Skip to main content

Manual de Cessão de Direitos Creditórios

Esse manual descreve o passo a passo envolvido na Cessão de Direitos Creditórios aos Fundos administrados pela QI DTVM. Além disso, é explicados as regras de negócio do produto e quais os principais pontos de atenção que o parceiro integrador deve ter para se ter uma integração mais rápida e eficiente.

Pré Requisitos

  1. Um Contrato de Cessão ter sido constituído e o Produto respectivo ter sido ativado (Vide APIs de Homologação de Cedente);

  2. Somente o Gestor do Fundo, o Cedente parte do Contrato e Originadores vinculados que podem acessar esse serviço.

  3. Ter armazenado a chave única de identificação do Fundo Cessionário (fund_class_key), e a chave única de identificação da Configuração de Cessão (assignment_configuration_key).

BASE_URL = "/fund_class/{fund_class_key}/assignment_configuration/{assignment_configuration_key}"
info

A BASE_URL será o caminho utilizado em todos os endpoints desta API.

Fluxo de Estados

A esteira de Cessão possui duas entidades principais onde as suas máquinas de estados possuem relações. De um lado temos o Lote, denominado assignment e de outro temos os Ativos, que chamamos de asset. Para o primeiro temos o seguinte fluxo:

Para o Ativo, temos o seguinte:

Resumo da Integração

Em suma, para chegarmos no Encarteiramento dos Ativos, temos o seguinte passo a passo:

  1. Criação do Lote;
  2. Inserção dos Ativos;
  3. Encerrar inserção de Ativos;
  4. Webhook de Elegibilidade dos Ativos;
  5. Envio da Documentação ;
  6. Webhook de Elegiblidade do Lote;
  7. Aprovação do Gestor;
  8. Assinatura do Termo de Cessão;
  9. Pagamento da Cessão;
  10. Encarteiramento dos Ativos;

1 - Criação do Lote;

Para a criação do Lote é exigido apenas um identificador único, gerado no sistema do parceiro integrador. Esse será o identificador utilizado tanto nas devoluções de Webhooks quanto nas rotas para as outras funcionalidades, que serão explicadas abaixo.

É de suma importância que esse identificador seja único, e o sistema da QI DTVM não permitirá que o parceiro mande duas vezes o mesmo Lote.

2 - Inserção dos Ativos;

A inserção de Ativos é o processo mais delicado de toda a integração. Nessa seção iremos explicar quais as regras de negócio envolvidas na criação dos Ativos, sejam aquelas que independem do tipo, ou aquelas que são específicas para um determinado tipo.

É muito importante para o entendimento dessa API, entender o conceito do Valor do Ativo e do Valor de Compra do Ativo. Para isso vamos utilizar a seguinte notação:

[A] como Valor de Compra do Ativo, fornecido no raiz do objeto, e significa o quanto o Fundo deve pagar por esse Ativo.

[B] como a soma total do Ágios da operação. Pode ser obtido através da soma de todos os total_values dos premiums fornecidos.

[C] como a soma total do Deságios da operação. Pode ser obtido através da soma de todos os total_values das deductions fornecidas.

[D] como o Valor do Ativo, que pode ser inferido através da seguinte fórmula.

Relação
[D] = [A] - [B] + [C]

2.1 - Regras Independentes de Tipo de Ativo

2.1.1 - Compatibilidade de Tipo de Ativo com Configuração de Cessão;

Toda Configuração de Cessão é única por tipo de ativo. Nunca será possível colocar num mesmo lote CCBs e e Duplicatas por exemplo. O produto ativado que gerou a assignment_configuration_key contém um tipo de ativo especifico, e esse será o único tipo aceito em uma dada Configuração. Caso isso seja violado retornaremos o seguinte erro:

Response Body
STATUS
400
Response Body
{
"code": "TRC000025"
}

2.1.2 - Inserção em Lotes Finalizados;

Caso tente-se inserir um ativo em lotes que já foram fechados, o parceiro integrador receberá o seguinte erro:

Response Body
STATUS
400
Response Body
{
"code": "TRC000022"
}

2.1.3 - Validação de Código Postal;

O código postal do objeto de endereço do tomador da operação deve ser válido. Portanto caso algum inexistente seja fornecido, a requisição não será aceita e devolverá o seguinte erro:

Response Body
STATUS
404
Response Body
{
"code": "TRC000070"
}

2.1.4 - Unicidade de External ID;

Um mesmo ativo não pode ser cedido 2 vezes pelo parceiro. Portanto caso esse ativo já exista em nossa base e não tenha sido descartado, o seguinte erro será levantado:

Response Body
STATUS
409
Response Body
{
"code": "TRC000054"
}

2.2 - Regras para Operações de Crédito

As Operações de Crédito são aquele ativos que derivam de um compromisso firmado por um Sacado, que toma dinheiro a uma determinada taxa, e honra um compromisso de pagamento de acordo com um determinado fluxo. Portanto esses ativos sempre possuem um principal em aberto, e uma taxa de juros que aumenta esse valor. A estrutura de dados exigida na Criação de uma Operação de Crédito encontra nesta página.

2.2.1 - Divergência Valor do Ativo vs Principal em Aberto;

Para uma Operação de Crédito é necessário que o Valor do Ativo seja sempre maior ou igual ao Principal em Aberto (Campo principal_value do Objeto de Operação de Crédito). O erro relacionado a essa regra de negócio é:

Response Body
STATUS
409
Response Body
{
"code": "TRC000054"
}

2.2.2 - Divergência Valor de Emissão vs Principal em Aberto;

O valor de Emissão do Contrato deve ser sempre maior ou igual ao principal em Aberto. O erro relacionado a essa regra de negócio é:

Response Body
STATUS
409
Response Body
{
"code": "TRC000054"
}

2.2.3 - Parcelas Sequenciais;

Todas as parcelas de uma operação de crédito devem ser ordenadas em ordem crescente de data de vencimento (maturity_date) e com os números (installment_number) sequenciais. Portanto se o fluxo começa com a parcela número 1, a próxima deve ser a 2, a seguinte a 3, e assim por diante.

Os erros relacionados a essas regras são respectivamente:

Response Body
STATUS
409
Response Body
{
"code": "TRC000054"
}
Response Body
STATUS
409
Response Body
{
"code": "TRC000054"
}

2.2.4 - Objetos pré e pós fixados;

De acordo com o tipo de juros (interest_rate_type) de uma operação, é preciso fornecer os objetos de pré e/ou pós fixados. Caso o tipo de juros seja pré fixado, é necessário fornecer apenas o objeto de pré fixado, enquanto na pós fixada, o objeto de pós fixado é obrigatório e o de pré fixado é opcional. Por exemplo, se a operação de

3 - Encerrar inserção de Ativos;

Após todos os ativos do Lote terem sido criados, o parceiro pode comandar o encerramento da Inserção de Ativos. Esse processo é importante para que o sistema da QI DTVM saiba que a partir desse momento, quando todos os ativos tiverem sido devidamente analisados pela Elegibilidade, e com toda a documentação fornecida, pode-se analisar a Elegibilidade do Lote como um todo.

info

Não é necessário esperar o Webhook de todos os Ativos para realizar essa ação. No momento em que não se desejar mais inserir ativos, pode-se executar esse comando.

4 - Webhook de Elegibilidade dos Ativos;

De acordo com o que os Ativos forem sendo analisados pelas regras de Elegibilidade do Fundo, o sistema devolve os Webhooks, 1 a 1. Esses Webhooks serão identificados com o identificador único do ativo, fornecido pelo parceiro no momento de criação.

Apenas duas possibilidades podem incorrer dessa análise, a aprovação dos ativos, ou a reprovação. Caso aconteça o primeiro, o Ativo irá seguir a sua esteira, ficando sujeito a inserção de documentos, caso contrário, ele irá para o Estado de descartado, e não irá seguir para os próximos passos.

5 - Envio da Documentação;

Com a aprovação de um determinado ativo na Elegibilidade, o parceiro pode seguir com a inserção dos documentos exigidos pelo produto. O envio deve ocorrer com uma requisição para cada documento necessário. O conteúdo será transmitido através de um Base64 do binário, portanto viabilizando que isso seja feito através de JSON, como todo o restante das APIs do nosso sistema.

Note que para realizar essa requisição é exigido, além do binário do arquivo, o tipo de documento desse arquivo. O Ativo só seguirá a esteira quando todos os documento exigidos forem enviados. Quando isso acontecer, este irá seguir para o estado de Pré Aprovado (pre_approved).

Aviso

Os documentos exigidos dependem do tipo de Produto e do Regulamento do Fundo. Isso pode ser obtido recuperando o Produto do Contrato de Cessão, que foi ativado para obtenção da assignment_configuration_key desse respectivo lote.

info

Não é necessário ter comandado o Encerramento da Inserção de Ativos. Caso queira vincular a lógica do Envio de Documentos ao Recebimento do Webhook, é totalmente possível e recomendado.

6 - Webhook de Elegiblidade do Lote;

Assim que um determinado Lote que ja teve a inserção de ativos encerrada, e todos os seus Ativos tiverem ou descartado ou pré-aprovados, ele irá seguir para uma análise de Elegibilidade do Lote todo. Mesmo que todos os Ativos ali tenha sido aprovados, pode ser que o Lote como um todo cause algum desenquadramento do Fundo. Por isso é necessário um segundo passo na execução da Elegibilidade.

De forma similar ao Ativo, podemos ter duas opções de resultado decorrido da Elegibilidade, a aprovação ou a reprovação. O resultado será informado através de um Webhook, mas dessa vez identificado com o external_id do Lote.

Caso o Lote seja reprovado, ele será descartado, e o processo finaliza-se. Caso contrário, ele seguirá para uma etapa de análise e aprovação do Gestor.

7 - Aprovação do Gestor;

A aprovação do Gestor deve ser feita através de uma requisição especifica, ou através do nosso Portal. Caso o Lote seja negado, ele será descartado e o processo finaliza-se. Caso contrário, o sistema providencia a geração do Termo de Cessão e o envia para assinatura, levando o Lote para o Estado pending_assignment_term_signature, e assim ficará ate que todas as partes relacionadas assinem o Documento.

8 - Assinatura do Termo de Cessão;

Uma vez assinado, enviamos um Webhook avisando que o Termo foi assinado e deve prosseguir para o pagamento, ficando, portanto, em pending_payment

9 - Pagamento da Cessão;

Nesse momento, o sistema paga o Cedente, o montante total da Cessão, que é a soma de todos os total_purchase_value dos ativos não descartados, na conta que foi informada no momento de ativação do Produto. Uma vez que esse pagamento for confirmado, enviamos um Webhook, e os ativos começam a serem encarteirados.

10 - Encarteiramento dos Ativos;

Por fim, assim que todos os ativos forem devidamente encarteirados, o Lote se tornará completed, e a partir desse momento o parceiro integrador tem a total certeza de que todos aqueles ativos já se encontram devidamente dentro do estoque do Fundo.