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.

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 para configurar.

Status com webhook

O diagrama abaixo mostra os três status que geram webhooks ao parceiro integrador:

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.

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.

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 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.

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"
}

---