Ficha técnica

Esta API tem como objetivo permitir a criação e o acompanhamento de operações de crédito (ativos) e de suas cessões para um FIDC. O fluxo é dividido em duas grandes etapas: a admissão do ativo, onde o ativo é validado, precificado e sua elegibilidade é verificada, e a cessão, que é a operação de venda/transferência do ativo para o fundo, envolvendo reserva de limite, registro do trade e desembolso.

Conceitos

Conceito	Descrição
Ativo (Asset)	Representação do crédito em si (um recebível ou um empréstimo/CCB), com suas parcelas, taxas, partes envolvidas e demais características.
Admissão	Processo automático executado após a criação do ativo: busca de contrapartes, validação dos dados, verificação de elegibilidade, etc.
Cessão (Cession)	A operação de venda do ativo para o fundo. É no momento da cessão que em que dispara a reserva de limite, o envio do trade, desembolso, etc.
Desembolso	Processo automático que executa o pagamento do fundo por aquele ativo.
Grupo de Desembolso	Recurso opcional que permite agrupar vários ativos — com mesmo sacado, cedente, fundo e data de desembolso — para que o desembolso ocorra de uma só vez, quando o grupo for liberado.

Fluxo Geral

O fluxo pode ser realizado de duas maneiras:

1. Em duas etapas (recomendado para análise prévia): o cedente/gestor cria o ativo (POST /assets) e aguarda o resultado da admissão. Com o ativo elegível, decide então se realiza a cessão (POST /cessions informando o assetId). Esse formato é útil quando o gestor precisa analisar questões de elegibilidade, precificação, etc antes de ceder o ativo ao fundo.

2. Em etapa única: o cedente/gestor envia a cessão já com os dados completos do ativo (POST /cessions com o objeto asset). Nesse caso o ativo é criado e admitido automaticamente e, se aprovado, a cessão prossegue sozinha. Se a admissão falhar, a cessão é rejeitada com o motivo.

📘 Etapas configuráveis por fundo

As etapas executadas na admissão e na cessão dependem da configuração de cada fundo. Por exemplo, um fundo pode não ter a etapa de elegibilidade prévia ou não ter desembolso. O fluxo se adapta automaticamente, pulando as etapas desabilitadas.

Criar Ativo

Cria o ativo e inicia a admissão de forma assíncrona — a resposta é imediata (202 Accepted) e retorna o identificador do ativo, mas o resultado da admissão deve ser acompanhado pela consulta de status ou retorno via webhook.

Criar um ativo não significa cedê-lo ao fundo. Esta rota serve justamente para que o cedente/gestor verifique se o ativo é elegível antes de decidir realizar a cessão.

• Criar ativo

// exemplo de resposta:
{
 "assetId": "0524b1ed-6a78-4f00-8394-543ffcd188f0"
}

📘 Idempotência

A criação de ativos é idempotente pela combinação de identification (identificador externo) + fundTaxId (CNPJ do fundo). Se o ativo já existir e estiver em admissão ou elegível, a mesma resposta com o assetId existente é retornada, sem duplicação. Se o ativo existir mas estiver inelegível, a criação é rejeitada e a correção deve ser feita pela rota de atualização (PUT).

Consultar Status do Ativo

Consulta a situação do ativo na admissão. Não é necessário ter realizado a cessão — esta rota funciona a qualquer momento após a criação e reflete apenas a fase de admissão. A busca pode ser feita de duas formas:

Forma de busca	Parâmetros
Pelo identificador interno	id do ativo (retornado na criação).
Pelo identificador externo	externalId do ativo (campo identification informado na criação) + fundTaxId (CNPJ do fundo). O fundTaxId é obrigatório neste caso.

• Consultar status do ativo

// exemplo de resposta:
{
 "id": "0524b1ed-6a78-4f00-8394-543ffcd188f0",
 "externalId": "NOTA-2024-000123",
 "status": "Ineligible"
}

Status	Descrição
Pending	Admissão em andamento (contrapartes, validação e/ou elegibilidade em execução)
Eligible	Ativo aprovado na admissão e pronto para ser cedido
Ineligible	Ativo reprovado — consulte o motivo pela rota de motivo de rejeição da operação (operation-rejection-reason)

Atualizar Ativo (Correção)

Quando o ativo é reprovado na admissão (problema de validação ou elegibilidade), o cedente/gestor pode corrigir os dados e reenviar através desta rota. Ao atualizar, a admissão é reprocessada automaticamente do início e o status volta para Pending.

• Atualizar ativo

❗️ Ativo com cessão ativa não pode ser corrigido

Se já existir uma cessão em andamento ou concluída com sucesso para o ativo, a atualização será rejeitada. Isso ocorre porque, após a cessão, a operação já foi encaminhada para registro e desembolso, e alterações no ativo não são mais permitidas.

Criar Cessão

A cessão é a operação de venda do ativo para o fundo. É nesta etapa que ocorrem a verificação de elegibilidade da negociação, a reserva de limite, o envio do trade para registro e o desembolso (quando configurado para o fundo), etc. O processamento é assíncrono e o acompanhamento deve ser feito pelas rotas de consulta de status ou retorno via webhook.

Existem duas formas de criar a cessão — apenas uma delas deve ser usada:

Forma	Quando usar
Informando assetId	O ativo já foi criado previamente e está elegível. Fluxo em duas etapas, quando o cedente/gestor analisou a elegibilidade antes de ceder.
Informando o objeto asset	Cria o ativo e a cessão em uma única chamada. A cessão aguarda a admissão do ativo e prossegue automaticamente se ele for aprovado.

• Criar cessão

Regras importantes:

• O ativo precisa estar elegível para ser cedido (exceto no formato de etapa única, em que a cessão aguarda a admissão).
• Não é permitido criar mais de uma cessão caso a cessão atual esteja em andamento ou concluída com sucesso.
• Se o ativo pertencer a um grupo de desembolso, a cessão é automaticamente vinculada ao grupo e o desembolso ocorrerá em lote, junto com os demais ativos do grupo, quando este for liberado.

Consultar Cessão

Consulta a situação de uma cessão. De forma semelhante à consulta de status do ativo, retorna os identificadores (externo e interno) e o status atual da cessão. A busca pode ser feita de duas formas:

Forma de busca	Parâmetros
Pelo identificador interno	id da cessão (gerado pela plataforma).
Pelo identificador externo	externalId da cessão + fundTaxId (CNPJ do fundo). O fundTaxId é obrigatório neste caso, pois o identificador externo só é único dentro de um mesmo fundo.

• Consultar cessão

// exemplo de resposta:
{
 "id": "8bce6cfc-dcd4-473b-9fae-60ef3f60ec11",
 "externalId": "REG-2024-000123",
 "status": "Ceded"
}

Grupos de Desembolso

O grupo de desembolso é um recurso opcional que permite agrupar vários ativos para que seus desembolsos sejam liberados de uma só vez. É útil quando o parceiro precisa consolidar pagamentos de diversos ativos num único momento.

❗️ O grupo de desembolso é referente apenas à transação financeira. As cessões dos ativos ainda precisam ser feitas de forma individual. O recurso financeiro só é disponibilizado quando todas cessões do grupo forem recebidas e validadas.

Criar Grupo de Desembolso

Cria um único grupo de desembolso a partir de um identificador externo (definido pelo gestor/parceiro) e de uma lista de ativos. A data de desembolso e a conta bancária são opcionais; quando informadas, definem quando o pagamento deve ocorrer e para qual conta destino. A resposta retorna o grupo gerado, com o identificador interno, o status e os ativos que o compõem.

Todos os ativos enviados na mesma requisição precisam ser homogêneos — ou seja, compartilhar o mesmo sacado, o mesmo cedente, o mesmo fundo e a mesma data de desembolso. Se algum ativo divergir, a requisição é recusada com 400 Bad Request e nenhum grupo é criado.

• Criar grupo de desembolso

// exemplo de requisição:
{
 "externalId": "bb9d844c-8041-464c-b160-471d437231d6",
 "disbursementDate": "2024-06-03T00:00:00",
 "bankAccount": {
  "number": "123456",
  "digit": "7",
  "bankCode": "208",
  "agency": "0001",
  "digitAgency": "9"
 },
 "assetIds": [
  "0524b1ed-6a78-4f00-8394-543ffcd188f0"
 ]
}

// exemplo de resposta:
{
 "id": "8bce6cfc-dcd4-473b-9fae-60ef3f60ec11",
 "externalId": "bb9d844c-8041-464c-b160-471d437231d6",
 "status": "Created",
 "assetIds": [
  "0524b1ed-6a78-4f00-8394-543ffcd188f0"
 ]
}

Regras importantes:

• O externalId é obrigatório e é a chave usada depois para consultar o grupo gerado. Cada externalId corresponde a exatamente um grupo interno (id).
• É necessário informar ao menos um ativo, e cada assetId deve ser um identificador válido.
• Todos os ativos precisam ter o mesmo sacado, o mesmo cedente, o mesmo fundo e a mesma data de desembolso. Ativos divergentes resultam em 400 Bad Request — a separação em grupos é responsabilidade do parceiro, que deve fazer uma chamada para cada conjunto homogêneo.
• O bankAccount é opcional. Quando informado, define a conta destino do pagamento do grupo; quando omitido, vale a conta já definida para o sacado.
• Os ativos agrupados têm seus desembolsos liberados juntos quando o grupo é liberado.

Consultar Grupo de Desembolso

Consulta um grupo de desembolso, incluindo o status do grupo e os ativos que o compõem — com a situação individual de cada membro (cessão vinculada, se está ativo no grupo e eventual motivo de remoção). Assim como na consulta de cessão, a busca pode ser feita de duas formas:

Forma de busca	Parâmetros
Pelo identificador interno	id do grupo (gerado pela plataforma).
Pelo identificador externo	externalId do grupo (informado pelo parceiro na criação) + fundTaxId (CNPJ do fundo). O fundTaxId é obrigatório neste caso, pois o identificador externo só é único dentro de um mesmo fundo.

• Consultar grupo de desembolso

// exemplo de resposta:
{
 "id": "8bce6cfc-dcd4-473b-9fae-60ef3f60ec11",
 "externalId": "bb9d844c-8041-464c-b160-471d437231d6",
 "status": "Created",
 "flowType": "Batch",
 "disbursementDate": "2024-06-03T00:00:00",
 "cancellationReason": null,
 "allOrNothing": true,
 "members": [
  {
   "assetId": "0524b1ed-6a78-4f00-8394-543ffcd188f0",
   "cessionId": "8bce6cfc-dcd4-473b-9fae-60ef3f60ec11",
   "cessionStatus": "Ceded",
   "isActive": true,
   "removalReason": null
  }
 ]
}

Tratamento de Erros

Todas as respostas da API — de sucesso ou de falha — seguem um envelope padrão. Em caso de erro, o campo succeeded retorna false e a lista errors traz o código, a mensagem e, quando aplicável, o campo que originou o problema. O trackingId pode ser informado ao suporte para rastrear a requisição.

// exemplo de resposta de erro:
{
 "trackingId": "8bce6cfc-dcd4-473b-9fae-60ef3f60ec11",
 "succeeded": false,
 "message": "Unsuccessful request, see errors to get more details.",
 "statusCode": 422,
 "errors": [
  {
   "code": "CF-67",
   "message": "The asset must be Eligible before creating a cession."
  }
 ],
 "data": null
}

Códigos HTTP

HTTP	Quando ocorre
400	Erro de validação nos dados enviados (campos obrigatórios, formatos ou valores inválidos, ativos de um grupo de desembolso com sacado/cedente/fundo/data divergentes)
404	Recurso não encontrado (ativo, cessão ou operação inexistente)
422	Violação de regra de negócio (ex.: ativo não elegível, cessão duplicada, correção com cessão ativa)
502	Falha na comunicação com um sistema integrado
500	Erro inesperado — contate o administrador informando o trackingId

Principais erros — Ativos

Código	HTTP	Descrição
CF-29	404	Ativo não encontrado — o assetId informado não existe.
CF-33	422	Produto não suportado — o produto informado não corresponde a um recebível ou empréstimo.
CF-34	422	Erro de validação — um ou mais campos do ativo estão inválidos; a mensagem consolida todas as violações encontradas.
CF-28	422	Estratégia não configurada — a configuração do fundo não possui uma estratégia válida; contate a administração do fundo.
CF-38	422	Ativo com cessão ativa — o ativo não pode ser corrigido enquanto houver uma cessão em andamento ou concluída.
CF-80	422	Correção necessária — o ativo já existe e está inelegível; utilize a rota de atualização (PUT) em vez de criar novamente.

Principais erros — Cessões

Código	HTTP	Descrição
CF-78	422	Referência de ativo obrigatória — informe asset ou assetId na criação da cessão.
CF-79	422	Referência ambígua — asset e assetId são mutuamente exclusivos; informe exatamente um.
CF-66	422/404	Ativo inexistente — o ativo referenciado pela cessão (ou pela consulta) não foi encontrado.
CF-67	422	Ativo não elegível — o ativo precisa estar Eligible para ser cedido.
CF-65	422	Cessão duplicada — já existe uma cessão ativa para este ativo (ou o ativo já está vinculado a uma cessão no grupo).
CF-68	422	Erro de validação da cessão — dados dos termos da cessão inválidos (registro, valor de compra, desembolsos, contas etc.), ou a configuração do fundo não foi encontrada.

📘 Erros durante o processamento assíncrono

Falhas que ocorrem após o aceite da requisição (precificação, elegibilidade, reserva de limite, registro do trade, desembolso) não são retornadas na resposta HTTP — elas aparecem no campo failureReason/rejectionReason das rotas de consulta de status. Exemplos: CF-70 (falha na precificação), CF-71 (inelegível para o fundo), CF-73 (falha na reserva de limite), CF-74 (falha no envio do trade) e CF-77 (falha no enriquecimento do desembolso).