# QI Tech — Investment-as-a-Service › Liquidação de Ativos Documentação da QI Tech em texto corrido, para colar em um LLM. Fonte: https://docs.qitech.com.br 9 página(s). Índice: - Inserção de Liquidações (/documentation/iaas/liquidacao_ativos/ativos/) - Remoção de Liquidações (/documentation/iaas/liquidacao_ativos/ativos/remocao_liquidacoes) - Webhooks de Liquidação (/documentation/iaas/liquidacao_ativos/ativos/webhook) - Fluxo de liquidação de ativos (/documentation/iaas/liquidacao_ativos/fluxo_liquidacao) - Liquidação de Ativos (/documentation/iaas/liquidacao_ativos/inicio) - Criação do Lote de Pagamento (/documentation/iaas/liquidacao_ativos/lote_pagamento/criacao) - Encerrar Inserção no Lote de Pagamento (/documentation/iaas/liquidacao_ativos/lote_pagamento/fechamento) - Listagem de Lotes de Pagamento (/documentation/iaas/liquidacao_ativos/lote_pagamento/listagem) - Webhooks do Lote de Pagamento (/documentation/iaas/liquidacao_ativos/lote_pagamento/webhook) --- # Inserção de Liquidações URL: /documentation/iaas/liquidacao_ativos/ativos/ Endpoint para inserir liquidações individuais em um lote de pagamento previamente criado. Cada liquidação representa um pagamento (total ou parcial) referente a um ativo da carteira do fundo — como liquidação de parcela, amortização, recompra ou pagamento de juros. :::info Liquidação vs Recompra Tanto a liquidação quanto a recompra de ativos são realizadas através deste endpoint. O campo `collection_origin_type` diferencia as duas operações: - `borrower` — para **liquidações** (pagamento realizado pelo sacado/devedor). - `assignor` — para **recompras** (pagamento realizado pelo cedente). ::: :::tip Onde estou no fluxo? Este é o **2º passo** do fluxo de liquidação. Antes deste passo, você deve ter [criado o lote de pagamento](/documentation/iaas/liquidacao_ativos/lote_pagamento/criacao). ::: ## Request ENDPOINT /settlement/fund_class/{fund_class_key}/payment_batch/{external_id}/settlement MÉTODO POST ### Path params | Parâmetro | Tipo | Descrição | |---|---|---| | `external_id` | string | O `external_id` do lote de pagamento onde a liquidação será inserida. | ```json title="Request Body" { "asset_type": "ccb", "total_value": 130.50, "external_id": "931e9437-d025-41ab-bb53-6b94e10fd361", "settlement_type": "installment_settlement", "contract_number": "0123456789/ABC", "installment_number": 1, "collection_date": "2025-01-01", "collection_origin_type": "borrower" } ``` ### Atributos do body | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `asset_type` | string | obrigatório | Tipo de ativo. Veja [enumeradores de `asset_type`](#enumeradores-de-asset_type). Máximo de 255 caracteres. | | `total_value` | number | obrigatório | Valor total do pagamento (com duas casas decimais). | | `external_id` | string | obrigatório | Chave única de identificação desta liquidação no sistema do parceiro integrador. Máximo de 50 caracteres. | | `settlement_type` | string | obrigatório | Tipo de liquidação. Veja [enumeradores de `settlement_type`](#enumeradores-de-settlement_type). Máximo de 50 caracteres. | | `collection_origin_type` | string | obrigatório | Determina se a operação é uma liquidação (`borrower`) ou uma recompra (`assignor`). Veja [enumeradores de `collection_origin_type`](#enumeradores-de-collection_origin_type). | | `contract_number` | string | opcional | Número do contrato referente ao ativo. Máximo de 50 caracteres. | | `asset_external_id` | string | opcional | Chave única de identificação do ativo no sistema, fornecida na cessão. Máximo de 50 caracteres. | | `asset_key` | string | opcional | Chave interna do ativo na QI Tech (UUID, 36 caracteres). | | `if_code` | string | opcional | Código de instrumento financeiro (B3). Máximo de 36 caracteres. | | `participant_control_number` | string | opcional | Número de controle do participante fornecido na cessão. Máximo de 50 caracteres. | | `installment_number` | integer | opcional | Número da parcela a ser paga. Obrigatório para tipos de liquidação por parcela. | | `installment_maturity_date` | string | opcional | Data de vencimento da parcela no formato `YYYY-MM-DD`. | | `installment_external_id` | string | opcional | Identificador externo da parcela. Máximo de 50 caracteres. | | `collection_date` | string | opcional | Data de pagamento no formato `YYYY-MM-DD`. Campo destinado para controle do integrador. | :::caution Atenção Os campos `asset_external_id`, `contract_number` e `asset_key` são formas alternativas de identificar o ativo no sistema. Informe **apenas um** deles — não envie múltiplos simultaneamente. ::: :::info Diferença entre external_id O campo `external_id` no corpo da requisição se refere ao identificador da **liquidação**. O campo `external_id` na URL se refere ao identificador do **lote de pagamento**. ::: **Enumeradores de `asset_type`:** | Valor | Descrição | |---|---| | `ccb` | Cédula de Crédito Bancário | | `cce` | Cédula de Crédito à Exportação | | `structured_ccb` | Cédula de Crédito Bancário Estruturada | | `structured_cce` | Cédula de Crédito à Exportação Estruturada | | `structured_nce` | Nota de Crédito à Exportação Estruturada | | `structured_cci` | Cédula de Crédito Imobiliário Estruturada | | `duplicata_mercantil` | Duplicata Mercantil | | `duplicata_servicos` | Duplicata de Serviços | | `discounted_contract` | Contrato | **Enumeradores de `settlement_type`:** | Valor | Descrição | |---|---| | `asset_settlement` | Liquidação total do ativo. | | `asset_amortization` | Amortização do ativo (carência). | | `fine_payment` | Pagamento de juros ou mora do ativo. | | `installment_settlement` | Liquidação de parcela. Obrigatório informar `installment_number`. | | `installment_amortization` | Amortização de parcela. Obrigatório informar `installment_number`. | | `installment_fine_payment` | Pagamento de juros ou mora de parcela. Obrigatório informar `installment_number`. | | `gloss` | Glosa de parcela. Obrigatório informar `installment_number`. | **Enumeradores de `collection_origin_type`:** | Valor | Descrição | |---|---| | `borrower` | Liquidação — pagamento realizado pelo sacado/devedor. | | `assignor` | Recompra — pagamento realizado pelo cedente. | ## Response STATUS 201 ```json title="Response Body" { "status": "validated", "total_value": 130.50, "external_id": "931e9437-d025-41ab-bb53-6b94e10fd361", "type": "installment_settlement", "settlement_key": "b2c3d4e5-f6a7-8901-abcd-ef1234567890", "installment_number": 1, "settlement_result": 0.0, "total_number_of_units": 1, "collection_origin_type": "borrower", "assets": [ { "asset_key": "f34e9437-d025-41ab-bb53-6b94e10fd361", "number_of_units": 1, "present_value": 1250.00, "installment_face_value": 130.50 } ] } ``` ### Atributos da resposta | Campo | Tipo | Descrição | |---|---|---| | `status` | string | Status da liquidação. Após inserção bem-sucedida, retorna `validated`. | | `total_value` | number | Valor total do pagamento. | | `external_id` | string | Chave externa da liquidação fornecida pelo parceiro. | | `type` | string | Tipo de liquidação. | | `settlement_key` | string | Identificador único da liquidação gerado pela QI Tech (UUID). | | `installment_number` | integer | Número da parcela. Presente quando aplicável. | | `settlement_result` | number | Resultado da liquidação. Presente quando calculado. | | `total_number_of_units` | integer | Quantidade total de unidades de ativo afetadas pela liquidação. | | `collection_origin_type` | string | Tipo de origem da cobrança (`borrower` ou `assignor`). Presente quando informado na requisição. | | `assets` | array | Lista de ativos afetados pela liquidação. Veja [Atributos de `assets`](#atributos-de-assets). | #### Atributos de `assets` | Campo | Tipo | Descrição | |---|---|---| | `asset_key` | string | Identificador único do ativo (UUID). | | `number_of_units` | integer | Quantidade de unidades do ativo. | | `present_value` | number | Valor presente do ativo em reais. | | `installment_face_value` | number | Valor de face da parcela. Presente quando aplicável. | | `installment_post_maturity_interest_value` | number | Valor de juros pós-vencimento da parcela. Presente quando aplicável. | | `installment_delay_interest_value` | number | Valor de juros de atraso da parcela. Presente quando aplicável. | | `installment_delay_fine_value` | number | Valor de multa de atraso da parcela. Presente quando aplicável. | ## Possíveis erros STATUS 404 **Lote de pagamento não encontrado** O `external_id` do lote informado na URL não corresponde a nenhum lote cadastrado para este fundo. Verifique se o identificador está correto. ```json { "title": "Payment batch not found", "description": "The Payment Batch with external_id {payment_batch_external_id} was not found", "translation": "O Lote de Pagamento com identificador externo {payment_batch_external_id} não foi encontrado", "code": "SET000010" } ``` STATUS 400 **Liquidação com external_id duplicado** Já existe uma liquidação cadastrada com o `external_id` informado neste lote. Cada liquidação deve ter um identificador único. Gere um novo `external_id` e tente novamente. ```json { "title": "Already Exists Settlement With External Id", "description": "The settlement with external_id {settlement_external_id} in payment batch with external id {payment_batch_external_id} already exists", "translation": "a liquidação com identificador {settlement_external_id} no lote de identificador {payment_batch_external_id} já existe", "code": "SET000013" } ``` ## Próximos passos Após inserir todas as liquidações desejadas, o fluxo continua com: 1. **[Encerramento do lote](/documentation/iaas/liquidacao_ativos/lote_pagamento/fechamento)** — sinalize que todas as liquidações foram inseridas para que o processamento seja iniciado. --- # Remoção de Liquidações URL: /documentation/iaas/liquidacao_ativos/ativos/remocao_liquidacoes Endpoint para descartar uma liquidação individual previamente inserida em um lote de pagamento. Somente liquidações em lotes que ainda não foram encerrados podem ser removidas. :::tip Quando utilizar Use este endpoint quando precisar remover uma liquidação incorreta ou indesejada antes de [encerrar o lote](/documentation/iaas/liquidacao_ativos/lote_pagamento/fechamento). Após o encerramento do lote, não é possível remover liquidações individuais. ::: ## Request ENDPOINT /settlement/fund_class/{fund_class_key}/payment_batch/{external_id}/settlement/{settlement_external_id} MÉTODO PUT ### Path params | Parâmetro | Tipo | Descrição | |---|---|---| | `external_id` | string | O `external_id` do lote de pagamento. | | `settlement_external_id` | string | O `external_id` da liquidação que será descartada. | ```json title="Request Body" { "status": "discarded" } ``` ### Atributos do body | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `status` | string | obrigatório | Novo status da liquidação. Para descartar, envie `discarded`. | ## Response STATUS 200 ```json title="Response Body" { "external_id": "931e9437-d025-41ab-bb53-6b94e10fd361", "status": "discarded" } ``` ### Atributos da resposta | Campo | Tipo | Descrição | |---|---|---| | `external_id` | string | Chave externa da liquidação fornecida pelo parceiro. | | `status` | string | Novo status da liquidação: `discarded`. | ## Possíveis erros STATUS 404 **Liquidação não encontrada** O `settlement_external_id` informado na URL não corresponde a nenhuma liquidação cadastrada neste lote. Verifique se os identificadores do lote e da liquidação estão corretos. ```json { "title": "Settlement not found", "description": "The Settlement with external_id {external_id} was not found", "translation": "A Liquidação com identificador externo {external_id} não foi encontrada", "code": "SET000011" } ``` STATUS 400 **Status inválido** O valor informado no campo `status` não é válido. Para remoção, utilize apenas `discarded`. ```json { "title": "Invalid status", "description": "The status given: {status} is not suported.", "translation": "O status: {status} não possui suporte.", "code": "SET000026" } ``` STATUS 400 **Lote já encerrado** O lote de pagamento já foi encerrado e não permite mais alterações nas liquidações. Não é possível remover liquidações de lotes que já passaram do status `pending_settlements_insertion`. ```json { "title": "Payment Batch Status mismatch", "description": "Payment batch of key: {payment_batch_key} with status: {current} was expected to be: {expected}", "translation": "O lote de pagamento com chave: {payment_batch_key} e com status: {current} não passou, era esperado que fosse: {expected}", "code": "SET000016" } ``` STATUS 400 **Status da liquidação incompatível** A liquidação está em um status que não permite ser descartada. Apenas liquidações com status `validated` podem ser removidas. ```json { "title": "Settlement type mismatch", "description": "The settlement given has the status: {current_status} and was expected: {expected_status}", "translation": "A liquidação com status: {current_status} era esperado ter: {expected_status}", "code": "SET000024" } ``` --- # Webhooks de Liquidação URL: /documentation/iaas/liquidacao_ativos/ativos/webhook Ao longo do processamento das liquidações, o sistema envia webhooks para notificar o parceiro integrador sobre mudanças de status de cada liquidação individual. Todos os webhooks possuem o tipo `settlement.settlement_status_change` e identificam a liquidação pelo `settlement_external_id` fornecido na criação. :::info Configuração de webhooks Para receber webhooks, é necessário ter uma URL de callback configurada junto à QI Tech. Entre em contato com [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br) para configurar. ::: ## Status com webhook O diagrama abaixo mostra os três status que geram webhooks ao parceiro integrador: ![Status da liquidação que geram webhooks](/img/diagrams/iaas-liquidacao-ativos-ativos-webhook.svg) ## Estrutura do webhook Todos os webhooks de liquidação seguem a mesma estrutura base: | Campo | Tipo | Descrição | |---|---|---| | `webhook_type` | string | Sempre `settlement.settlement_status_change`. | | `webhook_datetime` | string | Data e hora do evento no formato ISO 8601. | | `data` | array | Lista com os dados do evento. Veja tabela abaixo. | #### Atributos de cada objeto em `data` Os campos condicionais são ecoados diretamente do que foi enviado na criação da liquidação. O payload varia conforme o `settlement_type` e o método de identificação do ativo utilizado. **Campos sempre presentes:** | Campo | Tipo | Descrição | |---|---|---| | `payment_batch_external_id` | string | O `external_id` do lote de pagamento. | | `settlement_external_id` | string | O `external_id` da liquidação. | | `settlement_status` | string | Novo status da liquidação. | | `settlement_type` | string | Tipo de liquidação. | | `total_value` | number | Valor total da liquidação em reais. | | `fund_class_document_number` | string | CNPJ do fundo associado. | | `asset_key` | string | Chave interna do ativo na QI Tech (UUID). | **Identificação do ativo — apenas um dos campos abaixo estará presente, conforme o que foi informado na criação:** | Campo | Tipo | Descrição | |---|---|---| | `contract_number` | string | Número do contrato. Presente se informado na criação. | | `asset_external_id` | string | `external_id` do ativo no sistema do parceiro. Presente se informado na criação. | **Campos de parcela — presentes apenas para tipos de liquidação por parcela (`installment_settlement`, `installment_amortization`, `installment_fine_payment`, `gloss`):** | Campo | Tipo | Descrição | |---|---|---| | `installment_number` | integer | Número da parcela. | | `installment_maturity_date` | string | Data de vencimento da parcela no formato `YYYY-MM-DD`. Presente quando informado na criação. | | `installment_external_id` | string | `external_id` da parcela. Presente quando informado na criação. | ```json title="Estrutura padrão do webhook" { "data": [ { "payment_batch_external_id": "ac597f90-a13e-4f78-86f0-11c66f5fa6d6", "settlement_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b", "settlement_status": "STATUS", "settlement_type": "installment_settlement", "total_value": 130.50, "fund_class_document_number": "60.910.091/0001-24", "asset_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c", "contract_number": "0032226586/NNT", "installment_number": 3 } ], "webhook_type": "settlement.settlement_status_change", "webhook_datetime": "2024-04-23T15:08:30Z" } ``` --- ## Eventos por status ### Liquidação Concluída STATUS settled Enviado quando a liquidação é processada com sucesso e o valor foi devidamente conciliado na carteira do fundo. Este é o status final de uma liquidação bem-sucedida — a partir desse momento, a movimentação financeira está efetivada. ```json title="Webhook Body" { "data": [ { "payment_batch_external_id": "ac597f90-a13e-4f78-86f0-11c66f5fa6d6", "settlement_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b", "settlement_status": "settled", "settlement_type": "installment_settlement", "total_value": 130.50, "fund_class_document_number": "60.910.091/0001-24", "asset_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c", "contract_number": "0032226586/NNT", "installment_number": 3, } ], "webhook_type": "settlement.settlement_status_change", "webhook_datetime": "2024-04-23T15:08:30Z" } ``` --- ### Liquidação Descartada STATUS discarded Enviado quando a liquidação é descartada do fluxo de processamento. Liquidações descartadas não geram movimentação financeira. Existem três situações que causam esse status: 1. **Remoção manual antes do encerramento do lote** — o parceiro integrador remove a liquidação via endpoint de [remoção de liquidações](/documentation/iaas/liquidacao_ativos/ativos/remocao_liquidacoes) enquanto o lote ainda está aberto. 2. **Descarte interno após revisão** — a equipe QI Tech descarta uma liquidação que estava em revisão manual (`pending_validation`), por exemplo por inconsistência nos dados. 3. **Rejeição** — durante o processamento, a carteira do fundo retorna uma rejeição definitiva para uma liquidação com valor zero. Nesses casos, o sistema determina que reprocessar a liquidação produziria o mesmo resultado e a descarta. ```json title="Webhook Body" { "data": [ { "payment_batch_external_id": "ac597f90-a13e-4f78-86f0-11c66f5fa6d6", "settlement_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b", "settlement_status": "discarded", "settlement_type": "installment_settlement", "total_value": 130.50, "fund_class_document_number": "60.910.091/0001-24", "asset_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c", "contract_number": "0032226586/NNT", "installment_number": 3 } ], "webhook_type": "settlement.settlement_status_change", "webhook_datetime": "2024-04-23T15:08:30Z" } ``` --- --- # Fluxo de liquidação de ativos URL: /documentation/iaas/liquidacao_ativos/fluxo_liquidacao Esta página oferece uma visão holística do fluxo de liquidação de ativos já encarteirados no fundo: desde a criação do lote de pagamento até a conclusão das liquidações e a atualização da carteira. Acompanhe a evolução dos **status do lote**, dos **status de cada liquidação** e dos **webhooks** em cada etapa. :::tip Como usar este fluxograma Passe o mouse sobre cada etapa para ver os detalhes do endpoint e acessar a documentação completa. As trilhas coloridas mostram simultaneamente o que acontece com o lote, com cada liquidação e quais webhooks você receberá após o processamento. ::: {` .cf-legend{display:flex;flex-wrap:wrap;gap:8px;margin-bottom:24px} .cf-legend-item{display:flex;align-items:center;gap:6px;font-size:0.8rem;font-weight:600} .cf-legend-dot{width:12px;height:12px;border-radius:3px} .cf-step{position:relative;margin-bottom:4px} .cf-step:not(:last-child)::after{content:'';display:block;width:2px;height:16px;margin:0 auto;background:var(--ifm-color-emphasis-300)} .cf-card{border:1.5px solid var(--ifm-color-emphasis-200);border-radius:10px;padding:16px 20px;transition:box-shadow 0.2s,border-color 0.2s;cursor:pointer;background:var(--ifm-background-surface-color,var(--ifm-background-color))} .cf-card:hover{box-shadow:0 4px 16px rgba(0,0,0,0.08);border-color:var(--ifm-color-primary)} .cf-card-header{display:flex;align-items:center;gap:10px;flex-wrap:wrap} .cf-num{width:28px;height:28px;border-radius:50%;display:flex;align-items:center;justify-content:center;font-size:0.8rem;font-weight:800;color:#fff;flex-shrink:0} .cf-num-int{background:#3b82f6} .cf-num-qi{background:#8b5cf6} .cf-num-ges{background:#d946ef} .cf-title{font-size:1rem;font-weight:700;color:var(--ifm-font-color-base)} .cf-actor{font-size:0.7rem;font-weight:700;padding:2px 8px;border-radius:12px;margin-left:auto} .cf-actor-int{background:rgba(59,130,246,0.12);color:#2563eb} .cf-actor-qi{background:rgba(139,92,246,0.12);color:#7c3aed} .cf-actor-ges{background:rgba(217,70,239,0.12);color:#c026d3} .cf-subtitle{font-size:0.82rem;color:var(--ifm-color-emphasis-700);margin-top:4px;margin-left:38px} .cf-tracks{display:flex;flex-wrap:wrap;gap:8px;margin-top:12px;margin-left:38px} .cf-track{display:inline-flex;align-items:center;gap:5px;padding:3px 10px;border-radius:6px;font-size:0.75rem;font-family:var(--ifm-font-family-monospace);border:1px solid} .cf-track-lote{background:rgba(34,197,94,0.1);color:#16a34a;border-color:rgba(34,197,94,0.25)} .cf-track-ativo{background:rgba(59,130,246,0.1);color:#2563eb;border-color:rgba(59,130,246,0.25)} .cf-track-wh{background:rgba(245,158,11,0.1);color:#b45309;border-color:rgba(245,158,11,0.25)} .cf-track-err{background:rgba(239,68,68,0.1);color:#dc2626;border-color:rgba(239,68,68,0.25)} .cf-track-label{font-family:var(--ifm-font-family-base);font-weight:700;font-size:0.7rem;text-transform:uppercase;letter-spacing:0.03em} .cf-new{font-weight:700} .cf-unchanged{opacity:0.5} .cf-details{max-height:0;overflow:hidden;opacity:0;transition:max-height 0.35s ease,opacity 0.25s ease,margin 0.3s ease;margin-left:38px} .cf-card:hover .cf-details{max-height:300px;opacity:1;margin-top:14px;padding-top:12px;border-top:1px solid var(--ifm-color-emphasis-200)} .cf-endpoint{font-family:var(--ifm-font-family-monospace);font-size:0.82rem;padding:8px 12px;border-radius:6px;background:var(--ifm-color-emphasis-100);margin-bottom:8px;display:flex;align-items:center;gap:8px;flex-wrap:wrap} .cf-method{font-weight:800;padding:2px 6px;border-radius:4px;font-size:0.72rem} .cf-method-post{background:#f97316;color:#fff} .cf-method-put{background:#3b82f6;color:#fff} .cf-method-get{background:#22c55e;color:#fff} .cf-desc{font-size:0.82rem;color:var(--ifm-color-emphasis-700);margin-bottom:8px} .cf-link{font-size:0.82rem;font-weight:600;color:var(--ifm-color-primary);text-decoration:none} .cf-link:hover{text-decoration:underline} .cf-branch{margin-top:12px;margin-left:38px;display:flex;gap:12px;flex-wrap:wrap} .cf-branch-path{flex:1;min-width:200px;border-radius:8px;padding:10px 14px;border:1.5px dashed} .cf-branch-ok{border-color:rgba(34,197,94,0.4);background:rgba(34,197,94,0.05)} .cf-branch-err{border-color:rgba(239,68,68,0.4);background:rgba(239,68,68,0.05)} .cf-branch-label{font-size:0.78rem;font-weight:700;margin-bottom:4px} .cf-branch-label-ok{color:#16a34a} .cf-branch-label-err{color:#dc2626} html[data-theme='dark'] .cf-track-lote{background:rgba(34,197,94,0.15);color:#4ade80;border-color:rgba(34,197,94,0.3)} html[data-theme='dark'] .cf-track-ativo{background:rgba(59,130,246,0.15);color:#60a5fa;border-color:rgba(59,130,246,0.3)} html[data-theme='dark'] .cf-track-wh{background:rgba(245,158,11,0.15);color:#fbbf24;border-color:rgba(245,158,11,0.3)} html[data-theme='dark'] .cf-track-err{background:rgba(239,68,68,0.15);color:#f87171;border-color:rgba(239,68,68,0.3)} html[data-theme='dark'] .cf-branch-ok{background:rgba(34,197,94,0.08)} html[data-theme='dark'] .cf-branch-err{background:rgba(239,68,68,0.08)} html[data-theme='dark'] .cf-actor-int{background:rgba(59,130,246,0.2);color:#60a5fa} html[data-theme='dark'] .cf-actor-qi{background:rgba(139,92,246,0.2);color:#a78bfa} html[data-theme='dark'] .cf-actor-ges{background:rgba(217,70,239,0.2);color:#e879f9} `} ## Legenda Agente Integrador QI Tech (automático) Status do Lote Status da Liquidação Webhook ## Fluxograma 1 Criação do lote de pagamento Agente Integrador Cria um lote com identificador único ( external_id ) por fundo, contendo conta de crédito opcional e demais metadados. Lote: pending_settlements_insertion POST /settlement/fund_class/{fund_class_key}/payment_batch O lote fica pronto para receber liquidações. Ver documentação completa → 2 Inserção das liquidações Agente Integrador Insere cada liquidação (parcela, amortização, liquidação total, etc.) no lote. Repita para todas as operações desejadas. Lote: pending_settlements_insertion Liquidação: validated POST /settlement/fund_class/{fund_class_key}/payment_batch/{external_id}/settlement Cada liquidação recebe status validated após inserção bem-sucedida. Não há webhook neste momento; os webhooks são enviados após o encerramento e o processamento. Ver documentação completa → 3 Remoção de liquidação (opcional) Agente Integrador Antes de encerrar o lote, você pode descartar uma liquidação inserida por engano. Somente liquidações em status validated podem ser removidas. Lote: pending_settlements_insertion Liquidação: validated Removeu uma liquidação discarded A liquidação deixa de entrar no processamento. Não aplicável Pule este passo se não precisar remover nenhuma liquidação. PUT /settlement/fund_class/{fund_class_key}/payment_batch/{external_id}/settlement/{settlement_external_id} Corpo: {"status": "discarded"} . Após o encerramento do lote não é possível remover liquidações individuais. Ver documentação completa → 4 Encerramento do lote Agente Integrador Sinaliza que todas as liquidações foram inseridas (e ajustadas) e que o processamento pode iniciar — ou descarta o lote inteiro. Lote: pending_payment / discarded Liquidação: validated (ou discarded) Processar lote pending_payment É necessário ter ao menos uma liquidação no lote. Descartar lote discarded Nenhuma liquidação será processada. Fluxo encerrado. PUT /settlement/fund_class/{fund_class_key}/payment_batch/{external_id} Envie {"batch_status": "pending_payment"} para encerrar e processar, ou {"batch_status": "discarded"} para descartar o lote. Ver documentação completa → 5 Pagamento do lote QI Tech A QI Tech confirma o pagamento do lote. Em seguida as liquidações individuais são processadas e os webhooks de liquidação são disparados. Lote: paid Webhook: payment_batch_status_change Webhook settlement.payment_batch_status_change com status paid . Opcionalmente, use a listagem de lotes para acompanhar o lote. GET /settlement/fund_class/{fund_class_key}/payment_batches Consulta opcional para acompanhar o lote por status ou data de referência. Webhooks do lote → 6 Conclusão das liquidações QI Tech Cada liquidação processada com sucesso é conciliada na carteira do fundo. Este é o status final de sucesso por liquidação. Liquidação: settled Webhook: settlement_status_change Webhook settlement.settlement_status_change com settlement_status settled para cada liquidação concluída (após o pagamento do lote). Ver documentação de webhooks de liquidação → --- ## Resumo de webhooks A tabela abaixo consolida todos os webhooks da API de liquidação: | # | Tipo do webhook | Campo de status | Valor | Momento no fluxo | Ação esperada | |---|---|---|---|---|---| | 1 | `settlement.payment_batch_status_change` | `status` | `paid` | Após confirmação do pagamento do lote (passo 5) | A partir deste evento, as liquidações são processadas e os webhooks por liquidação passam a ser enviados. | | 2 | `settlement.settlement_status_change` | `settlement_status` | `settled` | Por liquidação, após processamento bem-sucedido (passo 6) | Liquidação concluída e conciliada na carteira. | | 3 | `settlement.settlement_status_change` | `settlement_status` | `discarded` | Por liquidação, quando descartada por remoção manual, descarte interno ou rejeição permanente da carteira | Liquidação não será processada. Nenhuma movimentação financeira é gerada. | | 4 | `settlement.payment_batch_status_change` | `status` | `completed` | Após todas as liquidações do lote atingirem status final (`settled` ou `discarded`) | O ciclo do lote está encerrado. Todas as liquidações foram processadas. | | 5 | `settlement.payment_batch_status_change` | `status` | `discarded` | Quando o lote é descartado (por solicitação do parceiro, descarte automático ou falha no cancelamento em conta caixa) | Nenhuma liquidação do lote será processada. | :::info Payload do webhook de liquidação O payload do webhook `settlement_status_change` varia conforme os dados enviados na criação da liquidação: - **Identificação do ativo:** apenas um dos campos `contract_number` ou `asset_external_id` estará presente, conforme o método de identificação usado na criação. Nunca os dois simultaneamente. - **Campos de parcela** (`installment_number`, `installment_maturity_date`, `installment_external_id`): presentes somente para tipos de liquidação por parcela — `installment_settlement`, `installment_amortization`, `installment_fine_payment` e `gloss`. Ausentes em tipos de ativo total (`asset_settlement`, `asset_amortization`, `fine_payment`). Para a estrutura completa dos payloads, consulte [Webhooks do lote de pagamento](/documentation/iaas/liquidacao_ativos/lote_pagamento/webhook) e [Webhooks de liquidação](/documentation/iaas/liquidacao_ativos/ativos/webhook). ::: --- # Liquidação de Ativos URL: /documentation/iaas/liquidacao_ativos/inicio Esta seção documenta as APIs que viabilizam o processo de Liquidação de Ativos para Fundos de Investimento administrados pela QI CTVM. Por meio dessas APIs, é possível registrar pagamentos de parcelas, amortizações, recompras e demais eventos de liquidação dos ativos que compõem a carteira do fundo. :::tip Contexto A liquidação de ativos descrita nesta seção aplica-se exclusivamente a direitos creditórios (CCBs, duplicatas, contratos, etc.) já encarteirados no fundo. Letras do Tesouro, Debêntures e outros ativos de renda fixa não se aplicam a esse fluxo. ::: :::info Pré-requisitos - Para ter acesso a esses serviços, entre em contato com [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br) para liberação dos ambientes de Homologação (Sandbox) e Produção. - Você precisará da `fund_class_key` (chave do fundo), que compõe a URL base de todos os endpoints desta API: ``` /settlement/fund_class/{fund_class_key} ``` ::: ## Fluxo de liquidação O diagrama abaixo mostra o caminho principal, as bifurcações e o status resultante de cada etapa. Passe o mouse em um nó para ver o endpoint e clique para abrir a documentação. :::tip Fluxo completo Para todas as transições de status, os payloads dos webhooks e os caminhos de exceção, consulte o [Fluxo de liquidação de ativos](/documentation/iaas/liquidacao_ativos/fluxo_liquidacao). ::: ## Passo a passo ### 1. Criação do Lote de Pagamento Crie um lote de pagamento informando um identificador único (`external_id`). O lote será o contêiner para todas as liquidações que serão processadas em conjunto. **[Acessar documentação da criação do lote](/documentation/iaas/liquidacao_ativos/lote_pagamento/criacao)** ### 2. Inserção das Liquidações Adicione as liquidações ao lote criado. Cada liquidação deve ser inserida individualmente, informando o tipo de ativo, o valor, o tipo de liquidação e os identificadores necessários. **[Acessar documentação da inserção de liquidações](/documentation/iaas/liquidacao_ativos/ativos)** Enquanto o lote não é encerrado, uma liquidação inserida por engano pode ser removida. **[Acessar documentação da remoção de liquidações](/documentation/iaas/liquidacao_ativos/ativos/remocao_liquidacoes)** ### 3. Encerramento do Lote Após inserir todas as liquidações, encerre o lote para que o processamento interno seja iniciado. A conciliação de caixa e a atualização do portfólio de ativos serão realizadas automaticamente. No mesmo endpoint é possível, alternativamente, descartar o lote inteiro — nesse caso nenhuma liquidação é processada. **[Acessar documentação do encerramento](/documentation/iaas/liquidacao_ativos/lote_pagamento/fechamento)** ### 4. Acompanhamento via Webhooks Acompanhe o progresso através dos webhooks: - **[Webhooks do lote de pagamento](/documentation/iaas/liquidacao_ativos/lote_pagamento/webhook)** — notificações sobre o status do lote. - **[Webhooks das liquidações](/documentation/iaas/liquidacao_ativos/ativos/webhook)** — notificações sobre o status individual de cada liquidação. :::info Processamento automático O procedimento de conciliação de caixa e a atualização do portfólio de ativos é feito de forma automática pela API após o encerramento do lote. ::: --- # Criação do Lote de Pagamento URL: /documentation/iaas/liquidacao_ativos/lote_pagamento/criacao Este é o **primeiro passo** do fluxo de liquidação de ativos. A criação do lote de pagamento reserva um agrupamento onde as liquidações que serão processadas serão inseridas nas etapas seguintes. :::info Pré-requisitos Antes de criar um lote, você precisa ter em mãos a `fund_class_key` — chave única do fundo no qual os ativos serão liquidados. Essa chave compõe o endpoint utilizado em toda esta API: ``` /settlement/fund_class/{fund_class_key} ``` Para mais detalhes sobre o fluxo completo, consulte a [página de introdução](/documentation/iaas/liquidacao_ativos/inicio). ::: :::caution Atenção Cada lote deve possuir um `external_id` **único** por fundo. O sistema não permitirá a criação de dois lotes com o mesmo identificador. ::: ## Request ENDPOINT /settlement/fund_class/{fund_class_key}/payment_batch MÉTODO POST ```json title="Request Body" { "external_id": "41d6ff41-1dac-4df7-9e50-d15210ec57f3", "description": "PAGAMENTOS - ABC - 2025-01-01", "account": { "account_number": "123456", "account_digit": "0", "account_branch": "0001", "financial_institution_code": "329" } } ``` ### Atributos do body | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `external_id` | string | obrigatório | Chave única de identificação deste lote no sistema do parceiro integrador. Máximo de 50 caracteres. | | `description` | string | opcional | Descrição do lote de liquidação. Máximo de 255 caracteres. | | `account` | object | opcional | Dados da conta onde a liquidação será creditada. Quando não informado, a liquidação será gerada na conta principal do fundo. Veja [Atributos de `account`](#atributos-de-account). | | `account_key` | string | opcional | Chave da conta onde a liquidação será creditada (UUID, 36 caracteres). Alternativa ao campo `account`. | | `reference_date` | string | opcional | Data de referência da liquidação no formato `YYYY-MM-DD`. | | `end_to_end_id` | string | opcional | Identificador end-to-end do PIX da contraparte financeira da liquidação. Máximo de 32 caracteres. | | `source_document_number` | string | opcional | CPF ou CNPJ da contraparte financeira da liquidação, com pontuação (ex: `12.345.678/0001-90` ou `123.456.789-00`). | :::caution Atenção Os campos `account` e `account_key` não devem ser passados simultaneamente. Caso nenhum dos dois seja informado, a liquidação será gerada na conta principal do fundo. As informações da conta devem ser referentes a uma conta pertencente ao fundo. ::: #### Atributos de `account` | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `account_number` | string | obrigatório | Número da conta. Máximo de 20 caracteres. | | `account_digit` | string | obrigatório | Dígito da conta. 1 caractere. | | `account_branch` | string | obrigatório | Agência da conta. Máximo de 4 caracteres. | | `financial_institution_code` | string | obrigatório | Código da instituição financeira. Máximo de 20 caracteres. | ## Response STATUS 201 ```json title="Response Body" { "external_id": "41d6ff41-1dac-4df7-9e50-d15210ec57f3", "description": "PAGAMENTOS - ABC - 2025-01-01", "fund_class": { "name": "FUNDO DE INVESTIMENTO EM DIREITOS CREDITÓRIOS", "manager": { "name": "EXEMPLO CAPITAL", "manager_key": "a7498c6c-1893-42ec-a8f3-bc6ad0c6b52c", "document_number": "45.585.471/0001-47" }, "fund_class_key": "4b8377d0-58ec-479f-8ee9-9f963d5c47ad", "document_number": "60.910.091/0001-24" }, "payment_batch_key": "63f0dbec-e9c4-4943-929e-1d47b9edbb0b", "status": "pending_settlements_insertion", "reference_date": "2025-01-01", "account_key": "5e621ba2-b4ac-4ddd-9893-82d220e1577e" } ``` ### Atributos da resposta | Campo | Tipo | Descrição | |---|---|---| | `external_id` | string | A mesma chave externa fornecida na requisição. | | `description` | string | Descrição do lote. | | `fund_class` | object | Dados do fundo associado ao lote. Veja [Atributos de `fund_class`](#atributos-de-fund_class). | | `payment_batch_key` | string | Identificador único do lote gerado pela QI Tech (UUID). | | `status` | string | Status inicial do lote. Sempre retorna `pending_settlements_insertion`, indicando que o lote está pronto para receber liquidações. | | `reference_date` | string | Data de referência da liquidação no formato `YYYY-MM-DD`. | | `account_key` | string | Chave da conta associada ao lote (UUID). | #### Atributos de `fund_class` | Campo | Tipo | Descrição | |---|---|---| | `name` | string | Nome do fundo. | | `manager` | object | Dados do gestor do fundo. Veja [Atributos de `manager`](#atributos-de-manager). | | `fund_class_key` | string | Chave única do fundo (UUID). | | `document_number` | string | CNPJ do fundo. | #### Atributos de `manager` | Campo | Tipo | Descrição | |---|---|---| | `name` | string | Nome do gestor. | | `manager_key` | string | Chave única do gestor (UUID). | | `document_number` | string | CNPJ do gestor. | ## Possíveis erros STATUS 404 **Fundo não encontrado** A `fund_class_key` informada na URL não corresponde a nenhum fundo cadastrado. Verifique se a chave está correta. ```json { "title": "Fund Class not Found", "description": "Fund Class with key {fund_class_key} was not found.", "translation": "A Classe de Fundo com chave {fund_class_key} nao foi encontrado.", "code": "SET000005" } ``` STATUS 409 **External ID duplicado** Já existe um lote cadastrado com o `external_id` informado. Cada lote deve ter um identificador único. Gere um novo `external_id` e tente novamente. ```json { "title": "Payment batch external id already exists", "description": "The Payment Batch with external id {payment_batch_external_id} already exists", "translation": "O Lote de Pagamento com identificador externo {payment_batch_external_id} ja existe", "code": "SET000009" } ``` STATUS 400 **Data contábil divergente** O lote está sendo criado em uma data diferente da data contábil vigente do fundo. Verifique a data contábil do fundo e tente novamente. ```json { "title": "Bad Request", "description": "Payment batch is being created in {accounting_date}, while fund is in {fund_class_accounting_date}", "translation": "Payment batch esta sendo criado em {accounting_date}, fundo esta em {fund_class_accounting_date}", "code": "SET000044" } ``` STATUS 404 **Conta não encontrada** A `account_key` informada não corresponde a nenhuma conta cadastrada. Verifique se a chave está correta e se a conta pertence ao fundo. ```json { "title": "Account not found", "description": "The account with key ({account_key}) was not found.", "translation": "A conta com chave({account_key}) não foi encontrada.", "code": "SET000009" } ``` ## Próximos passos Após criar o lote, o fluxo continua com: 1. **[Inserção das liquidações](/documentation/iaas/liquidacao_ativos/ativos)** — adicione as liquidações (pagamentos de parcelas, amortizações, etc.) ao lote. 2. **[Encerramento do lote](/documentation/iaas/liquidacao_ativos/lote_pagamento/fechamento)** — sinalize que todas as liquidações foram inseridas para que o processamento seja iniciado. --- # Encerrar Inserção no Lote de Pagamento URL: /documentation/iaas/liquidacao_ativos/lote_pagamento/fechamento Após inserir todas as liquidações desejadas no lote, utilize este endpoint para sinalizar que a inserção foi concluída e o processamento pode ser iniciado. Também é possível descartar o lote por completo. :::tip Onde estou no fluxo? Este é o **3º passo** do fluxo de liquidação. Antes deste passo, você deve ter: 1. [Criado o lote de pagamento](/documentation/iaas/liquidacao_ativos/lote_pagamento/criacao) 2. [Inserido as liquidações](/documentation/iaas/liquidacao_ativos/ativos) ::: ## Request ENDPOINT /settlement/fund_class/{fund_class_key}/payment_batch/{external_id} MÉTODO PUT ### Path params | Parâmetro | Tipo | Descrição | |---|---|---| | `external_id` | string | O `external_id` informado na criação do lote. | ```json title="Request Body" { "batch_status": "pending_payment" } ``` ### Atributos do body | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `batch_status` | string | obrigatório | Status para o qual o lote será atualizado. Veja [enumeradores](#enumeradores-de-batch_status) abaixo. | **Enumeradores de `batch_status`:** | Valor | Descrição | |---|---| | `pending_payment` | Encerra a inserção e inicia o processamento do lote. | | `discarded` | Descarta o lote inteiro. Nenhuma liquidação será processada. | ## Response STATUS 200 ```json title="Response Body" { "external_id": "41d6ff41-1dac-4df7-9e50-d15210ec57f3", "status": "pending_payment" } ``` ### Atributos da resposta | Campo | Tipo | Descrição | |---|---|---| | `external_id` | string | Chave externa do lote fornecida pelo parceiro. | | `status` | string | Novo status do lote. | ## Possíveis erros STATUS 404 **Lote não encontrado** O `external_id` informado na URL não corresponde a nenhum lote cadastrado para este fundo. Verifique se o identificador está correto. ```json { "title": "Payment batch not found", "description": "The Payment Batch with external_id {payment_batch_external_id} was not found", "translation": "O Lote de Pagamento com identificador externo {payment_batch_external_id} não foi encontrado", "code": "SET000010" } ``` STATUS 400 **Status inválido** O valor informado no campo `batch_status` não é válido. Utilize apenas `pending_payment` ou `discarded`. ```json { "title": "Invalid status", "description": "The status given: {status} is not suported.", "translation": "O status: {status} não possui suporte.", "code": "SET000026" } ``` STATUS 400 **Lote sem liquidações** Você tentou encerrar o lote, mas ele ainda não possui nenhuma liquidação inserida. É necessário [inserir pelo menos uma liquidação](/documentation/iaas/liquidacao_ativos/ativos) antes de encerrar o lote. ```json { "title": "Payment Batch with no settlement", "description": "Payment batch of external_id: {payment_batch_external_id} have no settlements to be settled", "translation": "O lote de pagamento com identificador: {payment_batch_external_id} não possui liquidações", "code": "SET000017" } ``` ## Próximos passos Após encerrar o lote, o processamento é iniciado automaticamente. Acompanhe o resultado através dos webhooks: 1. **[Webhooks do lote de pagamento](/documentation/iaas/liquidacao_ativos/lote_pagamento/webhook)** — notificação quando o lote for pago. 2. **[Webhooks das liquidações](/documentation/iaas/liquidacao_ativos/ativos/webhook)** — notificação individual de cada liquidação processada. --- # Listagem de Lotes de Pagamento URL: /documentation/iaas/liquidacao_ativos/lote_pagamento/listagem Endpoint de consulta paginada que retorna os lotes de pagamento de uma determinada classe de fundo. Utilize os filtros disponíveis para buscar lotes por status ou data de referência. ## Request ENDPOINT /settlement/fund_class/{fund_class_key}/payment_batches MÉTODO GET ### Query params | Parâmetro | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `status` | string | opcional | Filtra por um status específico do lote. Consulte os [enumeradores de status](#enumeradores-de-status-do-lote). | | `reference_date` | string | opcional | Filtra por data de referência no formato `YYYY-MM-DD`. | | `page` | integer | opcional | Número da página (começa em 0). Padrão: `0`. | | `limit` | integer | opcional | Quantidade de registros por página. Padrão: `10`. Máximo: `50`. | ```python title="Exemplo de chamada" GET /settlement/fund_class/{fund_class_key}/payment_batches?status=completed&reference_date=2025-01-01&page=0&limit=10 ``` ## Response STATUS 200 ```json title="Response Body" { "data": [ { "description": "LOTE DE LIQUIDAÇÃO 08/08", "fund_class": { "name": "FUNDO DE INVESTIMENTO EM DIREITOS CREDITÓRIOS", "manager": { "name": "EXEMPLO CAPITAL", "manager_key": "a7498c6c-1893-42ec-a8f3-bc6ad0c6b52c", "document_number": "45.585.471/0001-47" }, "fund_class_key": "a3ecf74b-d280-4d3c-aefd-cb223dbf0451", "document_number": "60.910.091/0001-24" }, "payment_batch_key": "50859e88-544c-4c79-a7aa-d373d90aa571", "status": "completed", "external_id": "5910209c-9cb5-4569-9069-f2dbc8060434", "reference_date": "2025-08-08", "account_key": "5e621ba2-b4ac-4ddd-9893-82d220e1577e", "total_value": 143.18 } ], "limit": 10, "page": 0, "is_last_page": false } ``` ### Atributos da resposta | Campo | Tipo | Descrição | |---|---|---| | `data` | array | Lista de objetos de lote de pagamento. Veja tabela abaixo. | | `page` | integer | Número da página atual. | | `limit` | integer | Quantidade de registros por página. | | `is_last_page` | boolean | Indica se esta é a última página de resultados. | #### Atributos de cada lote (objetos dentro de `data`) | Campo | Tipo | Descrição | |---|---|---| | `description` | string | Descrição do lote. | | `fund_class` | object | Dados do fundo associado ao lote. Consulte os [atributos de `fund_class`](/documentation/iaas/liquidacao_ativos/lote_pagamento/criacao#atributos-de-fund_class) na página de Criação. | | `payment_batch_key` | string | Identificador único do lote (UUID). | | `status` | string | Status atual do lote. Consulte os [enumeradores de status](#enumeradores-de-status-do-lote) abaixo. | | `external_id` | string | Chave externa fornecida pelo parceiro. | | `reference_date` | string | Data de referência no formato `YYYY-MM-DD`. | | `account_key` | string | Chave da conta associada ao lote (UUID). | | `total_value` | number | Valor total das liquidações do lote em reais. Pode não estar presente caso o lote ainda não tenha sido processado. | ## Enumeradores de status do lote | Status | Descrição | |---|---| | `pending_settlements_insertion` | Lote criado, aguardando inserção de liquidações. | | `pending_payment` | Lote encerrado, aguardando processamento do pagamento. | | `paid` | Pagamento do lote realizado. | | `completed` | Processamento do lote finalizado com sucesso. | | `discarded` | Lote descartado. | --- # Webhooks do Lote de Pagamento URL: /documentation/iaas/liquidacao_ativos/lote_pagamento/webhook Ao longo do fluxo de liquidação, o sistema envia webhooks para notificar o parceiro integrador sobre mudanças de status do lote de pagamento. Todos os webhooks possuem o tipo `settlement.payment_batch_status_change` e identificam o lote pelo `external_id` fornecido na criação. :::info Configuração de webhooks Para receber webhooks, é necessário ter uma URL de callback configurada junto à QI Tech. Entre em contato com [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br) para configurar. ::: ## Status com webhook O diagrama abaixo mostra os três status que geram webhooks ao parceiro integrador: ![Status do lote de pagamento que geram webhooks](/img/diagrams/iaas-liquidacao-ativos-lote-pagamento-webhook.svg) ## Estrutura do webhook Todos os webhooks do lote de pagamento seguem a mesma estrutura: | Campo | Tipo | Descrição | |---|---|---| | `webhook_type` | string | Sempre `settlement.payment_batch_status_change`. | | `webhook_datetime` | string | Data e hora do evento no formato ISO 8601. | | `data` | object | Dados do evento. Veja tabela abaixo. | #### Atributos de `data` | Campo | Tipo | Descrição | |---|---|---| | `external_id` | string | O `external_id` do lote informado na criação. | | `status` | string | Novo status do lote. | | `fund_class_document_number` | string | CNPJ do fundo associado ao lote. | ```json title="Estrutura padrão do webhook" { "data": { "external_id": "57efbd9f-0917-4c79-9a43-bc8f1039fc78", "status": "STATUS", "fund_class_document_number": "60.910.091/0001-24" }, "webhook_type": "settlement.payment_batch_status_change", "webhook_datetime": "2024-04-23T15:08:30Z" } ``` --- ## Eventos por status ### Lote Pago STATUS paid Enviado quando o pagamento do lote é confirmado pela QI Tech. A partir desse momento, as liquidações individuais são processadas em sequência e os respectivos [webhooks de liquidação](/documentation/iaas/liquidacao_ativos/ativos/webhook) são enviados conforme cada uma for concluída. ```json title="Webhook Body" { "data": { "external_id": "57efbd9f-0917-4c79-9a43-bc8f1039fc78", "status": "paid", "fund_class_document_number": "60.910.091/0001-24" }, "webhook_type": "settlement.payment_batch_status_change", "webhook_datetime": "2024-04-23T15:08:30Z" } ``` --- ### Lote Concluído STATUS completed Enviado quando todas as liquidações do lote atingiram um status final (`settled` ou `discarded`). Este é o status terminal do lote após a conclusão bem-sucedida do ciclo de liquidação. Ao receber este evento, o parceiro integrador pode considerar o lote integralmente processado. ```json title="Webhook Body" { "data": { "external_id": "57efbd9f-0917-4c79-9a43-bc8f1039fc78", "status": "completed", "fund_class_document_number": "60.910.091/0001-24" }, "webhook_type": "settlement.payment_batch_status_change", "webhook_datetime": "2024-04-23T15:08:30Z" } ``` --- ### Lote Descartado STATUS discarded Enviado quando o lote é descartado. Isso pode ocorrer por solicitação explícita do parceiro integrador no [encerramento do lote](/documentation/iaas/liquidacao_ativos/lote_pagamento/fechamento), por descarte automático de lotes em aberto pela QI Tech, ou após cancelamento junto à conta caixa. Nenhuma liquidação associada ao lote será processada após este status. ```json title="Webhook Body" { "data": { "external_id": "57efbd9f-0917-4c79-9a43-bc8f1039fc78", "status": "discarded", "fund_class_document_number": "60.910.091/0001-24" }, "webhook_type": "settlement.payment_batch_status_change", "webhook_datetime": "2024-04-23T15:08:30Z" } ```