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. A gestora e a consultoria do fundo recebem os webhooks de todas as liquidações; o cedente recebe apenas os das liquidações de ativos cedidos por ele.
Fluxo de status da liquidação
Nem toda mudança de status gera webhook. Só três situações notificam: a conclusão (settled) e o resultado de uma revisão da QI Tech (validated ou discarded). Para os demais status, use a consulta de liquidação.
Como ler o diagrama: contorno tracejado = status sem webhook · azul = webhook de andamento · verde = conclusão com sucesso · vermelho = descarte notificado.
| Status | Quando acontece | Webhook? |
|---|---|---|
validated | Na inserção, quando o valor pago está dentro da tolerância. | Não — é a resposta da própria inserção. |
pending_validation | Na inserção, quando o valor pago diverge do esperado além da tolerância. A liquidação aguarda revisão da QI Tech. | Não — é a resposta da própria inserção. |
validated (após revisão) | A QI Tech aprova uma liquidação que estava em pending_validation. | Sim |
discarded (após revisão) | A QI Tech descarta uma liquidação que estava em pending_validation ou validated, com o lote ainda aberto. | Sim |
waiting_send_to_queue / on_queue | O lote foi pago e a liquidação está sendo enviada à carteira do fundo. | Não |
settled | A liquidação foi conciliada na carteira. Status final de sucesso. | Sim |
inconsistent_asset | A carteira recusou o pagamento por inconsistência no ativo. A QI Tech trata o caso e reprocessa; o lote não chega a completed enquanto houver liquidação neste status. | Não |
discarded (sem aviso) | O lote foi descartado (as liquidações abertas são descartadas junto), ou a carteira recusou em definitivo uma liquidação de valor zero. | Não — no descarte do lote, o aviso é o webhook do lote com discarded. |
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). Se a liquidação atingir mais de um ativo, traz o primeiro. |
Identificação do ativo:
| Campo | Tipo | Descrição |
|---|---|---|
contract_number | string | Número do contrato. Presente se informado na criação; em CCBs e contratos, é preenchido a partir da carteira mesmo quando não informado. |
asset_external_id | string | external_id do ativo no sistema do parceiro. Presente se informado na criação; em CCBs e contratos, é preenchido a partir da carteira mesmo quando não informado. |
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. |
new_maturity_date | string | Nova data de vencimento. Presente em asset_extension. |
Campos de parcela — presentes apenas para tipos de liquidação por parcela (installment_* e 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": "11.222.333/0001-81",
"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": "11.222.333/0001-81",
"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 Aprovada após Revisão
Enviado quando a QI Tech aprova uma liquidação que estava em pending_validation. A liquidação segue para o processamento normal quando o lote for pago. O payload tem a mesma estrutura, com settlement_status igual a validated.
Liquidação Descartada
Enviado quando a QI Tech descarta uma liquidação após revisão — por exemplo, uma liquidação em pending_validation cujo valor não se confirma. Liquidações descartadas não geram movimentação financeira.
Descartes que acontecem junto com o descarte do lote, ou por rejeição definitiva da carteira para liquidações de valor zero, não geram este webhook. Veja o mapa de status.
{
"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": "11.222.333/0001-81",
"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"
}