Pular para o conteúdo principal

Manual de Cessão de Direitos Creditórios

Este manual descreve o passo a passo da cessão de direitos creditórios aos fundos administrados pela QI DTVM, as regras de negócio do produto e os pontos de atenção para uma integração mais rápida. O contrato de cada chamada (campos, respostas e erros) está na página de referência linkada em cada passo.

Pré-requisitos​

  1. Um contrato de cessão constituído e o produto respectivo ativado — veja Homologação de Cedente.
  2. Acesso pela gestora, pela consultoria ou pelo cedente do contrato. O que cada perfil pode chamar está no bloco Disponível em de cada página de referência.
  3. A chave do fundo cessionário (fund_class_key) e a chave da configuração de cessão (assignment_configuration_key), que compõem o caminho de todas as chamadas:
/trade_receivables/fund_class/{fund_class_key}/assignment_configuration/{assignment_configuration_key}

As configurações de cessão do fundo podem ser consultadas na Listagem de Configurações de Cessão.

Fluxo de estados​

A esteira de cessão tem duas entidades com máquinas de estado relacionadas: o lote (assignment) e os ativos (asset) dentro dele.

Fluxo de status do lote de cessão, do pending_assets_insertion até completed, com as saídas para denied e discarded

Lote — azul = status com webhook · tracejado = status sem webhook · verde = cessão concluída · vermelho = recusa ou descarte.

Fluxo de status do ativo, do pending_eligibility até completed, com as saídas para denied, registry_denied e discarded

Ativo — azul = status intermediário · verde = ativo encarteirado · vermelho = recusa ou descarte.

A lista completa de status está em Enumeradores de status do lote e Enumeradores de status do ativo.

Resumo da integração​

  1. Criação do lote.
  2. Inserção dos ativos.
  3. Envio da documentação.
  4. Encerramento da inserção.
  5. Elegibilidade dos ativos e do lote (automática, com webhooks).
  6. Aprovação da consultoria e/ou da gestora, quando a configuração exige.
  7. Assinatura do Termo de Cessão, pagamento e encarteiramento (automáticos, com webhooks).

1. Criação do lote​

O lote é criado com POST .../assignment — veja Criação do Lote de Cessão. Ele exige apenas um identificador gerado no seu sistema, o external_id, usado nas demais chamadas e nos webhooks.

O external_id do lote é único em toda a plataforma: uma segunda criação com o mesmo valor é recusada. Em caso de erro, reenvie a requisição: se o lote já existir, consulte-o.

2. Inserção dos ativos​

Cada ativo é inserido com POST .../assignment/{assignment_external_id}/asset, uma requisição por ativo. O corpo depende do tipo de ativo: CCB, duplicata, CT-e, contrato descontado e contrato parcelado. Também é possível ceder o lote inteiro por arquivo.

Valor do ativo e valor de compra​

Para entender a validação de valores, use esta notação:

  • [A] — valor de compra do ativo (total_purchase_value, na raiz do objeto): quanto o fundo paga pelo ativo;
  • [B] — soma dos ágios (total_value de cada item de premiums);
  • [C] — soma dos deságios (total_value de cada item de deductions);
  • [D] — valor do ativo, calculado como [D] = [A] − [B] + [C].

O valor do ativo [D] é conferido com o fluxo de parcelas informado. Divergências são recusadas na inserção, com os códigos listados na seção Erros da página de cada tipo de ativo.

Regras que valem para todos os tipos​

  • Tipo de ativo da configuração. Cada configuração de cessão aceita um único tipo de ativo; não é possível misturar, por exemplo, CCBs e duplicatas no mesmo lote.
  • Lote aberto. Ativos só entram enquanto o lote está em pending_assets_insertion.
  • external_id do ativo. É único dentro do lote: um segundo ativo com o mesmo external_id no mesmo lote é recusado. Em caso de erro, reenvie a requisição.
  • Originador. O originator_document_number precisa ser de um originador já cadastrado na QI Tech, com a mesma formatação do cadastro; caso contrário, a inserção devolve TRC000019.

Operações de crédito​

Operações de crédito (CCB) têm um principal em aberto e uma taxa de juros. As parcelas devem vir em ordem crescente de vencimento (maturity_date) e com installment_number sequencial. De acordo com o tipo de juros, informe o objeto de pré-fixado e/ou de pós-fixado. Os detalhes estão em Inserção de CCB.

3. Envio da documentação​

Os documentos de cada ativo são enviados com POST .../asset/{asset_external_id}/document, um por requisição, em Base64 — veja Inserção de Documentos do Ativo. O envio pode ser feito logo após a inserção do ativo, sem esperar o webhook pending_documentation.

Os documentos exigidos dependem do produto e estão nos campos required_documents e after_assignment_required_documents da configuração de cessão. O ativo só chega a pre_approved quando todos os documentos exigidos foram enviados e validados.

4. Encerramento da inserção​

Quando não quiser inserir mais ativos, encerre a inserção com PUT .../assignment/{assignment_external_id} e assignment_status = completed_assets_insertion — veja Encerrar Inserção de Ativos.

Não é necessário esperar o webhook de todos os ativos. O lote só segue para a elegibilidade quando todos os ativos estiverem com a análise concluída.

5. Elegibilidade dos ativos e do lote​

Cada ativo é analisado pelas regras de elegibilidade do fundo e o resultado chega por webhook do ativo, identificado pelo external_id do ativo. Aprovado, o ativo segue a esteira; reprovado, vai para denied e não compõe o lote.

Com todos os ativos analisados, o lote como um todo passa pela elegibilidade: mesmo com todos os ativos aprovados, o lote pode desenquadrar o fundo. O resultado chega por webhook do lote, identificado pelo external_id do lote. Reprovado, o lote vai para denied.

6. Aprovação​

Se a configuração de cessão exige aprovação manual, o lote fica em pending_consultant_approval e/ou pending_manager_approval até a decisão, feita com PUT .../assignment/{assignment_external_id} — veja Aprovação do Lote — ou pelo Portal do Gestor. Para retirar ativos antes de aprovar, veja Remoção de Ativos do Lote.

Com aprovação automática, o lote segue sem nenhuma ação.

7. Termo de Cessão, pagamento e encarteiramento​

Depois da aprovação, os ativos são registrados e formalizados, o Termo de Cessão é gerado e enviado para assinatura (pending_assignment_term_signature) — consulte-o em Documentos da Cessão.

Com o termo assinado, o cedente é pago (pending_payment) na conta de desembolso do lote. O valor é a soma do total_purchase_value dos ativos não reprovados. Confirmado o pagamento, os ativos são encarteirados (pending_assets_wallet_inclusion) e, ao final, o lote fica completed: a partir daí todos os ativos estão no estoque do fundo.

Lotes de substituição​

Em lotes criados numa configuração de recompra, insira também os ativos que o cedente vai recomprar, com POST .../assignment/{assignment_external_id}/repurchased_asset — veja Inserção de Ativo para Recompra. O valor dos ativos recomprados é abatido do pagamento.