Recompra e Venda de Ativos
Esta seção documenta as APIs que viabilizam a venda e a recompra de direitos creditórios já encarteirados nos fundos administrados pela QI DTVM. O fluxo abrange desde a criação do lote até a baixa dos ativos da carteira do fundo.
Este serviço apenas baixa os ativos da carteira do fundo. Ele não envia dados para outras administradoras.
Existem dois conceitos fundamentais: o lote (assignment) e o ativo (asset). Um lote é composto por um ou mais ativos, e cada ativo inserido precisa já estar na carteira do fundo.
- 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, e daassignment_configuration_key(chave da configuração), informada na criação do lote:
/trade_resolve/fund_class/{fund_class_key}
Fluxo de venda/recompra
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.
Informe um external_id único, a data contábil do fundo e o documento de quem fará o pagamento ao fundo.
/trade_resolve/fund_class/{fund_class_key}/assignmentUma requisição por ativo, identificado pelo mesmo external_id com que foi encarteirado. O ativo precisa estar ativo na carteira.
.../assignment/{external_id}/assetQuando o preço de venda diverge mais de 5% do valor justo contábil, o ativo fica retido. A confirmação não está disponível na API: alinhe com integracao.dtvm@qitech.com.br.
É necessário ter ao menos um ativo não descartado. Você pode enviar number_of_assets e total_value para a API conferir os totais.
.../assignment/{external_id}O lote pode ser descartado até o encerramento. O descarte não está disponível na API: solicite a integracao.dtvm@qitech.com.br.
Termo interno: a QI Tech gera o documento e coleta as assinaturas. Termo externo: o lote fica em pending_signed_term_submission.
Com o termo assinado, a QI Tech registra a expectativa de pagamento na conta do fundo.
Confirmado o crédito, o lote passa a pending_wallet_sale e os ativos são baixados um a um. Quando todos concluem, o lote é encerrado.
Passo a passo
1. Criação do Lote
Crie o lote informando um identificador único (external_id), a data da operação (a data contábil atual do fundo) e o documento de quem fará o pagamento ao fundo. O lote nasce em pending_assets_insertion e é o contêiner de todos os ativos que serão baixados.
Acessar documentação da criação do lote
2. Inserção dos Ativos
Insira um ativo por requisição, identificando-o pelo mesmo external_id com que ele foi encarteirado (ou pelo número do contrato). O ativo precisa estar ativo na carteira do fundo no momento da inserção.
Acessar documentação da inserção de ativos
Se o preço de venda informado divergir em mais de 5% do valor justo contábil do ativo, o ativo não segue automaticamente: ele fica em pending_validation e exige uma confirmação antes de entrar na baixa. Divergências de até 5% seguem direto para pending_wallet_sale.
A confirmação não está disponível na API. Enquanto houver ativo em pending_validation, o lote não avança depois do encerramento. Se o seu fluxo pode gerar divergências acima de 5%, alinhe o procedimento com integracao.dtvm@qitech.com.br.
3. Encerramento do Lote
Após inserir todos os ativos, encerre o lote. É necessário ter ao menos um ativo não descartado. Opcionalmente, você pode enviar number_of_assets e total_value para que a API confira a quantidade e o valor total consolidados antes de aceitar o encerramento.
O lote só pode ser descartado até esta etapa, e o descarte do lote não está disponível na API: solicite a integracao.dtvm@qitech.com.br.
Acessar documentação do encerramento
4. Termo de Recompra
O responsável pela emissão do Termo de Recompra depende da configuração do lote:
- Termo interno — quando todos os ativos estão prontos para a baixa, a QI Tech gera o termo (
pending_documents_generation) e coleta as assinaturas das partes (pending_documents_signature). Nenhuma ação do integrador é necessária. - Termo externo — o lote passa para
pending_signed_term_submissione precisa receber o termo já assinado. O envio desse termo não está disponível namanager-api, naconsultant-apinem naassignor-api: antes de operar com termo externo, combine o envio com integracao.dtvm@qitech.com.br.
Em ambos os casos, com o termo assinado o lote passa a pending_payment, aguardando o crédito na conta do fundo.
5. Pagamento e Baixa dos Ativos
As etapas finais são automatizadas: a QI Tech confirma o crédito na conta do fundo, o lote passa a pending_wallet_sale, os ativos são baixados da carteira e, quando todos os ativos são concluídos, o lote é encerrado em completed.
Webhook
Quando o termo interno é assinado e o lote passa a pending_payment, a QI Tech envia o webhook trade_resolve.assignment_status_change aos agentes cadastrados na configuração do lote. É o único status que emite webhook: lotes com termo externo não recebem este evento. O cadastro é feito pela QI Tech: solicite em integracao.dtvm@qitech.com.br. Para validar a assinatura, veja Autenticação de webhooks.
{
"webhook_type": "trade_resolve.assignment_status_change",
"webhook_datetime": "2024-04-02T10:15:00Z",
"data": {
"assignment_external_id": "931e9437-d025-41ab-bb53-6b94e10fd361",
"assignment_new_status": "pending_payment",
"signed_term_url": "https://URL_TEMPORARIA_DO_TERMO"
}
}
| Campo | Descrição |
|---|---|
assignment_external_id | external_id do lote |
assignment_new_status | Novo status do lote: pending_payment |
signed_term_url | Link para baixar o termo assinado. Expira em 24 horas. |