Webhooks de Liquidação
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.
Para receber webhooks, é necessário ter uma URL de callback configurada junto à QI Tech. Entre em contato com integracao.dtvm@qitech.com.br para configurar.
Fluxo de status da liquidação
Cada liquidação inserida no lote fica em validated e só é processada depois que o lote de pagamento atinge paid. A partir daí ela chega a um dos dois status finais que geram webhook: settled ou discarded. O status validated não dispara notificação — ele é o resultado da própria chamada de inserção da liquidação.
Como ler o diagrama: contorno tracejado = status sem webhook · verde = conclusão com sucesso · vermelho = encerramento sem movimentação financeira.
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. |
fund_class_key | string | Chave do fundo na QI Tech (UUID). |
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. |
Demais campos ecoados quando informados:
| Campo | Tipo | Descrição |
|---|---|---|
if_code | string | Código de instrumento financeiro (B3). Presente se informado na criação da liquidação. |
participant_control_number | string | Número de controle do participante. Presente se informado na criação da liquidação. |
source_document_number | string | CPF ou CNPJ da contraparte financeira. Presente se informado na criação do lote. |
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. |
{
"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",
"fund_class_key": "8e2d1c4b-3a5f-4e6d-9b7c-1a2b3c4d5e6f",
"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
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.
{
"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",
"fund_class_key": "8e2d1c4b-3a5f-4e6d-9b7c-1a2b3c4d5e6f",
"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
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:
- Remoção manual antes do encerramento do lote — o parceiro integrador remove a liquidação via endpoint de remoção de liquidações enquanto o lote ainda está aberto.
- 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. - 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.
{
"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",
"fund_class_key": "8e2d1c4b-3a5f-4e6d-9b7c-1a2b3c4d5e6f",
"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"
}