Liquidação de Ativos
Esta seção documenta as APIs que viabilizam o processo de Liquidação de Ativos para Fundos de Investimento administrados pela QI DTVM. Por meio dessas APIs, é possível registrar pagamentos de parcelas, amortizações, recompras e demais eventos de liquidação dos ativos que compõem a carteira do fundo.
A liquidação de ativos descrita nesta seção aplica-se exclusivamente a direitos creditórios (CCBs, duplicatas, contratos, etc.) já encarteirados no fundo. Letras do Tesouro, Debêntures e outros ativos de renda fixa não se aplicam a esse fluxo.
- Para ter acesso a esses serviços, entre em contato com integracao.dtvm@qitech.com.br para liberação dos ambientes de sandbox e produção.
- Você precisará da
fund_class_key(chave do fundo), que compõe a URL base de todos os endpoints desta API:
/settlement/fund_class/{fund_class_key}
Como enviar as baixas
| Caminho | Como funciona | Onde |
|---|---|---|
| Pela API, liquidação a liquidação | Criação do lote de pagamento, uma requisição por liquidação e encerramento do lote. É o fluxo detalhado nesta seção | API de integração |
| Por arquivo | Um único arquivo com todas as liquidações: CNAB 444 ou CSV | Portal do gestor/consultor |
Se você já recebe o retorno CNAB do banco cobrador, pode enviá-lo direto. Veja Baixa por Arquivo e o Layout CNAB 444 — Baixa.
Fluxo de liquidação
O diagrama abaixo mostra o caminho principal, as bifurcações e o status resultante de cada etapa. Passe o mouse em um nó para ver o endpoint e clique para abrir a documentação.
Contêiner de todas as liquidações que serão processadas em conjunto, identificado por um external_id único.
/settlement/fund_class/{fund_class_key}/payment_batchUma requisição por liquidação, informando tipo de ativo, valor, tipo de liquidação e identificadores.
.../payment_batch/{external_id}/settlementDefine o batch_status. É necessário ter ao menos uma liquidação inserida.
.../payment_batch/{external_id}Nenhuma liquidação é processada e nenhuma movimentação financeira é gerada. Fluxo encerrado.
A QI Tech confirma o pagamento. A partir deste evento as liquidações individuais passam a ser processadas.
Ver documentação →Cada liquidação é conciliada na carteira do fundo e notificada individualmente por webhook.
Ver documentação →Todas as liquidações atingiram status final e o ciclo do lote está encerrado.
Ver documentação →Para todas as transições de status, os payloads dos webhooks e os caminhos de exceção, consulte o Fluxo de liquidação de ativos.
Passo a passo
1. Criação do Lote de Pagamento
Crie um lote de pagamento informando um identificador único (external_id). O lote será o contêiner para todas as liquidações que serão processadas em conjunto.
Acessar documentação da criação do lote
Para conferir um lote já criado, use a consulta de lote.
2. Inserção das Liquidações
Adicione as liquidações ao lote criado. Cada liquidação deve ser inserida individualmente, informando o tipo de ativo, o valor, o tipo de liquidação e os identificadores necessários.
Acessar documentação da inserção de liquidações
Não há endpoint para remover uma liquidação individual. Se uma liquidação foi inserida por engano, descarte o lote no encerramento e crie um novo. Para conferir uma liquidação já inserida, use a consulta de liquidação.
3. Encerramento do Lote
Após inserir todas as liquidações, encerre o lote para que o processamento interno seja iniciado. A conciliação de caixa e a atualização do portfólio de ativos serão realizadas automaticamente. No mesmo endpoint é possível, alternativamente, descartar o lote inteiro — nesse caso nenhuma liquidação é processada.
Acessar documentação do encerramento
4. Acompanhamento via Webhooks
Acompanhe o progresso através dos webhooks:
- Webhooks do lote de pagamento — notificações sobre o status do lote.
- Webhooks das liquidações — notificações sobre o status individual de cada liquidação.
O procedimento de conciliação de caixa e a atualização do portfólio de ativos é feito de forma automática pela API após o encerramento do lote.