Webhooks do Lote de Pagamento
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.
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 do lote
O lote passa pelos status abaixo até o encerramento. Três deles geram webhook: paid, completed e discarded. Os dois primeiros — pending_settlements_insertion e pending_payment — são resultado das suas próprias chamadas de criação e encerramento do lote e não disparam notificação.
Como ler o diagrama: contorno tracejado = status sem webhook · azul = webhook de andamento · verde = encerramento com sucesso · vermelho = encerramento sem processamento.
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 | Identificador do lote. Veja Como o external_id é formado. |
status | string | Novo status do lote. |
fund_class_document_number | string | CNPJ do fundo associado ao lote. |
fund_class_key | string | Chave do fundo na QI Tech (UUID). |
payment_batch_key | string | Identificador único do lote gerado pela QI Tech (UUID). |
reference_date | string | Data de referência do lote, no formato AAAA-MM-DD. |
total_value | number | Valor total do lote em reais. Presente depois que o total é apurado, no encerramento do lote — ou seja, nos webhooks de paid e completed. |
description | string | Descrição do lote. Presente quando o lote possui descrição. |
{
"data": {
"external_id": "57efbd9f-0917-4c79-9a43-bc8f1039fc78",
"status": "STATUS",
"fund_class_document_number": "60.910.091/0001-24",
"fund_class_key": "8e2d1c4b-3a5f-4e6d-9b7c-1a2b3c4d5e6f",
"payment_batch_key": "c1f0a9d8-7b6e-4c5d-8a9b-0f1e2d3c4b5a",
"reference_date": "2024-04-23",
"total_value": 4520.75,
"description": "PAGAMENTOS - ABC - 2024-04-23"
},
"webhook_type": "settlement.payment_batch_status_change",
"webhook_datetime": "2024-04-23T15:08:30Z"
}
Como o external_id é formado
O external_id é a chave de correlação entre o lote na QI CTVM e o seu próprio controle. A origem do valor depende de como o lote foi criado:
| Origem do lote | Valor do external_id |
|---|---|
| Criação via API | Exatamente o external_id que você informou no corpo da requisição. |
| Arquivo de liquidação enviado via SFTP | O nome do arquivo sem a extensão. |
O webhook não traz um campo com o nome do arquivo. Para correlacionar o evento ao arquivo que você enviou, compare o external_id com o nome do arquivo sem a extensão:
| Arquivo enviado | external_id do lote |
|---|---|
liquidacoes_20260811_001.REM | liquidacoes_20260811_001 |
CNAB_BAIXAS_liquidacoes_20260811_001.REM | liquidacoes_20260811_001 |
Como mostra a segunda linha, o prefixo CNAB_BAIXAS_, quando presente, também é removido.
O arquivo de retorno com as inconsistências encontradas no processamento, quando gerado, segue a mesma convenção — retorno_liquidacoes_20260811_001.csv.
Eventos por status
Lote Pago
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 são enviados conforme cada uma for concluída.
{
"data": {
"external_id": "57efbd9f-0917-4c79-9a43-bc8f1039fc78",
"status": "paid",
"fund_class_document_number": "60.910.091/0001-24",
"fund_class_key": "8e2d1c4b-3a5f-4e6d-9b7c-1a2b3c4d5e6f",
"payment_batch_key": "c1f0a9d8-7b6e-4c5d-8a9b-0f1e2d3c4b5a",
"reference_date": "2024-04-23",
"total_value": 4520.75,
"description": "PAGAMENTOS - ABC - 2024-04-23"
},
"webhook_type": "settlement.payment_batch_status_change",
"webhook_datetime": "2024-04-23T15:08:30Z"
}
Lote Concluído
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.
Para identificar a que lote o evento se refere, use o external_id — veja Como o external_id é formado.
{
"data": {
"external_id": "57efbd9f-0917-4c79-9a43-bc8f1039fc78",
"status": "completed",
"fund_class_document_number": "60.910.091/0001-24",
"fund_class_key": "8e2d1c4b-3a5f-4e6d-9b7c-1a2b3c4d5e6f",
"payment_batch_key": "c1f0a9d8-7b6e-4c5d-8a9b-0f1e2d3c4b5a",
"reference_date": "2024-04-23",
"total_value": 4520.75,
"description": "PAGAMENTOS - ABC - 2024-04-23"
},
"webhook_type": "settlement.payment_batch_status_change",
"webhook_datetime": "2024-04-23T15:08:30Z"
}
Lote Descartado
Enviado quando o lote é descartado. Isso pode ocorrer por solicitação explícita do parceiro integrador no encerramento do lote, 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.
Quando o lote é descartado antes do encerramento, o valor total não chega a ser apurado e o campo total_value não vem no payload.
{
"data": {
"external_id": "57efbd9f-0917-4c79-9a43-bc8f1039fc78",
"status": "discarded",
"fund_class_document_number": "60.910.091/0001-24",
"fund_class_key": "8e2d1c4b-3a5f-4e6d-9b7c-1a2b3c4d5e6f",
"payment_batch_key": "c1f0a9d8-7b6e-4c5d-8a9b-0f1e2d3c4b5a",
"reference_date": "2024-04-23",
"description": "PAGAMENTOS - ABC - 2024-04-23"
},
"webhook_type": "settlement.payment_batch_status_change",
"webhook_datetime": "2024-04-23T15:08:30Z"
}