Fluxo de liquidação de ativos

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.

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.

Legenda

Agente Integrador

QI Tech (automático)

Status do Lote

Status da Liquidação

Webhook

Fluxograma

1

Criação do lote de pagamentoAgente 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çõesAgente Integrador

Insere cada liquidação (parcela, amortização, liquidação total, etc.) no lote. Repita para todas as operações desejadas.

Lote: pending_settlements_insertionLiquidação: validated / pending_validation

POST /settlement/fund_class/{fund_class_key}/payment_batch/{external_id}/settlement

Cada liquidação recebe validated ou, se o valor pago divergir do esperado além da tolerância, pending_validation (revisão pela QI Tech; o resultado chega por webhook). Não há como remover uma liquidação individual: se necessário, descarte o lote e crie outro.

Ver documentação completa →

3

Encerramento do loteAgente Integrador

Sinaliza que todas as liquidações foram inseridas e que o processamento pode iniciar — ou descarta o lote inteiro.

Lote: pending_payment / pending_validation / pending_discardLiquidação: validated

Processar lote

pending_payment

É necessário ter ao menos uma liquidação no lote. Se houver liquidação em revisão, o lote fica em pending_validation e segue sozinho para pending_payment ao fim da revisão.

Descartar lote

pending_discard → discarded

Nenhuma liquidação será processada. O webhook do lote com discarded confirma o fim do fluxo.

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 →

4

Pagamento do loteQI 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: paidWebhook: payment_batch_status_change

Webhook settlement.payment_batch_status_change com status paid. Opcionalmente, use a consulta de lote para acompanhar o lote.

GET /settlement/fund_class/{fund_class_key}/payment_batch/{external_id}

Consulta opcional do status atual do lote.

Webhooks do lote →

5

Conclusão das liquidaçõesQI Tech

Cada liquidação processada com sucesso é conciliada na carteira do fundo. Este é o status final de sucesso por liquidação. Se a carteira recusar o ativo, a liquidação fica em inconsistent_asset (sem webhook) até a QI Tech tratá-la.

Liquidação: settledWebhook: 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 4)	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 5)	Liquidação concluída e conciliada na carteira.
3	settlement.settlement_status_change	settlement_status	validated	Por liquidação, quando a QI Tech aprova uma liquidação que estava em pending_validation	Nenhuma: a liquidação segue o fluxo normal.
4	settlement.settlement_status_change	settlement_status	discarded	Por liquidação, quando a QI Tech a descarta após revisão	Liquidação não será processada. Nenhuma movimentação financeira é gerada.
5	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.
6	settlement.payment_batch_status_change	status	discarded	Quando o descarte do lote é concluído (por solicitação do parceiro ou descarte automático de lotes em aberto)	Nenhuma liquidação do lote será processada. As liquidações abertas são descartadas sem webhook próprio.

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: contract_number e asset_external_id aparecem quando informados na criação; em CCBs e contratos, os dois são preenchidos a partir da carteira.
• Campos de parcela (installment_number, installment_maturity_date, installment_external_id): presentes somente para tipos de liquidação por parcela (installment_* e gloss).

Para a estrutura completa dos payloads, consulte Webhooks do lote de pagamento e Webhooks de liquidação.