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

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

Cada liquidação recebe status validated após inserção bem-sucedida. Não há webhook neste momento; os webhooks são enviados após o encerramento e o processamento.

Ver documentação completa →

3

Remoção de liquidação (opcional)Agente Integrador

Antes de encerrar o lote, você pode descartar uma liquidação inserida por engano. Somente liquidações em status validated podem ser removidas.

Lote: pending_settlements_insertionLiquidação: validated

Removeu uma liquidação

discarded

A liquidação deixa de entrar no processamento.

Não aplicável

Pule este passo se não precisar remover nenhuma liquidação.

PUT /settlement/fund_class/{fund_class_key}/payment_batch/{external_id}/settlement/{settlement_external_id}

Corpo: {"status": "discarded"}. Após o encerramento do lote não é possível remover liquidações individuais.

Ver documentação completa →

4

Encerramento do loteAgente Integrador

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

Lote: pending_payment / discardedLiquidação: validated (ou discarded)

Processar lote

pending_payment

É necessário ter ao menos uma liquidação no lote.

Descartar lote

discarded

Nenhuma liquidação será processada. Fluxo encerrado.

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 →

5

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 listagem de lotes para acompanhar o lote.

GET /settlement/fund_class/{fund_class_key}/payment_batches

Consulta opcional para acompanhar o lote por status ou data de referência.

Webhooks do lote →

6

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.

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 5)	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 6)	Liquidação concluída e conciliada na carteira.
3	settlement.settlement_status_change	settlement_status	discarded	Por liquidação, quando descartada por remoção manual, descarte interno ou rejeição permanente da carteira	Liquidação não será processada. Nenhuma movimentação financeira é gerada.
4	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.
5	settlement.payment_batch_status_change	status	discarded	Quando o lote é descartado (por solicitação do parceiro, descarte automático ou falha no cancelamento em conta caixa)	Nenhuma liquidação do lote será processada.

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: apenas um dos campos contract_number ou asset_external_id estará presente, conforme o método de identificação usado na criação. Nunca os dois simultaneamente.
• Campos de parcela (installment_number, installment_maturity_date, installment_external_id): presentes somente para tipos de liquidação por parcela — installment_settlement, installment_amortization, installment_fine_payment e gloss. Ausentes em tipos de ativo total (asset_settlement, asset_amortization, fine_payment).

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