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
-
Um Contrato de Cessão ter sido constituído e o Produto respectivo ter sido ativado (Vide APIs de Homologação de Cedente);
-
Somente o Gestor do Fundo, o Cedente parte do Contrato e Originadores vinculados que podem acessar esse serviço.
-
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}"
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:
- Criação do Lote;
- Inserção dos Ativos;
- Encerrar inserção de Ativos;
- Webhook de Elegibilidade dos Ativos;
- Envio da Documentação ;
- Webhook de Elegiblidade do Lote;
- Aprovação do Gestor;
- Assinatura do Termo de Cessão;
- Pagamento da Cessão;
- 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.
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
{
"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
{
"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
{
"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
{
"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
{
"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
{
"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
{
"code": "TRC000054"
}
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.
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).
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.
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.