# QI Tech — Investment-as-a-Service › Cessão de Direitos Creditórios
Documentação da QI Tech em texto corrido, para colar em um LLM.
Fonte: https://docs.qitech.com.br
28 página(s).
Índice:
- Layout CNAB 400 — Contratos Parcelados (/documentation/iaas/negociacao_recebiveis/arquivo/cnab400_contrato)
- Layout CNAB 444 — Cessão (/documentation/iaas/negociacao_recebiveis/arquivo/cnab444)
- Layout CSV — Contratos Parcelados (/documentation/iaas/negociacao_recebiveis/arquivo/csv_contrato_parcelado)
- Layout CSV — Duplicatas, CT-e, Cheques e Notas Promissórias (/documentation/iaas/negociacao_recebiveis/arquivo/csv_duplicatas_titulos)
- Cessão por Arquivo (/documentation/iaas/negociacao_recebiveis/arquivo/inicio)
- Criação de Ativo — CCB (/documentation/iaas/negociacao_recebiveis/asset/criacao_co)
- Criação de ativo — contrato parcelado (/documentation/iaas/negociacao_recebiveis/asset/criacao_contract)
- Criação de Ativo — CTE (/documentation/iaas/negociacao_recebiveis/asset/criacao_cte)
- Criação de ativo — contrato descontado (/documentation/iaas/negociacao_recebiveis/asset/criacao_discounted_contract)
- Criação de Ativo — Duplicata (/documentation/iaas/negociacao_recebiveis/asset/criacao_duplicata)
- Inserção de Ativo para Recompra (/documentation/iaas/negociacao_recebiveis/asset/criacao_repurchased_asset)
- Envio do Lastro do Ativo (/documentation/iaas/negociacao_recebiveis/asset/documents)
- Qual ativo enviar (/documentation/iaas/negociacao_recebiveis/asset/qual_ativo_enviar)
- Consulta de Ativos do Lote (/documentation/iaas/negociacao_recebiveis/asset/recuperar_ativos)
- Remoção de Ativos do Lote (/documentation/iaas/negociacao_recebiveis/asset/remocao_ativos)
- Webhooks do Ativo (/documentation/iaas/negociacao_recebiveis/asset/webhooks)
- Aprovação do Lote (/documentation/iaas/negociacao_recebiveis/assignment/aprovacao)
- Criação do Lote de Cessão (/documentation/iaas/negociacao_recebiveis/assignment/criacao)
- Termo de Cessão do Lote (/documentation/iaas/negociacao_recebiveis/assignment/documento_da_cessao)
- Encerrar Inserção de Ativos (/documentation/iaas/negociacao_recebiveis/assignment/fechamento)
- Listagem de Lotes de Cessão (/documentation/iaas/negociacao_recebiveis/assignment/listagem)
- Recuperação do Lote de Cessão (/documentation/iaas/negociacao_recebiveis/assignment/recuperacao)
- Resumo de ativos do lote (/documentation/iaas/negociacao_recebiveis/assignment/resumo_ativos)
- Como criar uma cessão? (/documentation/iaas/negociacao_recebiveis/assignment/video_cessao)
- Webhooks do Lote de Cessão (/documentation/iaas/negociacao_recebiveis/assignment/webhooks)
- Fluxo de Cessão (/documentation/iaas/negociacao_recebiveis/fluxo_cessao)
- Cessão de Direitos Creditórios (/documentation/iaas/negociacao_recebiveis/inicio)
- Listagem de Configurações de Cessão (/documentation/iaas/negociacao_recebiveis/listagem)
---
# Layout CNAB 400 — Contratos Parcelados
URL: /documentation/iaas/negociacao_recebiveis/arquivo/cnab400_contrato
Layout do arquivo de **remessa de cessão de contratos parcelados** no padrão CNAB 400 de cobrança (registros `0`, `1`, `2` e `9`). Cada registro `1` é uma parcela; as parcelas com o mesmo número do documento formam um contrato.
:::info Onde este arquivo é usado
Este é o arquivo enviado no fluxo descrito em [Cessão por Arquivo](/documentation/iaas/negociacao_recebiveis/arquivo/inicio), pelo portal do gestor ou do consultor, ou pela API da gestora. O layout 400 só é aceito em configuração de cessão de **contrato parcelado** (`contract`) ou de **contrato descontado** (`discounted_contract`). Em qualquer outra configuração o arquivo é recusado com a mensagem *"O layout CNAB 400 aceita apenas cessão de contratos, mas a configuração de cessão é de '…'."*
:::
[Baixar remessa de exemplo](/downloads/modelos_arquivo/exemplo_cessao_contrato_cnab400.rem) — dados fictícios: troque o código do originador no header (posições 27–46) pelo seu antes de testar.
## Estrutura do arquivo
| Registro | Identificação (posição 1) | Quantidade |
|---|---|---|
| **Header** | `0` | 1, sempre a primeira linha |
| **Detalhe** | `1` | 1 por parcela |
| **Complemento** | `2` | Opcional, depois de uma parcela. É conferido e não altera o contrato |
| **Trailer** | `9` | 1, sempre a última linha |
Todas as linhas têm **exatamente 400 caracteres**, sem contar a quebra de linha. O arquivo é reconhecido como CNAB 400 pelo tamanho das linhas: não remova os espaços do fim da linha.
## Regras gerais de preenchimento
| Regra | Detalhe |
|---|---|
| **Tamanho fixo** | Toda linha tem 400 posições. Linhas mais curtas ou mais longas recusam o arquivo. |
| **Campos numéricos** | Alinhados à direita, completados com **zeros** à esquerda. |
| **Campos alfanuméricos** | Alinhados à esquerda, completados com **espaços** à direita. |
| **Valores monetários** | 13 posições, com 2 casas decimais, **sem** vírgula ou ponto. `R$ 1.234,56` → `0000000123456`. |
| **Datas** | Formato `DDMMAA`. Ex.: 15/10/2026 → `151026`. |
| **Extensão** | `.rem` ou `.txt`. Quebra de linha `CRLF` ou `LF`. |
## Registro Header
| # | Posição | Tam. | Campo | Obrig. | Conteúdo aceito |
|---|---|---|---|---|---|
| 1 | 001–001 | 1 | Identificação do registro | Sim | `0` |
| 2 | 002–002 | 1 | Identificação do arquivo remessa | Sim | `1` |
| 3 | 003–009 | 7 | Literal remessa | Sim | `REMESSA` |
| 4 | 010–011 | 2 | Código do serviço | Sim | `01` |
| 5 | 012–026 | 15 | Literal do serviço | Sim | `COBRANCA` + 7 espaços |
| 6 | 027–046 | 20 | **Código do originador** | Sim | Código cadastrado na configuração de cessão, alinhado à direita com zeros |
| 7 | 047–076 | 30 | Nome do originador | Sim | Razão social |
| 8 | 077–079 | 3 | Número do banco | Sim | Dígitos |
| 9 | 080–094 | 15 | Nome do banco | Sim | Não pode ficar em branco |
| 10 | 095–100 | 6 | Data de gravação do arquivo | Sim | `DDMMAA` |
| 11 | 101–108 | 8 | Brancos | Sim | 8 espaços |
| 12 | 109–110 | 2 | Identificação do sistema | Sim | `MX` |
| 13 | 111–117 | 7 | Nº sequencial do arquivo | Sim | Dígitos |
| 14 | 118–394 | 277 | Brancos | Sim | Exatamente 277 espaços |
| 15 | 395–400 | 6 | Nº sequencial do registro | Sim | `000001` |
:::info Código do originador (posições 27–46)
É o identificador do originador **cadastrado na configuração de cessão**. Um código não cadastrado ou vinculado a outra configuração recusa o arquivo. Solicite o código no processo de homologação do cedente.
:::
## Registro Detalhe (parcela)
Um registro por parcela. Só os campos abaixo são lidos; as demais posições do layout de cobrança (por exemplo, 002–037, conta de débito e identificação da empresa) podem vir preenchidas e não são usadas.
| # | Posição | Tam. | Campo | Obrig. | Conteúdo aceito |
|---|---|---|---|---|---|
| 1 | 001–001 | 1 | Identificação do registro | Sim | `1` |
| 2 | 038–062 | 25 | **Nº de controle do participante** | Sim | Identificador da parcela no seu sistema. Único no arquivo e não deve mudar depois da cessão: é por ele que a parcela é encontrada na liquidação |
| 3 | 109–110 | 2 | **Identificação da ocorrência** | Sim | `01` (entrada) |
| 4 | 111–120 | 10 | **Nº do documento** | Sim | Número do contrato. Repita o mesmo número em todas as parcelas do contrato |
| 5 | 121–126 | 6 | **Data de vencimento** | Sim | `DDMMAA` |
| 6 | 127–139 | 13 | **Valor de face** | Sim | Valor da parcela, 2 decimais, maior que zero |
| 7 | 148–149 | 2 | **Espécie do título** | Sim | `60` contrato · `61` contrato físico |
| 8 | 151–156 | 6 | **Data de emissão** | Sim | `DDMMAA`. Igual em todas as parcelas do contrato |
| 9 | 193–205 | 13 | **Valor presente (aquisição)** | Sim | Preço que o fundo paga pela parcela (valor de face com o desconto acertado), 2 decimais, maior que zero |
| 10 | 219–220 | 2 | **Tipo de inscrição do sacado** | Sim | `01` pessoa física (CPF), `02` pessoa jurídica (CNPJ) |
| 11 | 221–234 | 14 | **Nº de inscrição do sacado** | Sim | CNPJ com 14 posições; CPF com 11 dígitos alinhados à direita. **O dígito verificador é conferido.** Igual em todas as parcelas do contrato |
| 12 | 235–274 | 40 | **Nome do sacado** | Sim | Não pode ficar em branco |
| 13 | 275–314 | 40 | **Endereço do sacado** | Sim | Não pode ficar em branco. Ex.: `AV EXEMPLO, 100` |
| 14 | 327–334 | 8 | **CEP do sacado** | Sim | 8 dígitos, sem hífen |
| 15 | 395–400 | 6 | Nº sequencial do registro | Sim | Sequencial da linha |
:::caution Posições 193–205
No layout de cobrança bancária essas posições costumam trazer o IOF, muitas vezes zerado. Na cessão elas trazem o **valor presente da parcela**: com zeros, a linha é recusada.
:::
## Registro Complemento
| # | Posição | Tam. | Campo | Obrig. | Conteúdo aceito |
|---|---|---|---|---|---|
| 1 | 001–001 | 1 | Identificação do registro | Sim | `2` |
| 2 | 002–394 | 393 | Mensagens e descontos do boleto | Não | Livre; não é lido |
| 3 | 395–400 | 6 | Nº sequencial do registro | Sim | 6 dígitos |
## Registro Trailer
| # | Posição | Tam. | Campo | Obrig. | Conteúdo aceito |
|---|---|---|---|---|---|
| 1 | 001–001 | 1 | Identificação do registro | Sim | `9` |
| 2 | 002–394 | 393 | Brancos | Sim | Exatamente 393 espaços |
| 3 | 395–400 | 6 | Nº sequencial do registro | Sim | 6 dígitos |
## Como as parcelas viram contratos
- **Agrupamento:** linhas com o mesmo **Nº do documento** (111–120) são as parcelas de um mesmo contrato, e esse número vira o identificador e o número do contrato na carteira. O arquivo pode ter contratos de vários sacados.
- **Consistência:** todas as parcelas de um contrato precisam ter o mesmo **Nº de inscrição do sacado** e a mesma **data de emissão**; senão, o arquivo é recusado. Os demais dados do sacado vêm da primeira linha do contrato.
- **Numeração:** não informe número de parcela. As parcelas de cada contrato são numeradas 1, 2, 3, … pela data de vencimento.
- **Nº de controle do participante:** obrigatório e sem repetição no arquivo.
- **Valores:** o valor de compra do contrato é a soma dos valores presentes das suas parcelas. O layout 400 não traz taxa, e o contrato entra sem taxa nominal.
## Exemplo
O [arquivo de exemplo](/downloads/modelos_arquivo/exemplo_cessao_contrato_cnab400.rem) tem dois contratos:
| Linha | Registro | Nº do documento | Nº de controle | Vencimento | Valor de face | Valor presente | Resultado |
|---|---|---|---|---|---|---|---|
| 2 | `1` | `CT4001` | `400002` | 15/10/2026 | 1.500,00 | 1.400,00 | Contrato CT4001, parcela 1 |
| 3 | `2` | — | — | — | — | — | Complemento, não lido |
| 4 | `1` | `CT4001` | `400001` | 15/11/2026 | 1.500,00 | 1.350,00 | Contrato CT4001, parcela 2 |
| 5 | `2` | — | — | — | — | — | Complemento, não lido |
| 6 | `1` | `CT4002` | `400003` | 20/10/2026 | 800,00 | 760,00 | Contrato CT4002, parcela 1 |
| 7 | `2` | — | — | — | — | — | Complemento, não lido |
O contrato CT4001 entra com valor de compra de R$ 2.750,00 e o CT4002 com R$ 760,00.
---
# Layout CNAB 444 — Cessão
URL: /documentation/iaas/negociacao_recebiveis/arquivo/cnab444
Layout do arquivo de **remessa de cessão** aceito pela QI DTVM. É o padrão CNAB 444 de cobrança usado no mercado de FIDCs, com as regras de preenchimento e os domínios efetivamente validados pela nossa plataforma.
:::info Onde este arquivo é usado
Este é o arquivo enviado no fluxo descrito em [Cessão por Arquivo](/documentation/iaas/negociacao_recebiveis/arquivo/inicio), pelo portal do gestor ou do consultor, ou pela API da gestora. Para dar baixa em ativos já encarteirados, o layout é outro: veja [Layout CNAB 444 — Baixa](/documentation/iaas/liquidacao_ativos/arquivo/cnab444_baixa).
:::
## Estrutura do arquivo
| Registro | Identificação (posição 1) | Quantidade |
|---|---|---|
| **Header** | `0` | 1, sempre a primeira linha |
| **Detalhe** | `1` | 1 por título cedido |
| **Trailer** | `9` | 1, sempre a última linha |
Todas as linhas têm **exatamente 444 caracteres**, sem contar a quebra de linha.
## Nome do arquivo
`CBDDMMxx.REM` ou `CBDDMMxx.TXT` — `CB` fixo, `DD` dia, `MM` mês e `xx` sequencial alfanumérico. Exemplos: `CB120801.REM`, `CB1208AE.TXT`.
Aceitamos qualquer nome, desde que a extensão seja `.rem` ou `.txt`. A convenção acima é apenas a recomendada.
## Regras gerais de preenchimento
| Regra | Detalhe |
|---|---|
| **Tamanho fixo** | Toda linha tem 444 posições. Linhas mais curtas ou mais longas recusam o arquivo. |
| **Campos numéricos** | Alinhados à direita, completados com **zeros** à esquerda. |
| **Campos alfanuméricos** | Alinhados à esquerda, completados com **espaços** à direita. |
| **Valores monetários** | Sempre com 2 casas decimais, **sem** vírgula ou ponto. `R$ 2.470,56` → `000000000247056`. |
| **Datas** | Formato `DDMMAA`. Ex.: 12/08/2025 → `120825`. |
| **Caracteres permitidos** | Apenas `A-Z`, `a-z`, `0-9`, espaço e `. / - , ( ) &`. **Não use acentos nem `Ç`** — troque `SÃO PAULO` por `SAO PAULO` e `AÇOS` por `ACOS`. |
| **Codificação** | UTF-8 ou ASCII. Quebra de linha `CRLF` ou `LF`. |
:::caution O erro mais comum
Acento ou cedilha em nome de sacado, razão social ou endereço. A mensagem devolvida aponta a posição exata e o nome do campo — por exemplo: *"Caracteres inválidos encontrados na posição 240, dentro do campo 'Nome do sacado'."*
:::
## Registro Header
| # | Posição | Tam. | Campo | Obrig. | Conteúdo aceito |
|---|---|---|---|---|---|
| 1 | 001–001 | 1 | Identificação do registro | Sim | `0` |
| 2 | 002–002 | 1 | Identificação do arquivo remessa | Sim | `1` |
| 3 | 003–009 | 7 | Literal remessa | Sim | `REMESSA` |
| 4 | 010–011 | 2 | Código do serviço | Sim | `01` |
| 5 | 012–026 | 15 | Literal do serviço | Sim | `COBRANCA` + 7 espaços |
| 6 | 027–046 | 20 | **Código do originador** | Sim | Código fornecido pela QI DTVM no cadastro, alinhado à direita com zeros |
| 7 | 047–076 | 30 | Nome do originador | Sim | Razão social |
| 8 | 077–079 | 3 | Número do banco | Não | Livre |
| 9 | 080–094 | 15 | Nome do banco | Não | Livre |
| 10 | 095–100 | 6 | Data de gravação do arquivo | Sim | `DDMMAA` |
| 11 | 101–108 | 8 | Brancos | Sim | 8 espaços |
| 12 | 109–110 | 2 | Identificação do sistema | Sim | `MX` |
| 13 | 111–117 | 7 | Nº sequencial do arquivo | Não | Livre |
| 14 | 118–120 | 3 | Banco do cedente | Não | Dígitos ou brancos |
| 15 | 121–125 | 5 | Agência do cedente | Não | Dígitos ou brancos |
| 16 | 126–126 | 1 | DV da agência | Não | Livre |
| 17 | 127–138 | 12 | Conta corrente do cedente | Não | Dígitos ou brancos |
| 18 | 139–139 | 1 | DV da conta corrente | Não | Livre |
| 19 | 140–377 | 238 | Brancos | Sim | Exatamente 238 espaços |
| 20 | 378–391 | 14 | **CPF/CNPJ do cedente original** | Não | CNPJ com 14 caracteres, CPF com 11 dígitos + 3 espaços, ou 14 espaços |
| 21 | 392–438 | 47 | Brancos | Sim | Exatamente 47 espaços |
| 22 | 439–444 | 6 | Nº sequencial do registro | Sim | `000001` |
:::info Código do originador (posições 27–46)
É o identificador do originador **cadastrado na configuração de cessão**. Um código não cadastrado ou vinculado a outra configuração recusa o arquivo com a mensagem *"O código do originador '…' não foi encontrado"*. Solicite o código no processo de homologação do cedente.
:::
:::tip Cedente original (posições 378–391)
Campo específico da QI DTVM, que **não existe no layout de mercado**. Use quando o título já tiver passado por um endosso anterior e você precisar registrar o CNPJ/CPF do cedente de origem. Se não se aplica, deixe em branco.
:::
## Registro Detalhe
Um registro por título. Os campos em **negrito** são os que alimentam o ativo criado na carteira do fundo.
| # | Posição | Tam. | Campo | Obrig. | Conteúdo aceito |
|---|---|---|---|---|---|
| 1 | 001–001 | 1 | Identificação do registro | Sim | `1` |
| 2 | 002–007 | 6 | Data de carência | Não | `DDMMAA` ou zeros |
| 3 | 008–008 | 1 | Tipo de juros | Não | `0` sem correção, `1` juros fixo, `2` CDI, `3` IPCA-15, `4` IPCA, `5` IGPM, ou branco |
| 4 | 009–010 | 2 | Brancos | Sim | 2 espaços |
| 5 | 011–020 | 10 | Taxa de juros | Não | Dígitos (7 decimais) ou 10 espaços |
| 6 | 021–022 | 2 | Coobrigação | Sim | `01` com coobrigação, `02` sem coobrigação |
| 7 | 023–024 | 2 | Característica especial (SCR) | Não | Anexo 8 do SCR 3040, `00` ou brancos |
| 8 | 025–028 | 4 | Modalidade da operação (SCR) | Condicional | Anexo 3 do SCR 3040. Pode ficar em branco para duplicatas e CTe |
| 9 | 029–030 | 2 | Natureza da operação (SCR) | Não | Anexo 2 do SCR 3040, `00` ou brancos |
| 10 | 031–034 | 4 | Origem do recurso (SCR) | Não | Anexo 4 do SCR 3040, `0000` ou brancos |
| 11 | 035–036 | 2 | Classe de risco (SCR) | Não | `AA`, `A`…`H`, `HH`, `01`, `00` ou brancos |
| 12 | 037–037 | 1 | Zeros | Não | `0` ou branco |
| 13 | 038–062 | 25 | **Nº de controle do participante** | Sim | Identificador único do ativo no seu sistema. Alinhado à esquerda |
| 14 | 063–065 | 3 | Número do banco | Não | Dígitos ou brancos |
| 15 | 066–070 | 5 | Zeros | Não | Zeros ou brancos |
| 16 | 071–081 | 11 | Identificação do título no banco | Não | Dígitos ou 11 espaços |
| 17 | 082–082 | 1 | Dígito do nosso número | Não | Livre |
| 18 | 083–092 | 10 | Valor pago | Não | **Zeros** na cessão |
| 19 | 093–093 | 1 | Condição de emissão da papeleta | Não | Branco |
| 20 | 094–094 | 1 | Papeleta para débito automático | Não | Branco |
| 21 | 095–100 | 6 | Data da liquidação | Não | **Zeros** na cessão |
| 22 | 101–104 | 4 | Identificação da operação do banco | Não | 4 espaços ou `0000` |
| 23 | 105–105 | 1 | Indicador de rateio de crédito | Não | Branco ou `0` |
| 24 | 106–106 | 1 | Endereçamento de aviso de débito | Não | Branco |
| 25 | 107–108 | 2 | Brancos | Não | 2 espaços ou `00` |
| 26 | 109–110 | 2 | **Identificação da ocorrência** | Sim | Ver [Ocorrências](#ocorrencias-aceitas) |
| 27 | 111–120 | 10 | **Nº do documento** | Sim | Número do título/duplicata. Exatamente 10 caracteres |
| 28 | 121–126 | 6 | **Data de vencimento** | Sim | `DDMMAA` |
| 29 | 127–139 | 13 | **Valor de face** | Sim | Valor nominal do título, 2 decimais |
| 30 | 140–142 | 3 | Banco encarregado da cobrança | Não | Dígitos, zeros ou brancos |
| 31 | 143–147 | 5 | Agência depositária | Não | 5 dígitos, `00000` ou brancos |
| 32 | 148–149 | 2 | **Espécie de título** | Sim | Ver [Espécies](#especies-de-titulo) |
| 33 | 150–150 | 1 | Identificação | Não | Branco |
| 34 | 151–156 | 6 | **Data de emissão do título** | Sim | `DDMMAA` |
| 35 | 157–158 | 2 | 1ª instrução | Não | `00` |
| 36 | 159–159 | 1 | 2ª instrução | Não | `0` |
| 37 | 160–161 | 2 | Tipo de pessoa do cedente | Sim | `01` pessoa física, `02` pessoa jurídica |
| 38 | 162–173 | 12 | Juros/mora por dia de atraso | Não | 12 caracteres alfanuméricos **ou** 12 espaços |
| 39 | 174–192 | 19 | Nº do termo de cessão | Não | Livre ou brancos |
| 40 | 193–205 | 13 | **Valor presente (aquisição)** | Sim | Valor pago pelo fundo por este título, 2 decimais |
| 41 | 206–218 | 13 | Valor do abatimento | Não | Zeros ou dígitos |
| 42 | 219–220 | 2 | **Tipo de inscrição do sacado** | Sim | `01` pessoa física (CPF), `02` pessoa jurídica (CNPJ) |
| 43 | 221–234 | 14 | **Nº de inscrição do sacado** | Sim | CNPJ com 14 posições; CPF com 11 dígitos alinhados à direita. **O dígito verificador é conferido** |
| 44 | 235–274 | 40 | **Nome do sacado** | Sim | Não pode ficar em branco |
| 45 | 275–314 | 40 | **Endereço do sacado** | Sim | Não pode ficar em branco. Ex.: `AV EXEMPLO, 100` |
| 46 | 315–323 | 9 | **Nº da nota fiscal** | Condicional | Obrigatório para duplicatas e CTe |
| 47 | 324–326 | 3 | Série da nota fiscal | Não | 3 alfanuméricos ou 3 espaços. Em branco assume `1` |
| 48 | 327–334 | 8 | **CEP do sacado** | Sim | 8 dígitos, sem hífen |
| 49 | 335–394 | 60 | **Cedente** | Sim | `335–380` nome do cedente (46) · `381–394` CNPJ do cedente (14) |
| 50 | 395–438 | 44 | **Chave da NF-e** | Condicional | 44 dígitos. Obrigatória para `duplicata_mercantil` e `cte` nas ocorrências `01`, `81` e `84` |
| 51 | 439–444 | 6 | Nº sequencial do registro | Sim | Sequencial da linha, começando em `000002` |
## Registro Trailer
| # | Posição | Tam. | Campo | Obrig. | Conteúdo aceito |
|---|---|---|---|---|---|
| 1 | 001–001 | 1 | Identificação do registro | Sim | `9` |
| 2 | 002–438 | 437 | Brancos | Sim | Exatamente 437 espaços |
| 3 | 439–444 | 6 | Nº sequencial do registro | Sim | Número da última linha do arquivo |
## Ocorrências aceitas
A ocorrência (posições 109–110) diz o que fazer com o título.
| Código | Significado | Quando usar |
|---|---|---|
| `01` | **Remessa — aquisição de títulos** | Padrão da cessão. É o que você usa em quase todos os casos |
| `80` | Remessa — aquisição com liquidação para a consultoria | Tratada como aquisição |
| `81` | Entrada por troca de títulos, com liquidação para a consultoria | Contrapartida de recompra dentro do mesmo arquivo |
| `84` | Entrada por troca de títulos, com liquidação para o cedente | Contrapartida de recompra dentro do mesmo arquivo |
| `72` | **Recompra parcial** | Só em lote de substituição. Gera amortização do ativo recomprado |
| `74` | **Baixa por recompra** | Só em lote de substituição. Gera liquidação do ativo recomprado |
:::caution Recompra exige lote de substituição
As ocorrências `72` e `74` só são aceitas quando a configuração de cessão é do tipo substituição e o lote foi criado com `assignment_type: substitution_assignment`. Em um lote comum, o arquivo é recusado com a mensagem *"A ocorrência de recompra '…' só é permitida em configurações de cessão de recompra (substituição)"*.
:::
:::info Ocorrências de baixa não entram aqui
Códigos como `04`, `14`, `75` e `77` pertencem ao arquivo de **baixa** e são processados por outro fluxo. Enviá-los em um arquivo de cessão faz o ativo falhar no processamento, mesmo que a linha passe na validação de estrutura. Veja [Baixa por Arquivo](/documentation/iaas/liquidacao_ativos/arquivo/inicio).
:::
## Espécies de título {#especies-de-titulo}
A espécie, nas posições 148–149, define como o título é lido. **Estes códigos são processados no fluxo de cessão por arquivo:**
| Código | Espécie | Tipo de ativo | Nota fiscal | Chave da NF-e | Exemplo |
|---|---|---|---|---|---|
| `01` | Duplicata | `duplicata_mercantil` | Obrigatória | Obrigatória | [Baixar](/downloads/modelos_arquivo/exemplo_cessao_duplicata_mercantil_cnab444.rem) |
| `14` | Duplicata de serviço | `duplicata_servicos` | Obrigatória | Dispensada | [Baixar](/downloads/modelos_arquivo/exemplo_cessao_duplicata_servicos_cnab444.rem) |
| `53` | CT-e | `cte` | Obrigatória | Obrigatória | [Baixar](/downloads/modelos_arquivo/exemplo_cessao_cte_cnab444.rem) |
| `51`, `52`, `87` | Cheque | `check` | — | Dispensada | — |
| `02`, `06` | Nota promissória | `promissory_note` | — | Dispensada | — |
No cheque e na nota promissória, o número do instrumento é o **Nº do documento** (posições 111–120) e a data de emissão é a das posições 151–156. O banco (063–065) e a agência (143–147), quando preenchidos, também são levados ao instrumento: use-os no cheque e deixe-os em branco ou zerados na nota promissória, que não aceita esses campos e teria o ativo recusado.
:::caution Outros códigos passam na estrutura, mas não são processados
O layout CNAB 444 prevê outras espécies — `41` CCB digital, `60` contrato, entre outras. Elas passam pela validação estrutural do arquivo, mas **não são convertidas em ativo no fluxo de cessão por arquivo**: o processamento devolve *"Asset type … was not expected"* e o lote não avança.
Se o seu produto usa uma dessas espécies, ceda pela API de integração, ativo a ativo, ou confirme o caminho com [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br) antes de montar o arquivo.
:::
:::info A espécie precisa combinar com a configuração de cessão
Uma configuração de `duplicata_mercantil` espera espécie `01`. Enviar uma espécie incompatível com o tipo de ativo da configuração faz o ativo ser recusado na inserção.
:::
## De-para: do CNAB para o ativo na carteira
Cada linha de detalhe vira um ativo idêntico ao que seria criado pelo endpoint de [Criação de Ativo — Duplicata](/documentation/iaas/negociacao_recebiveis/asset/criacao_duplicata) (ou [CTE](/documentation/iaas/negociacao_recebiveis/asset/criacao_cte)).
| Posição no CNAB | Campo do ativo (API) |
|---|---|
| 038–062 Nº de controle do participante | `discounted_credit_right.external_id` e `participant_control_number` — é por ele que o ativo é referenciado depois, inclusive na baixa |
| 111–120 Nº do documento | `discounted_credit_right.order_number` — identifica a linha dentro do arquivo e **não pode se repetir** |
| 121–126 Data de vencimento | `discounted_credit_right.maturity_date` |
| 127–139 Valor de face | `discounted_credit_right.face_value` |
| 148–149 Espécie de título | `asset_type` |
| 151–156 Data de emissão | `discounted_credit_right.invoice.issue_date` |
| 193–205 Valor presente | `total_purchase_value` |
| 219–220 / 221–234 Sacado | `borrower.person_type` e `borrower.document_number` |
| 235–274 Nome do sacado | `borrower.name` |
| 275–314 Endereço do sacado | `borrower.address.street` e `number` |
| 315–323 / 324–326 Nota fiscal | `invoice.number` e `invoice.serie` |
| 327–334 CEP | `borrower.address.postal_code` |
| 395–438 Chave da NF-e | `invoice.access_key` |
| Header 027–046 Código do originador | `originator_document_number` |
| Header 378–391 Cedente original | `original_assignor_document_number` |
:::tip Endereço do sacado
O logradouro e o número são extraídos do texto das posições 275–314, e o restante do endereço (bairro, cidade e UF) é completado automaticamente a partir do CEP. Escreva no formato `LOGRADOURO, NUMERO`.
:::
## Exemplo comentado
Cessão de duas duplicatas mercantis do cedente `11.222.333/0001-81`, com vencimento em 10/10/2025.
```text title="CB120801.REM"
01REMESSA01COBRANCA 00000011222333000181INDUSTRIA EXEMPLO S/A ...MX...000001
1...0CTRL000001...01000100001101025000000015100...0245678912000155COMERCIO EXEMPLO ALFA LTDA...000002
1...0CTRL000002...01000200002101025000000015200...0278912345000109COMERCIO EXEMPLO BETA LTDA...000003
9 ...000004
```
| Linha | Leitura |
|---|---|
| Header | Originador `00000011222333000181`, arquivo gerado em 12/08/2025, sistema `MX` |
| Detalhe 1 | Ativo `CTRL000001`, documento `0001000010`, vence em 10/10/2025, face R$ 1.510,00, aquisição R$ 1.480,00, sacado CNPJ `45.678.912/0001-55` |
| Detalhe 2 | Ativo `CTRL000002`, documento `0002000020`, face R$ 1.520,00, aquisição R$ 1.490,00, sacado CNPJ `78.912.345/0001-09` |
| Trailer | Fecha o arquivo com o sequencial `000004` |
### Arquivos de exemplo
| Arquivo | Espécie | O que traz |
|---|---|---|
| [Duplicata mercantil](/downloads/modelos_arquivo/exemplo_cessao_duplicata_mercantil_cnab444.rem) | `01` | Dois títulos com nota fiscal e chave da NF-e preenchidas |
| [Duplicata de serviços](/downloads/modelos_arquivo/exemplo_cessao_duplicata_servicos_cnab444.rem) | `14` | Dois títulos com nota fiscal e sem chave da NF-e |
| [CT-e](/downloads/modelos_arquivo/exemplo_cessao_cte_cnab444.rem) | `53` | Dois conhecimentos de transporte com chave preenchida |
:::info Sobre os exemplos
Os três arquivos passam integralmente pela nossa validação. Os CNPJs são fictícios, mas têm dígito verificador válido — se você trocar por documentos "redondos" tipo `45678912000199`, o arquivo será recusado.
:::
## Checklist antes de enviar
- [ ] Todas as linhas com exatamente 444 caracteres
- [ ] Header começa com `01REMESSA01COBRANCA` e tem `MX` nas posições 109–110
- [ ] Código do originador cadastrado, alinhado à direita com zeros
- [ ] Sem acentos, `Ç` ou caracteres especiais em qualquer campo
- [ ] CPF/CNPJ do sacado com dígito verificador válido
- [ ] Nome e endereço do sacado preenchidos
- [ ] Chave da NF-e com 44 dígitos nas duplicatas mercantis e CT-e
- [ ] Nº de controle do participante único por ativo
- [ ] Valores monetários sem vírgula, com 2 decimais
- [ ] Ocorrência `01` (ou `72`/`74` apenas em lote de substituição)
- [ ] Sequencial de registro correto, com o trailer fechando na última linha
---
# Layout CSV — Contratos Parcelados
URL: /documentation/iaas/negociacao_recebiveis/arquivo/csv_contrato_parcelado
Layout do arquivo de **cessão de contratos parcelados** (`asset_type` igual a `contract`) aceito pela QI DTVM. É um CSV com **uma linha por parcela**: as linhas que compartilham o mesmo `external_id` são as parcelas de um mesmo contrato e formam um único ativo.
:::info Onde este arquivo é usado
Este é o arquivo enviado no fluxo descrito em [Cessão por Arquivo](/documentation/iaas/negociacao_recebiveis/arquivo/inicio), pelo portal do gestor ou do consultor, ou pela API da gestora. Para ceder contrato parcelado ativo a ativo pela API, veja [Criação de Ativo — Contrato Parcelado](/documentation/iaas/negociacao_recebiveis/asset/criacao_contract).
:::
**[📄 Baixar modelo CSV](/downloads/modelos_arquivo/modelo_cessao_contrato_parcelado.csv)**
O modelo já vem com linhas de exemplo preenchidas — dois contratos, um pré-fixado de pessoa física com duas parcelas e um pós-fixado de pessoa jurídica com uma parcela. Apague as linhas de exemplo antes de colocar os seus dados.
## Estrutura do arquivo
| Item | Regra |
|---|---|
| **Cabeçalho** | 1 linha, sempre a primeira, com os nomes das colunas exatamente como no modelo |
| **Linhas de dados** | 1 por **parcela**. Um contrato com 12 parcelas ocupa 12 linhas |
| **Agrupamento** | Linhas com o mesmo `external_id` são o mesmo ativo. O lote é contado em ativos, não em linhas |
| **Extensão** | `.csv` |
| **Separador** | Vírgula (`,`) ou ponto e vírgula (`;`) — detectado a partir da linha de cabeçalho |
| **Codificação** | UTF-8 (com ou sem BOM) |
| **Datas** | Formato `AAAA-MM-DD` |
| **Valores** | Ponto como separador decimal, sem separador de milhar. `R$ 900,00` → `900.00` |
| **Documentos** | CPF em `000.000.000-00` e CNPJ em `00.000.000/0000-00`, sempre com a pontuação |
:::caution O cabeçalho é fechado
Use o cabeçalho do modelo sem alterações: não traduza, não renomeie e não acrescente colunas. Qualquer coluna fora do modelo, ou a falta de uma coluna obrigatória, recusa o arquivo inteiro antes de qualquer linha ser conferida.
:::
## Colunas
### Identificação
| Coluna | Obrigatoriedade | Descrição |
|---|---|---|
| `asset_type` | obrigatória | Tipo do ativo. Para contrato parcelado, o único valor aceito é `contract`, em todas as linhas |
| `external_id` | obrigatória | Identificador do contrato no seu sistema, até 50 caracteres. É a chave do ativo: as parcelas do mesmo contrato repetem o mesmo valor |
| `originator_document_number` | obrigatória | CPF ou CNPJ do originador, com pontuação. Precisa estar cadastrado e vinculado à configuração de cessão, e ser o mesmo em todas as linhas do arquivo |
| `contract_number` | obrigatória | Número do contrato, até 50 caracteres. Enviado exatamente como escrito, sem normalização |
| `contract_issue_date` | opcional | Data de emissão do contrato, em `AAAA-MM-DD` |
### Valores e juros
| Coluna | Obrigatoriedade | Descrição |
|---|---|---|
| `total_purchase_value` | obrigatória | Valor que o fundo paga pelo contrato inteiro. Repita o mesmo valor em todas as linhas do contrato |
| `interest_rate_type` | obrigatória | `pre_fixed` ou `post_fixed`. Define quais colunas de taxa passam a ser obrigatórias |
| `calendar_base` | opcional | Base de contagem de dias do contrato: `workdays`, `calendar_360` ou `calendar_365`. Em branco, é assumido `workdays` |
| `pre_fixed_calendar_base` | condicional | Base de contagem de dias da taxa pré-fixada. Obrigatória quando `interest_rate_type` é `pre_fixed` |
| `pre_fixed_monthly_rate` | condicional | Taxa mensal pré-fixada, em fração decimal menor que 1 e com até 8 casas: `0.015` significa 1,5% ao mês. Obrigatória quando `interest_rate_type` é `pre_fixed` |
| `post_fixed_calendar_base` | condicional | Base de contagem de dias da correção pós-fixada. Obrigatória quando `interest_rate_type` é `post_fixed` |
| `post_fixed_indexer` | condicional | Índice que corrige o contrato: `di`, `selic` ou `ipca`. Obrigatória quando `interest_rate_type` é `post_fixed` |
| `post_fixed_rate` | condicional | Taxa aplicada sobre o indexador. `1` significa 100% do índice. Obrigatória quando `interest_rate_type` é `post_fixed` |
| `post_fixed_lag_reference` | condicional | Unidade da defasagem do índice: `daily` ou `monthly`. Obrigatória quando `interest_rate_type` é `post_fixed` |
| `post_fixed_lag_amount` | condicional | Quantidade de defasagem, em número inteiro (ex.: `2` com `monthly` usa o índice de dois meses antes). Obrigatória quando `interest_rate_type` é `post_fixed` |
:::caution Ágio e dedução não entram no arquivo
O CSV de contrato parcelado não tem colunas de ágio ou dedução — elas não se aplicam a este tipo de ativo. O valor de aquisição é sempre o `total_purchase_value`.
:::
### Parcelas
| Coluna | Obrigatoriedade | Descrição |
|---|---|---|
| `installment_number` | obrigatória | Número da parcela, inteiro começando em 1. Uma linha por parcela |
| `installment_maturity_date` | obrigatória | Data de vencimento da parcela, em `AAAA-MM-DD`. As datas precisam crescer junto com o número da parcela |
| `installment_face_value` | obrigatória | Valor de face da parcela — quanto o sacado paga no vencimento. Ponto como separador decimal, até 8 casas |
| `installment_principal_value` | opcional | Parte do principal amortizada nesta parcela |
| `installment_external_id` | opcional | Identificador da parcela no seu sistema, até 50 caracteres |
### Sacado
| Coluna | Obrigatoriedade | Descrição |
|---|---|---|
| `borrower_name` | obrigatória | Nome completo do sacado, até 255 caracteres |
| `borrower_document_number` | obrigatória | CPF ou CNPJ do sacado, com pontuação e compatível com o `borrower_person_type` |
| `borrower_person_type` | obrigatória | `natural_person` (pessoa física) ou `legal_person` (pessoa jurídica) |
| `borrower_gender` | condicional | `male` ou `female`. Obrigatória quando `borrower_person_type` é `natural_person`; deixe em branco para pessoa jurídica |
| `borrower_mother_name` | opcional | Nome da mãe do sacado. Usado apenas para pessoa física |
| `borrower_birthdate` | opcional | Data de nascimento do sacado, em `AAAA-MM-DD`. Usada apenas para pessoa física |
| `borrower_email` | opcional | E-mail do sacado |
| `borrower_phone_area_code` | opcional | DDD do telefone, exatamente 2 dígitos. Se informar o DDD, informe também o número |
| `borrower_phone_number` | opcional | Telefone do sacado, 8 ou 9 dígitos, sem DDD e sem pontuação |
| `borrower_address_postal_code` | opcional | CEP no formato `00000-000`. Se preencher qualquer outro campo de endereço, o CEP passa a ser obrigatório |
| `borrower_address_street` | opcional | Logradouro, até 255 caracteres |
| `borrower_address_number` | opcional | Número do endereço, até 40 caracteres |
| `borrower_address_neighborhood` | opcional | Bairro, até 255 caracteres |
| `borrower_address_city` | opcional | Cidade, até 255 caracteres |
| `borrower_address_uf` | opcional | Sigla de 2 letras do estado, em maiúsculas (ex.: `SP`) |
| `borrower_address_country` | opcional | País em 3 letras (ex.: `BRA`) |
## Regras do arquivo
- **Uma linha por parcela, um `external_id` por contrato.** O contador de ativos do lote usa os `external_id` distintos.
- **As linhas do mesmo contrato precisam ser idênticas fora das colunas de parcela.** Todas as colunas cujo nome **não** contém `installment` são conferidas entre as linhas que compartilham o `external_id`; qualquer divergência aponta os campos diferentes e recusa o arquivo.
- **O fluxo de pagamento precisa ser crescente.** Parcela maior com vencimento anterior ao de uma parcela menor recusa o arquivo.
- **`installment_number` precisa formar a sequência `1, 2, 3, …`** dentro de cada contrato, ordenado por vencimento. Uma numeração com salto ou repetição faz o ativo ser recusado com o código `TRC000174`, sem derrubar os demais ativos do arquivo.
- **Todas as linhas precisam ter o mesmo `originator_document_number`**, e esse originador precisa estar cadastrado e vinculado à configuração de cessão.
- **Não inclua as colunas de recompra** (`assignor_document_number` e `settlement_type`): com elas o arquivo passa a ser lido como substituição e é recusado. Lote de substituição de contrato parcelado não é aceito por arquivo hoje.
- **O identificador do lote é único e definitivo.** Um lote recusado não pode ser reenviado com o mesmo identificador — envie um lote novo.
- **A validação é tudo ou nada na etapa de arquivo.** Uma linha inválida recusa o arquivo inteiro, e o relatório lista no máximo **50 erros** por envio.
## Erros mais comuns
| Mensagem | Causa |
|---|---|
| Coluna obrigatória ausente no cabeçalho | O cabeçalho foi editado ou salvo de um modelo antigo |
| Linhas com o mesmo identificador possuem dados inconsistentes nos campos: … | Alguma coluna que não é de parcela mudou entre as linhas do mesmo contrato |
| Fluxo de pagamento inválido para o ativo … | Vencimentos fora de ordem em relação ao número da parcela |
| Número da parcela … inválido | `installment_number` com texto, decimal ou em branco |
| O contrato … deve ter os números das parcelas em sequência iniciando em 1 | Salto ou repetição na numeração das parcelas (`TRC000174`) |
| O número de documento … não é válido | CPF ou CNPJ sem pontuação ou com dígito verificador inválido |
| Esse lote não pode receber esse tipo de ativo | O `asset_type` do arquivo não é o da configuração de cessão selecionada |
## Exemplo
```csv title="modelo_cessao_contrato_parcelado.csv (colunas principais)"
asset_type,external_id,contract_number,total_purchase_value,interest_rate_type,borrower_name,borrower_document_number,installment_number,installment_maturity_date,installment_face_value
contract,CONTRATO_0001,1144927986/XXX,900.00,pre_fixed,José de Souza,969.698.790-03,1,2026-12-25,500.46
contract,CONTRATO_0001,1144927986/XXX,900.00,pre_fixed,José de Souza,969.698.790-03,2,2027-01-25,500.46
contract,CONTRATO_0002,2244927986/XXX,450.00,post_fixed,Empresa Souza LTDA,11.222.333/0001-81,1,2026-12-25,500.46
```
O trecho acima mostra apenas as colunas principais, para leitura. O arquivo enviado precisa ter **todas** as colunas do modelo no cabeçalho — baixe o [modelo completo](/downloads/modelos_arquivo/modelo_cessao_contrato_parcelado.csv).
## Checklist antes de enviar
- [ ] Cabeçalho igual ao do modelo, sem colunas extras nem faltando
- [ ] `asset_type` igual a `contract` em todas as linhas, e igual ao tipo da configuração de cessão
- [ ] Uma linha por parcela, com o `external_id` repetido nas parcelas do mesmo contrato
- [ ] Colunas que não são de parcela idênticas entre as linhas do mesmo contrato
- [ ] `installment_number` em sequência de 1 a N, com vencimentos crescentes
- [ ] Colunas `pre_fixed_*` **ou** `post_fixed_*` preenchidas conforme o `interest_rate_type`
- [ ] `borrower_gender` preenchido para sacado pessoa física
- [ ] CPF/CNPJ com pontuação e dígito verificador válido
- [ ] Valores com ponto decimal e sem separador de milhar
- [ ] Arquivo salvo como CSV em UTF-8
---
# Layout CSV — Duplicatas, CT-e, Cheques e Notas Promissórias
URL: /documentation/iaas/negociacao_recebiveis/arquivo/csv_duplicatas_titulos
Layout do arquivo CSV de **cessão de duplicatas, CT-e, cheques e notas promissórias** (`asset_type` igual a `duplicata_mercantil`, `duplicata_servicos`, `cte`, `check` ou `promissory_note`) aceito pela QI DTVM. É um CSV com **uma linha por título**: cada linha é um ativo do lote. É uma alternativa à remessa [CNAB 444](/documentation/iaas/negociacao_recebiveis/arquivo/cnab444), que continua aceita para os mesmos títulos.
:::info Onde este arquivo é usado
Este é o arquivo enviado no fluxo descrito em [Cessão por Arquivo](/documentation/iaas/negociacao_recebiveis/arquivo/inicio), pelo portal do gestor ou do consultor, ou pela API da gestora. Para ceder duplicata ativo a ativo pela API, veja [Criação de Ativo — Duplicata](/documentation/iaas/negociacao_recebiveis/asset/criacao_duplicata).
:::
**📄 Baixar modelo CSV:** [duplicata mercantil](/downloads/modelos_arquivo/modelo_cessao_duplicata_mercantil.csv) · [duplicata de serviços](/downloads/modelos_arquivo/modelo_cessao_duplicata_servicos.csv) · [CT-e](/downloads/modelos_arquivo/modelo_cessao_cte.csv) · [cheque](/downloads/modelos_arquivo/modelo_cessao_check.csv) · [nota promissória](/downloads/modelos_arquivo/modelo_cessao_promissory_note.csv)
Todos os modelos têm o mesmo cabeçalho; cada um vem com uma linha de exemplo do seu tipo. Apague a linha de exemplo antes de colocar os seus dados.
## Estrutura do arquivo
| Item | Regra |
|---|---|
| **Cabeçalho** | 1 linha, sempre a primeira, com os nomes das colunas exatamente como no modelo |
| **Linhas de dados** | 1 por **título**. Cada linha é um ativo do lote |
| **Um tipo por arquivo** | Todas as linhas têm o `asset_type` da configuração de cessão selecionada. Para ceder duplicatas e cheques, por exemplo, envie um lote para cada configuração |
| **Extensão** | `.csv` |
| **Separador** | Vírgula (`,`) ou ponto e vírgula (`;`) — detectado a partir da linha de cabeçalho |
| **Codificação** | UTF-8 (com ou sem BOM) |
| **Datas** | Formato `AAAA-MM-DD` |
| **Valores** | Ponto como separador decimal, sem separador de milhar. `R$ 960,00` → `960.00` |
| **Documentos** | CPF em `000.000.000-00` e CNPJ em `00.000.000/0000-00`, sempre com a pontuação |
:::caution O cabeçalho é fechado
Use o cabeçalho do modelo sem alterações: não traduza, não renomeie e não acrescente colunas. Qualquer coluna fora do modelo, ou a falta de uma coluna obrigatória, recusa o arquivo inteiro antes de qualquer linha ser conferida. Colunas que não se aplicam ao título da linha (por exemplo, nota fiscal em um cheque) ficam no cabeçalho e em branco na linha.
:::
## Colunas
### Identificação
| Coluna | Obrigatoriedade | Descrição |
|---|---|---|
| `asset_type` | obrigatória | Tipo do título: `duplicata_mercantil`, `duplicata_servicos`, `cte`, `check` ou `promissory_note`. Precisa ser igual ao tipo da configuração de cessão, em todas as linhas |
| `external_id` | obrigatória | Identificador do título no seu sistema, até 25 caracteres. É a chave do ativo e não pode se repetir no arquivo |
| `order_number` | obrigatória | Número do título (seu número), até 45 caracteres. No cheque e na nota promissória é o número do próprio título, com até 20 caracteres |
| `originator_document_number` | obrigatória | CPF ou CNPJ do originador, com pontuação. Precisa estar cadastrado e vinculado à configuração de cessão, e ser o mesmo em todas as linhas do arquivo |
### Datas e valores
| Coluna | Obrigatoriedade | Descrição |
|---|---|---|
| `issue_date` | obrigatória | Data de emissão, em `AAAA-MM-DD`. Nas duplicatas e no CT-e é a data de emissão da nota; no cheque e na nota promissória, a do título |
| `maturity_date` | obrigatória | Data de vencimento do título, em `AAAA-MM-DD` |
| `face_value` | obrigatória | Valor de face — quanto o sacado paga no vencimento. Ponto como separador decimal, até 8 casas |
| `total_purchase_value` | obrigatória | Valor que o fundo paga pelo título (preço de aquisição). Não pode ser maior que o `face_value` |
### Nota fiscal
| Coluna | Obrigatoriedade | Descrição |
|---|---|---|
| `invoice_access_key` | condicional | Chave de acesso da NF-e ou do CT-e, exatamente 44 dígitos, sem espaços. O modelo (posições 21–22 da chave) precisa ser `55` na duplicata mercantil e `57` ou `67` no CT-e. Obrigatória para `duplicata_mercantil` e `cte`; opcional para `duplicata_servicos`; em branco para cheque e nota promissória |
| `invoice_number` | condicional | Número da nota fiscal, até 9 dígitos. Obrigatória para `duplicata_mercantil`, `duplicata_servicos` e `cte` |
| `invoice_serie` | opcional | Série da nota fiscal, até 3 caracteres. Em branco, é assumida a série `1` |
### Cheque
| Coluna | Obrigatoriedade | Descrição |
|---|---|---|
| `bank_code` | opcional | Código do banco do cheque, 3 dígitos |
| `agency` | opcional | Agência do cheque, até 5 dígitos |
### Sacado
| Coluna | Obrigatoriedade | Descrição |
|---|---|---|
| `borrower_name` | obrigatória | Nome completo do sacado, até 255 caracteres |
| `borrower_document_number` | obrigatória | CPF ou CNPJ do sacado, com pontuação e compatível com o `borrower_person_type` |
| `borrower_person_type` | obrigatória | `natural_person` (pessoa física) ou `legal_person` (pessoa jurídica) |
| `borrower_email` | opcional | E-mail do sacado |
| `borrower_phone_area_code` | opcional | DDD do telefone, exatamente 2 dígitos. Se informar o DDD, informe também o número |
| `borrower_phone_number` | opcional | Telefone do sacado, 8 ou 9 dígitos, sem DDD e sem pontuação |
| `borrower_address_postal_code` | obrigatória | CEP no formato `00000-000`. Os demais campos de endereço em branco são completados pelo CEP |
| `borrower_address_street` | opcional | Logradouro, até 255 caracteres |
| `borrower_address_number` | opcional | Número do endereço, até 40 caracteres |
| `borrower_address_neighborhood` | opcional | Bairro, até 255 caracteres |
| `borrower_address_city` | opcional | Cidade, até 255 caracteres |
| `borrower_address_uf` | opcional | Sigla de 2 letras do estado, em maiúsculas (ex.: `SP`) |
| `borrower_address_country` | opcional | País em 3 letras (ex.: `BRA`). Em branco, é assumido `BRA` |
## Regras do arquivo
- **Uma linha por título.** O `external_id` não pode se repetir no arquivo, e o contador de ativos do lote é o número de linhas.
- **Um tipo por arquivo.** O `asset_type` de todas as linhas precisa ser o da configuração de cessão; uma linha de outro tipo recusa o arquivo.
- **Nota fiscal conforme o tipo.** `duplicata_mercantil` exige `invoice_access_key` de modelo `55` e `cte` exige modelo `57` ou `67`, ambos com `invoice_number`; `duplicata_servicos` exige só `invoice_number`.
- **Cheque e nota promissória não têm nota fiscal.** O `order_number` é o número do título e a `issue_date` é a data de emissão. Banco e agência valem apenas para cheque.
- **O `face_value` não pode ser menor que o `total_purchase_value`.**
- **Todas as linhas precisam ter o mesmo `originator_document_number`**, e esse originador precisa estar cadastrado e vinculado à configuração de cessão.
- **Lote de substituição:** as linhas de recompra entram no mesmo CSV, com as colunas de recompra (`assignor_document_number`, `settlement_type` e `repurchase_value`) e as demais colunas em branco.
- **O identificador do lote é único e definitivo.** Um lote recusado não pode ser reenviado com o mesmo identificador — envie um lote novo.
- **A validação é tudo ou nada na etapa de arquivo.** Uma linha inválida recusa o arquivo inteiro, e o relatório lista no máximo **50 erros** por envio.
## Erros mais comuns
| Mensagem | Causa |
|---|---|
| A coluna obrigatória … está ausente no arquivo | O cabeçalho foi editado ou salvo de um modelo antigo |
| A coluna … não é reconhecida | Coluna de outro modelo (CCB, contrato) ou nome traduzido |
| O campo Chave de acesso da nota fiscal é obrigatório | Duplicata mercantil ou CT-e sem `invoice_access_key` |
| O campo Chave de acesso da nota fiscal deve ter 44 dígitos, com o modelo 55 (NF-e) … | Chave com espaços, pontuação, tamanho errado ou modelo que não é o do tipo (NF-e numa linha de CT-e, por exemplo) |
| O tipo de ativo … não é o da configuração da cessão | Linha com `asset_type` diferente do tipo da configuração selecionada |
| O identificador … está duplicado | Duas linhas com o mesmo `external_id` |
| O 'face_value' não pode ser menor que o 'total_purchase_value' | Preço de aquisição acima do valor de face |
## Exemplo
```csv title="modelo_cessao_duplicata_mercantil.csv (colunas principais)"
asset_type,external_id,order_number,issue_date,maturity_date,face_value,total_purchase_value,invoice_access_key,invoice_number
duplicata_mercantil,DUPLICATA_0001,000123-1,2026-11-01,2026-12-25,1000.00,960.00,35261153020654000143550010000001231000001230,000000123
duplicata_mercantil,DUPLICATA_0002,000124-1,2026-11-01,2027-01-25,1000.00,940.00,35261153020654000143550010000001241000001240,000000124
```
O trecho acima mostra apenas as colunas principais, para leitura. O arquivo enviado precisa ter **todas** as colunas do modelo no cabeçalho — baixe o modelo completo do seu tipo: [duplicata mercantil](/downloads/modelos_arquivo/modelo_cessao_duplicata_mercantil.csv) · [duplicata de serviços](/downloads/modelos_arquivo/modelo_cessao_duplicata_servicos.csv) · [CT-e](/downloads/modelos_arquivo/modelo_cessao_cte.csv) · [cheque](/downloads/modelos_arquivo/modelo_cessao_check.csv) · [nota promissória](/downloads/modelos_arquivo/modelo_cessao_promissory_note.csv).
## Checklist antes de enviar
- [ ] Cabeçalho igual ao do modelo, sem colunas extras nem faltando
- [ ] `asset_type` de todas as linhas igual ao tipo da configuração de cessão
- [ ] Um `external_id` diferente por linha, com até 25 caracteres
- [ ] Chave de acesso (44 dígitos) e número da nota nas duplicatas mercantis e CT-e
- [ ] Colunas de nota fiscal em branco nos cheques e notas promissórias
- [ ] `face_value` maior ou igual ao `total_purchase_value`
- [ ] CPF/CNPJ com pontuação e dígito verificador válido
- [ ] Valores com ponto decimal e sem separador de milhar
- [ ] Arquivo salvo como CSV em UTF-8
---
# Cessão por Arquivo
URL: /documentation/iaas/negociacao_recebiveis/arquivo/inicio
Além da inserção ativo a ativo pela API, é possível ceder um lote inteiro **enviando um único arquivo** pelo portal do gestor ou do consultor — ou, para a gestora, também pela API. O arquivo é validado linha a linha, convertido em ativos e segue exatamente o mesmo fluxo de elegibilidade, aprovação, termo de cessão e pagamento descrito na [Introdução](/documentation/iaas/negociacao_recebiveis/inicio).
:::info Envio por arquivo: portal ou API da gestora
No **portal** do gestor e do consultor, o envio é feito pela tela descrita abaixo. A **gestora** também pode enviar o arquivo pela API (`manager-api`, permissão de Escrita), em três chamadas:
1. `POST /trade_receivables_files/fund_class/{fund_class_key}/assignment_configuration/{assignment_configuration_key}/assignment` com `external_id`, `filename` (extensão `.rem`, `.txt` ou `.csv`), `assignment_type` (`assignment` ou `substitution_assignment`) e `assignment_date` (a data contábil aberta do fundo). A resposta traz em `bucket_link` a `url` e os `fields` de um upload por formulário (POST multipart), válido por 10 minutos.
2. Upload do arquivo para a `url` de `bucket_link`, com os `fields` devolvidos.
3. `PUT /trade_receivables_files/fund_class/{fund_class_key}/assignment_configuration/{assignment_configuration_key}/assignment/{assignment_external_id}/file_uploaded`, sem body, que dispara a validação do arquivo.
Esse fluxo ainda não tem página de referência; para detalhes, fale com [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br). Consultoria e cedente cedem pela API ativo a ativo, pelo fluxo de [criação de lote + inserção de ativos](/documentation/iaas/negociacao_recebiveis/fluxo_cessao).
:::
| | Envio por arquivo | Inserção pela API |
|---|---|---|
| **Como funciona** | Um arquivo com todos os ativos do lote | Uma requisição por ativo |
| **Formatos** | CNAB 444 (duplicatas, CT-e, cheques e notas promissórias), CNAB 400 (contratos parcelados) e CSV (duplicatas, CT-e, cheques, notas promissórias, CCB, honorários e contratos parcelados) | JSON |
| **Indicado para** | Quem já gera CNAB para bancos/FIDCs e quer reaproveitar o layout | Quem quer controle e retorno por ativo, em tempo real |
| **Retorno de erro** | Consolidado ao final da validação do arquivo | Imediato, na resposta de cada ativo |
| **Disponível em** | Portal do gestor e do consultor; API da gestora | API de integração |
Os dois caminhos produzem o mesmo lote e o mesmo resultado. Escolha um por lote — não é possível misturar arquivo e API no mesmo lote.
## Formatos aceitos
O formato é determinado pelo **tipo de ativo da configuração de cessão** que você seleciona na tela.
| Tipo de ativo da configuração | Formato do arquivo | Extensão | Manual | Modelo |
|---|---|---|---|---|
| `duplicata_mercantil` | **CNAB 444**, espécie `01`, ou **CSV** | `.rem` · `.txt` · `.csv` | Layout CNAB 444 · Layout CSV — Duplicatas e Títulos | [Exemplo](/downloads/modelos_arquivo/exemplo_cessao_duplicata_mercantil_cnab444.rem) · [Modelo CSV](/downloads/modelos_arquivo/modelo_cessao_duplicata_mercantil.csv) |
| `duplicata_servicos` | **CNAB 444**, espécie `14`, ou **CSV** | `.rem` · `.txt` · `.csv` | Layout CNAB 444 · Layout CSV — Duplicatas e Títulos | [Exemplo](/downloads/modelos_arquivo/exemplo_cessao_duplicata_servicos_cnab444.rem) · [Modelo CSV](/downloads/modelos_arquivo/modelo_cessao_duplicata_servicos.csv) |
| `cte` | **CNAB 444**, espécie `53`, ou **CSV** | `.rem` · `.txt` · `.csv` | Layout CNAB 444 · Layout CSV — Duplicatas e Títulos | [Exemplo](/downloads/modelos_arquivo/exemplo_cessao_cte_cnab444.rem) · [Modelo CSV](/downloads/modelos_arquivo/modelo_cessao_cte.csv) |
| `check` (cheque) e `promissory_note` (nota promissória) | **CNAB 444**, espécies `51`, `52` e `87` (cheque) e `02` e `06` (nota promissória), ou **CSV** | `.rem` · `.txt` · `.csv` | Layout CNAB 444 · Layout CSV — Duplicatas e Títulos | [Modelo CSV — cheque](/downloads/modelos_arquivo/modelo_cessao_check.csv) · [Modelo CSV — nota promissória](/downloads/modelos_arquivo/modelo_cessao_promissory_note.csv) |
| `ccb` e `structured_cci` | **CSV** | `.csv` | — | [Modelo](/downloads/modelos_arquivo/modelo_cessao_ccb.csv) |
| `legal_fees` (honorários advocatícios) | **CSV** | `.csv` | — | [Modelo](/downloads/modelos_arquivo/modelo_cessao_honorarios.csv) |
| `contract` (contratos parcelados) | **CNAB 400**, espécie `60` ou `61`, ou **CSV** | `.rem` · `.txt` · `.csv` | Layout CNAB 400 — Contratos Parcelados · Layout CSV — Contratos Parcelados | [Exemplo](/downloads/modelos_arquivo/exemplo_cessao_contrato_cnab400.rem) · [Modelo CSV](/downloads/modelos_arquivo/modelo_cessao_contrato_parcelado.csv) |
Em lotes de substituição, as linhas de recompra entram no mesmo CSV, com as colunas de recompra: [modelo de substituição](/downloads/modelos_arquivo/modelo_cessao_substituicao.csv).
:::caution Cada formato atende tipos específicos
Para **cessão de duplicatas, CT-e, cheques e notas promissórias** você escolhe entre o **CNAB 444** — o mesmo layout de remessa de cobrança usado no mercado, descrito em [Layout CNAB 444 — Cessão](/documentation/iaas/negociacao_recebiveis/arquivo/cnab444) — e o **CSV** descrito em [Layout CSV — Duplicatas, CT-e, Cheques e Notas Promissórias](/documentation/iaas/negociacao_recebiveis/arquivo/csv_duplicatas_titulos). CCB e honorários entram apenas por CSV. Contratos parcelados entram por CSV, descrito em [Layout CSV — Contratos Parcelados](/documentation/iaas/negociacao_recebiveis/arquivo/csv_contrato_parcelado), ou por remessa CNAB 400 de cobrança, descrita em [Layout CNAB 400 — Contratos Parcelados](/documentation/iaas/negociacao_recebiveis/arquivo/cnab400_contrato). O layout 400 só é aceito em configuração de contrato parcelado ou de contrato descontado.
Contratos descontados (`discounted_contract`) entram por remessa CNAB 400/444/500 com espécie `60` ou `61`, ou por CSV com o modelo disponível na tela de envio.
:::
## Fluxo do envio
## Passo a passo pela tela
No **portal do gestor** e no **portal do consultor**:
1. Acesse **Ativos › Cessões** e clique em **Nova cessão**.
2. Informe o **cedente** (CPF/CNPJ) e selecione a **configuração de cessão** — é ela que define o fundo, o tipo de ativo e, portanto, o formato de arquivo aceito.
3. Informe o **identificador do lote** e a **data da cessão**, que precisa ser a data contábil aberta do fundo — normalmente o dia útil corrente.
4. Marque **Substituição** se o lote tiver ativos de recompra.
5. Escolha o **meio de pagamento** ao cedente (Pix ou TED), quando aplicável.
6. Arraste o arquivo (`.rem`, `.txt` ou `.csv`) para a área de upload e confirme.
O lote passa a aparecer na listagem de cessões, com o status atualizado em tempo real conforme a validação avança.
:::info Permissões
O usuário precisa da permissão de criação de cessão por arquivo no fundo em questão. A concessão é feita pelo administrador do portal em **Usuários › Associações do fundo**.
:::
## Acompanhamento e retorno de erros
A listagem de cessões mostra o andamento do lote de arquivo:
| Etapa | O que significa | O que fazer |
|---|---|---|
| Aguardando arquivo | Lote criado, arquivo ainda não enviado | Faça o upload e confirme o envio |
| Validação em andamento | Arquivo recebido, sendo conferido linha a linha | Aguarde |
| Criando o lote | Arquivo válido, lote sendo criado | Aguarde |
| Inserindo os ativos | Cada linha está virando um ativo | Aguarde |
| Concluído | Todos os ativos inseridos | Acompanhe o lote pelo [fluxo de cessão](/documentation/iaas/negociacao_recebiveis/fluxo_cessao) |
| Recusado | Arquivo recusado na validação | Corrija o arquivo e envie um **lote novo**, com um novo identificador |
Quando o arquivo é recusado, o portal lista as linhas inválidas e, para cada uma, o campo, as posições no registro e a descrição do erro em português — por exemplo:
> Linha 1, posições 218–234: o CNPJ do sacado '45678912000199' é inválido. Verifique o número do documento e tente novamente.
:::caution Validação é tudo ou nada
Uma única linha inválida recusa o arquivo inteiro — não existe processamento parcial. A análise para após **50 erros encontrados**, então corrija os erros apontados e reenvie: podem existir outros adiante.
:::
## Regras que valem para qualquer arquivo
- **O identificador do lote é único e definitivo.** Um lote recusado não pode ser reenviado com o mesmo identificador.
- **A data da cessão precisa ser a data contábil aberta do fundo.** Outra data devolve erro na criação do lote.
- **O arquivo é imutável.** Para alterar qualquer informação, envie um lote novo.
- **Cada linha vira um ativo**, identificado pelo número do documento (posições 111–120 no CNAB). Em arquivos de duplicata e CT-e, **duas linhas com o mesmo número de documento derrubam a cessão inteira** — cada título precisa de um número próprio. No CSV de duplicatas e títulos vale o mesmo: cada linha precisa de um `external_id` próprio. Em CSV de CCB e de contrato parcelado, ao contrário, várias linhas com o mesmo identificador são lidas como as parcelas de um mesmo contrato.
- **O cedente e o originador precisam estar previamente cadastrados** e vinculados à configuração de cessão — veja [Homologação de Cedente](/documentation/iaas/homologacao_cedente/contrato_de_cessao/pedido_de_contrato).
:::info Envio por SFTP
Para operações de alto volume, a QI DTVM também disponibiliza a esteira de remessa por SFTP, com diretório dedicado por fundo e cedente e arquivo de retorno com os erros. É uma configuração sob demanda — fale com [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br).
:::
---
# Criação de Ativo — CCB
URL: /documentation/iaas/negociacao_recebiveis/asset/criacao_co
Endpoint para inserir um ativo do tipo **CCB** (Cédula de Crédito Bancário) em um lote de cessão. Cada ativo representa uma operação de crédito que será cedida ao fundo. O mesmo contrato vale para `structured_cci`.
:::info Disponível em
| Perfil | Host | Permissão exigida |
| ----------- | ---------------- | -------------------------------------------- |
| Gestora | `manager-api` | Escrita |
| Consultoria | `consultant-api` | Lotes |
| Cedente | `assignor-api` | Escrita |
URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts).
:::
:::tip Onde estou no fluxo?
Este é o **2º passo** do fluxo de cessão. Antes, você deve ter [criado o lote](/documentation/iaas/negociacao_recebiveis/assignment/criacao). Após inserir os ativos, envie o [lastro](/documentation/iaas/negociacao_recebiveis/asset/documents) exigido de cada um e [encerre a inserção](/documentation/iaas/negociacao_recebiveis/assignment/fechamento).
:::
:::caution Atenção
O campo `external_id` da operação de crédito identifica o ativo dentro do lote e não deve ser confundido com o `external_id` do lote.
:::
## Request
ENDPOINT /trade_receivables/fund_class/{fund_class_key}/assignment_configuration/{assignment_configuration_key}/assignment/{assignment_external_id}/asset
MÉTODO POST
```json title="Request Body"
{
"asset_type": "ccb",
"total_purchase_value": 1351.66,
"premiums": [
{
"premium_type": "spread",
"total_value": 13.38
}
],
"credit_operation": {
"contract": {
"number": "0008309052/NBF",
"disbursement_date": "2023-07-06",
"issue_date": "2023-07-06",
"signature_date": "2023-07-06",
"issue_value": 1338.28
},
"amortization_type": "sac",
"borrower": {
"name": "Empresa Exemplo Ltda",
"document_number": "11.222.333/0001-81",
"person_type": "legal_person",
"email": "financeiro@empresaexemplo.com.br",
"address": {
"street": "Pátio de Teixeira",
"number": "1",
"neighborhood": "Estrela do Oriente",
"city": "Rondônia",
"postal_code": "01012-030",
"uf": "RO",
"country": "BRA"
},
"phone": {
"area_code": "11",
"number": "936360268"
},
"legal_person": {
"activity_code": "11.11-1-11"
}
},
"delay": {
"fine": {
"fine_type": "percentage",
"percentage_value": 0.0
},
"interest": {
"method": "compound",
"pre_fixed": {
"monthly_rate": 0.0,
"calendar_base": "calendar_360"
}
}
},
"principal_value": 1338.28,
"interest_rate_type": "pre_fixed",
"external_id": "ccf6f331-d55f-46c0-a32f-fb909884dbb2",
"originator_document_number": "22.333.444/0001-81",
"pre_fixed": {
"calendar_base": "calendar_365",
"monthly_rate": 0.018
},
"installments": [
{
"maturity_date": "2023-10-01",
"installment_number": 1,
"face_value": 689.33
},
{
"maturity_date": "2024-10-01",
"installment_number": 2,
"face_value": 482.53
},
{
"maturity_date": "2025-10-01",
"installment_number": 3,
"face_value": 300.36
},
{
"maturity_date": "2026-10-01",
"installment_number": 4,
"face_value": 162.77
},
{
"maturity_date": "2027-10-01",
"installment_number": 5,
"face_value": 81.39
},
{
"maturity_date": "2028-10-01",
"installment_number": 6,
"face_value": 40.69
}
],
"modality_code": "0202",
"consignee": {
"consignee_type": "inss",
"name": "Consignee name",
"document_number": "33.444.555/0001-81"
},
"collaterals": [
{
"collateral_type": "social_security",
"benefit_number": "0000000000",
"benefit_type": "benefit_type",
"status": "reserved"
}
]
}
}
```
### Atributos do body
| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `asset_type` | string | obrigatório | Tipo do ativo. Para CCB, informar `ccb`. |
| `total_purchase_value` | number | obrigatório | Valor total da compra do ativo — efetivamente quanto o cessionário vai pagar. Até 2 casas decimais. |
| `premiums` | array | opcional | Lista de ágios envolvidos na venda. Veja [Atributos de `premiums`](#atributos-de-premiums). |
| `deductions` | array | opcional | Lista de deságios envolvidos na venda. Veja [Atributos de `deductions`](#atributos-de-deductions). |
| `credit_operation` | object | obrigatório | Dados da operação de crédito. Veja [Atributos de `credit_operation`](#atributos-de-credit_operation). |
:::info Ágios e deságios entram na conferência de valor
Na inserção, a QI Tech calcula o valor presente das parcelas e o compara com o valor de compra do ativo: `total_purchase_value` − soma de `premiums` + soma de `deductions`. Diferenças pequenas são registradas automaticamente como ajuste (`math_adjustment`); acima disso, a inserção devolve `TRC100014`.
:::
#### Atributos de `premiums`
| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `premium_type` | string | obrigatório | Tipo do ágio: `spread`, `math_adjustment`, `banker_fee`, `transaction_fee` ou `originator_fee`. |
| `total_value` | number | obrigatório | Valor total do ágio. Mínimo `0.01`. Até 2 casas decimais. |
#### Atributos de `deductions`
| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `deduction_type` | string | obrigatório | Tipo do deságio: `bad_debt_discount` ou `math_adjustment`. |
| `total_value` | number | obrigatório | Valor total do deságio. Mínimo `0.01`. Até 2 casas decimais. |
#### Atributos de `credit_operation`
| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `external_id` | string | obrigatório | Chave única de identificação deste ativo no sistema do parceiro. Máximo de 50 caracteres. |
| `originator_document_number` | string | obrigatório | CPF ou CNPJ formatado (`000.000.000-00` ou `00.000.000/0000-00`) do originador que viabilizou a operação. Precisa estar cadastrado na QI Tech; caso contrário, devolve `TRC000019`. |
| `principal_value` | number | obrigatório | Principal total em aberto da operação. Até 8 casas decimais. |
| `contract` | object | obrigatório | Dados do contrato. Veja [Atributos de `contract`](#atributos-de-contract). |
| `borrower` | object | obrigatório | Dados do sacado/devedor. Veja [Atributos de `borrower`](#atributos-de-borrower). |
| `amortization_type` | string | obrigatório | Tipo de amortização utilizado no cálculo. |
| `interest_rate_type` | string | obrigatório | Tipo de juros da operação. |
| `pre_fixed` | object | condicional | Dados do cálculo da parte pré-fixada. Obrigatório quando `interest_rate_type` for `pre_fixed`. Veja [Atributos de `pre_fixed`](#atributos-de-pre_fixed). |
| `post_fixed` | object | condicional | Dados do cálculo da parte pós-fixada. Obrigatório quando `interest_rate_type` for `post_fixed`. Veja [Atributos de `post_fixed`](#atributos-de-post_fixed). |
| `installments` | array | obrigatório | Lista de parcelas da operação. Veja [Atributos de `installments`](#atributos-de-installments). |
| `delay` | object | obrigatório | Dados de multa e juros por atraso. Veja [Atributos de `delay`](#atributos-de-delay). |
| `modality_code` | string | opcional | Código de 4 dígitos que especifica a categoria ou tipo de operação financeira associada ao ativo. Quando omitido, vale o da configuração de cessão. |
| `b3_code` | string | opcional | Código do ativo na B3. Até 50 caracteres. Só é aceito quando a configuração de cessão usa registro `registry_transfer`, `deferred_registry` ou `external_registry`; nas demais, devolve `TRC000188`. |
| `b3_self_code` | string | opcional | Código próprio do ativo na B3. Até 50 caracteres. Mesma regra de `b3_code`. |
| `consignee` | object | opcional | Dados do ente consignante. Veja [Atributos de `consignee`](#atributos-de-consignee). |
| `collaterals` | array | opcional | Lista de garantias associadas à operação. Veja [Atributos de `collaterals`](#atributos-de-collaterals). |
**Enumeradores de `amortization_type`:**
| Valor | Descrição |
|---|---|
| `sac` | Amortização do tipo SAC. |
| `price` | Amortização do tipo Price. |
| `price_days` | Amortização do tipo Price com juros calculados por dias corridos. |
**Enumeradores de `interest_rate_type`:**
| Valor | Descrição |
|---|---|
| `pre_fixed` | Para operações pré-fixadas. Informe o objeto `pre_fixed`. |
| `post_fixed` | Para operações pós-fixadas. Informe o objeto `post_fixed`. |
#### Atributos de `contract`
| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `number` | string | obrigatório | Número do contrato. Máximo de 50 caracteres. |
| `disbursement_date` | string | obrigatório | Data de desembolso no formato `YYYY-MM-DD`. |
| `issue_date` | string | obrigatório | Data de emissão no formato `YYYY-MM-DD`. |
| `signature_date` | string | opcional | Data de assinatura do contrato no formato `YYYY-MM-DD`. |
| `issue_value` | number | obrigatório | Valor de emissão do contrato. Até 2 casas decimais. |
#### Atributos de `borrower`
| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `name` | string | obrigatório | Nome do sacado. Máximo de 255 caracteres. |
| `document_number` | string | obrigatório | CPF ou CNPJ do sacado. |
| `person_type` | string | obrigatório | Tipo de pessoa. |
| `email` | string | opcional | E-mail do sacado. Máximo de 255 caracteres. |
| `address` | object | opcional | Endereço do sacado. Veja [Atributos de `address`](#atributos-de-address). |
| `phone` | object | opcional | Telefone do sacado. Veja [Atributos de `phone`](#atributos-de-phone). |
**Enumeradores de `person_type`:**
| Valor | Descrição |
|---|---|
| `natural_person` | Pessoa Física. O CPF em `document_number` tem o dígito verificador conferido. Quando informado, incluir o objeto `natural_person` dentro de `borrower`. Veja [Atributos de `natural_person`](#atributos-de-natural_person). |
| `legal_person` | Pessoa Jurídica. Quando informado, incluir o objeto `legal_person` dentro de `borrower`. Veja [Atributos de `legal_person`](#atributos-de-legal_person). |
#### Atributos de `address`
| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `street` | string | opcional | Logradouro. Caso não tenha todas as informações, enviar o compilado neste campo. Máximo de 255 caracteres. |
| `number` | string | opcional | Número do endereço. Máximo de 40 caracteres. |
| `neighborhood` | string | opcional | Bairro. Máximo de 255 caracteres. |
| `city` | string | opcional | Cidade. Máximo de 255 caracteres. |
| `uf` | string | opcional | Sigla do estado, em maiúsculas (ex.: `SP`). |
| `complement` | string | opcional | Complemento. Máximo de 255 caracteres. |
| `postal_code` | string | obrigatório | CEP no formato `00000-000`. Obrigatório sempre que o objeto `address` for informado. |
| `country` | string | opcional | País no formato ISO 3166-1 alpha-3. 3 caracteres. |
#### Atributos de `phone`
| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `area_code` | string | obrigatório | Código de área (DDD). 2 dígitos. |
| `number` | string | obrigatório | Número de telefone. 8 ou 9 dígitos. |
| `international_dial_code` | string | opcional | Código internacional (DDI). Até 3 caracteres. |
#### Atributos de `natural_person`
| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `birthdate` | string | opcional | Data de nascimento no formato `YYYY-MM-DD`. |
| `gender` | string | opcional | Gênero. |
| `mother_name` | string | opcional | Nome da mãe. Máximo de 255 caracteres. |
**Enumeradores de `gender`:**
| Valor | Descrição |
|---|---|
| `male` | Masculino. |
| `female` | Feminino. |
#### Atributos de `legal_person`
| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `foundation_date` | string | opcional | Data de fundação no formato `YYYY-MM-DD`. |
| `activity_code` | string | opcional | Código de atividade (CNAE) no formato `11.11-1-11`. |
| `annual_revenues` | integer | opcional | Receita anual em centavos. |
| `representatives` | array | opcional | Lista de representantes legais. Veja [Atributos de `representatives`](#atributos-de-representatives). |
#### Atributos de `representatives`
| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `name` | string | obrigatório | Nome do representante. Máximo de 255 caracteres. |
| `document_number` | string | obrigatório | CPF ou CNPJ do representante. |
| `email` | string | obrigatório | E-mail do representante. Máximo de 255 caracteres. |
| `phone` | object | obrigatório | Telefone. Mesma estrutura de [Atributos de `phone`](#atributos-de-phone). |
| `address` | object | obrigatório | Endereço. Mesma estrutura de [Atributos de `address`](#atributos-de-address). |
| `person_type` | string | opcional | Tipo de pessoa (`natural_person` ou `legal_person`). |
| `representative_type` | string | opcional | Tipo do representante. Máximo de 50 caracteres. |
#### Atributos de `pre_fixed`
| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `calendar_base` | string | obrigatório | Base de cálculo utilizada. |
| `monthly_rate` | number | obrigatório | Taxa mensal do contrato, em fração decimal entre 0 e 1. Para 1%, informar `0.01`. Até 8 casas decimais. |
| `nominal_monthly_rate` | number | opcional | Taxa mensal nominal do contrato, no mesmo formato de `monthly_rate`. |
**Enumeradores de `calendar_base`:**
| Valor | Descrição |
|---|---|
| `workdays` | Base de cálculo em dias úteis (252). |
| `calendar_365` | Base de cálculo em 365 dias. |
| `calendar_360` | Base de cálculo em 360 dias. |
#### Atributos de `post_fixed`
| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `calendar_base` | string | obrigatório | Base de contagem de dias da correção. Mesmos enumeradores de [`calendar_base`](#atributos-de-pre_fixed). |
| `indexer` | string | obrigatório | Índice que corrige a operação: `di`, `selic` ou `ipca`. |
| `rate` | number | obrigatório | Taxa aplicada sobre o indexador. Para 100% do DI, informar `1`. |
| `lag` | object | obrigatório | Defasagem do índice: `reference` (`daily` ou `monthly`) e `amount` (quantidade). Para usar o índice de dois meses antes, informar `{"reference": "monthly", "amount": 2}`. |
#### Atributos de `installments`
| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `maturity_date` | string | obrigatório | Data de vencimento da parcela no formato `YYYY-MM-DD`. |
| `installment_number` | integer | obrigatório | Número da parcela. |
| `face_value` | number | obrigatório | Valor de face da parcela. Até 8 casas decimais. |
| `principal_value` | number | opcional | Principal esperado a ser amortizado na data de vencimento. Até 8 casas decimais. |
| `external_id` | string | opcional | Identificador da parcela no seu sistema. |
#### Atributos de `delay`
| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `fine` | object | obrigatório | Dados da multa por atraso. Veja [Atributos de `fine`](#atributos-de-fine). Sem multa, envie `fine_type` `percentage` com `percentage_value` `0`. |
| `interest` | object | obrigatório | Dados do juros de mora. Veja [Atributos de `interest`](#atributos-de-interest). Sem juros de mora, envie `monthly_rate` `0`. |
#### Atributos de `fine`
| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `fine_type` | string | obrigatório | Tipo da multa. |
| `percentage_value` | number | condicional | Valor da multa quando `fine_type` for `percentage`. De 0 a 1, representando 0% a 100%. Até 2 casas decimais. |
| `amount` | number | condicional | Valor fixo da multa quando `fine_type` for `fixed`. Até 2 casas decimais. |
**Enumeradores de `fine_type`:**
| Valor | Descrição |
|---|---|
| `percentage` | Multa percentual sobre o valor da parcela. |
| `fixed` | Valor fixo de multa. |
#### Atributos de `interest`
| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `method` | string | obrigatório | Método do juros de mora. |
| `pre_fixed` | object | obrigatório | Taxa do juros de mora: `calendar_base` e `monthly_rate` **ou** `daily_rate`. Não aceita `nominal_monthly_rate`. Veja [Atributos de `pre_fixed` do juros de mora](/documentation/iaas/negociacao_recebiveis/asset/criacao_cte#atributos-de-pre_fixed). |
**Enumeradores de `method`:**
| Valor | Descrição |
|---|---|
| `compound` | Juros de mora composto. |
| `simple` | Juros de mora simples. |
| `pre_fixed` | Juros de mora pré-fixado. |
#### Atributos de `consignee`
| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `name` | string | opcional | Nome do ente consignante. Máximo de 255 caracteres. |
| `document_number` | string | obrigatório | CPF ou CNPJ do ente consignante. |
| `consignee_type` | string | obrigatório | Tipo de consignado. |
**Enumeradores de `consignee_type`:**
| Valor | Descrição |
|---|---|
| `public` | Consignado público. |
| `private` | Consignado privado. |
| `inss` | Consignado INSS. |
#### Atributos de `collaterals`
| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `collateral_type` | string | obrigatório | Tipo de garantia. |
:::info Como montar `collaterals`
`collaterals` é uma lista e cada item representa **uma** garantia. O `collateral_type` determina quais campos aquele item aceita — os campos de um tipo não são aceitos em outro. Qualquer propriedade fora do conjunto do tipo informado é recusada com `QIT000001`.
:::
**Enumeradores de `collateral_type`:**
| Valor | Descrição |
|---|---|
| `fgts` | Garantia de FGTS. Incluir os campos de [Atributos de garantia FGTS](#atributos-de-garantia-fgts). |
| `social_security` | Garantia de INSS. Incluir os campos de [Atributos de garantia INSS](#atributos-de-garantia-inss). |
| `home_equity` | Garantia de imóveis. Incluir os campos de [Atributos de garantia imóvel](#atributos-de-garantia-imovel). |
| `vehicle` | Garantia de veículo. Incluir os campos de [Atributos de garantia veículo](#atributos-de-garantia-veiculo). |
#### Atributos de garantia FGTS
| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `protocol_number` | string | obrigatório | Número do protocolo. |
| `status` | string | obrigatório | Status da garantia. |
#### Atributos de garantia INSS
| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `benefit_number` | string | obrigatório | Número do benefício. |
| `benefit_type` | string | obrigatório | Tipo do benefício. |
| `status` | string | obrigatório | Status da garantia. |
#### Atributos de garantia imóvel
| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `enterprise_name` | string | obrigatório | Nome do empreendimento. |
| `registration_number` | string | obrigatório | Número do registro do imóvel. |
| `enterprise_document_number` | string | opcional | CPF ou CNPJ associado ao empreendimento. |
| `collateral_properties` | array | obrigatório | Lista de propriedades do imóvel. Veja [Atributos de `collateral_properties`](#atributos-de-collateral_properties). |
#### Atributos de `collateral_properties`
| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `address` | object | obrigatório | Endereço do imóvel. Mesma estrutura de [Atributos de `address`](#atributos-de-address). |
| `total_collateral_value` | number | obrigatório | Valor do imóvel. Até 8 casas decimais. |
#### Atributos de garantia veículo
| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `vehicle_loan_value` | number | opcional | Valor financiado do veículo. Não pode ser negativo. |
| `vehicle_total_market_value` | number | opcional | Valor de mercado total do veículo. Não pode ser negativo. |
| `vehicle_identification` | object | obrigatório | Identificação do veículo. Veja [Atributos de `vehicle_identification`](#atributos-de-vehicle_identification). |
```json title="Exemplo de garantia de veículo"
{
"collateral_type": "vehicle",
"vehicle_loan_value": 30000.00,
"vehicle_total_market_value": 55000.00,
"vehicle_identification": {
"brand": "Toyota",
"model": "Corolla XEi 2.0",
"manufacturing_year": 2022,
"chassis_number": "9BRBLWHEXK0123456",
"license_plate": "ABC1D23",
"renavam": "12345678901"
}
}
```
#### Atributos de `vehicle_identification`
| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `brand` | string | opcional | Marca do veículo. |
| `model` | string | obrigatório | Modelo do veículo. |
| `manufacturing_year` | integer | obrigatório | Ano de fabricação do veículo. Mínimo 1900. |
| `chassis_number` | string | obrigatório | Número do chassi do veículo. |
| `license_plate` | string | opcional | Placa do veículo. |
| `renavam` | string | opcional | Código RENAVAM do veículo. |
## Response
STATUS 201
```json title="Response Body"
{
"asset_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3",
"external_id": "ccf6f331-d55f-46c0-a32f-fb909884dbb2",
"status": "pending_eligibility"
}
```
### Atributos da resposta
| Campo | Tipo | Descrição |
|---|---|---|
| `asset_key` | string | Identificador único do ativo gerado pela QI Tech (UUID). |
| `external_id` | string | A mesma chave externa fornecida no campo `external_id` da `credit_operation`. |
| `status` | string | Status inicial do ativo. Sempre retorna `pending_eligibility`, indicando que o ativo foi inserido e aguarda análise de elegibilidade. |
## Erros
| Status | Código | Quando acontece |
|---|---|---|
| 400 | `QIT000001` | O request body não segue o formato esperado: campo obrigatório ausente, tipo ou formato inválido. A `description` aponta o campo. |
| 404 | `TRC000018` | Não existe lote com esse `assignment_external_id` nesta configuração de cessão. |
| 404 | `TRC000015` | O `asset_type` não existe. |
| 400 | `TRC000025` | O `asset_type` é diferente do tipo de ativo da configuração de cessão. |
| 400 | `TRC000022` | O lote não aceita mais ativos: a inserção já foi encerrada. Para incluir mais, [reabra o lote](/documentation/iaas/negociacao_recebiveis/asset/remocao_ativos). |
| 400 | `TRC000009` | CPF ou CNPJ inválido em `originator_document_number` ou no `document_number` de um sacado pessoa física. |
| 404 | `TRC000019` | Não há originador cadastrado com o `originator_document_number` informado. Apesar do título (*Originator bond not found*), o erro não se refere ao vínculo com a configuração. |
| 400 | `TRC000188` | `b3_code` ou `b3_self_code` enviados numa configuração cujo tipo de registro não os aceita. |
| 409 | `TRC000054` | Já existe um ativo com esse `external_id` neste lote. |
| 400 | `TRC100014` | O valor presente do fluxo de parcelas não bate com o valor de compra (`total_purchase_value`, ágios e deságios). |
| 400 | `TRC100004` / `TRC100005` | Parcelas sem numeração sequencial ou fora de ordem crescente de vencimento. |
| 400 | `TRC100009` | `issue_value` menor que o principal da operação. |
| 409 | `TRC100017` | O fundo não pode comprar ativos vencidos. |
Os códigos `TRC1000xx` vêm da validação financeira do ativo, feita na inserção. O corpo de erro segue o formato abaixo:
```json
{
"title": "Already Exist This External Id",
"description": "Already exist an asset with this External Id and asset_key->41d6ff41-1dac-4df7-9e50-d15210ec57f3",
"translation": "Ja existe um ativo com esse External Id e asset_key->41d6ff41-1dac-4df7-9e50-d15210ec57f3",
"code": "TRC000054"
}
```
Em caso de erro, reenvie a requisição. Duplicidade (`TRC000054`) significa que o recurso já existe: consulte-o em vez de recriar, pelo endpoint de [consulta de ativo](/documentation/iaas/negociacao_recebiveis/asset/recuperar_ativos). Mais em [Reenvio e duplicidade](/documentation/iaas/introducao/erros#reenvio-e-duplicidade).
Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros).
## Próximos passos
Após inserir o ativo, o fluxo continua com:
1. **[Envio do lastro](/documentation/iaas/negociacao_recebiveis/asset/documents)** — envie os documentos de lastro exigidos para cada ativo aprovado na elegibilidade.
2. **[Encerramento da inserção](/documentation/iaas/negociacao_recebiveis/assignment/fechamento)** — sinalize que todos os ativos foram inseridos para que o lote siga para a análise de elegibilidade.
---
# Criação de ativo — contrato parcelado
URL: /documentation/iaas/negociacao_recebiveis/asset/criacao_contract
Endpoint para inserir um ativo do tipo **Contrato Parcelado** em um lote de cessão. Cada ativo representa um contrato com um fluxo de parcelas — o contrato inteiro é cedido ao fundo em uma única requisição, com todas as suas parcelas.
:::info Disponível em
| Perfil | Host | Permissão exigida |
| ----------- | ---------------- | -------------------------------------------- |
| Gestora | `manager-api` | Escrita |
| Consultoria | `consultant-api` | Lotes |
| Cedente | `assignor-api` | Escrita |
URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts).
:::
:::tip Onde estou no fluxo?
Este é o **2º passo** do fluxo de cessão. Antes, você deve ter [criado o lote](/documentation/iaas/negociacao_recebiveis/assignment/criacao). Após inserir os ativos, envie o [lastro](/documentation/iaas/negociacao_recebiveis/asset/documents) exigido de cada um e [encerre a inserção](/documentation/iaas/negociacao_recebiveis/assignment/fechamento).
:::
:::tip Contrato descontado ou contrato parcelado?
Pense num contrato de 5 parcelas como uma cartela com 5 cupons.
- **[Contrato descontado](/documentation/iaas/negociacao_recebiveis/asset/criacao_discounted_contract)** (`discounted_contract`): você cede **cupons soltos**. Cada parcela é um ativo e vai numa requisição só dela.
- **[Contrato parcelado](/documentation/iaas/negociacao_recebiveis/asset/criacao_contract)** (`contract`): você cede **a cartela inteira**. O contrato é um ativo só e vai numa requisição, com as parcelas dentro.
| | Contrato descontado | Contrato parcelado |
|---|---|---|
| O ativo é | uma parcela | o contrato inteiro |
| Requisições por contrato | uma por parcela | uma |
| O que você precisa ter na hora | só a parcela que vai ceder | valor e vencimento de todas as parcelas que vai ceder |
| Preço (`total_purchase_value`) | de cada parcela | do contrato; a QI Tech reparte entre as parcelas |
| Como as parcelas são cedidas | uma a uma, cada uma no lote que você quiser | juntas, no mesmo ativo |
| Recusa na elegibilidade | sai só a parcela | sai o contrato inteiro |
| [Boleto](/documentation/iaas/boletos/campos_do_boleto) | um por parcela | um por parcela |
| [Pagamentos informados por você](/documentation/iaas/liquidacao_ativos/ativos/ativos) | todos os tipos de direito creditório, inclusive devolução, glosa e juros | só liquidação e amortização, do contrato ou de uma parcela |
| Prorrogar o vencimento | sim, parcela a parcela (`asset_extension`) | não |
| [Recompra](/documentation/iaas/negociacao_recebiveis/asset/criacao_repurchased_asset) | parcela a parcela | só o contrato inteiro |
| [Relatório de estoque](/documentation/iaas/relatorios_dtvm/assets_wallet_composition) | uma linha por parcela; a coluna de número do contrato traz o `order_number` | uma linha por parcela, com o número do contrato e o da parcela |
**Qual combina com a sua operação:**
- Vende parcelas aos poucos, escolhe quais vender ou precisa prorrogar, devolver ou recomprar parcelas soltas: **contrato descontado**.
- Vende o contrato como uma unidade, com um preço só, e todas as parcelas são conhecidas na hora da cessão: **contrato parcelado**.
O tipo não é escolhido no envio: ele vem da sua configuração de cessão, e o lote só aceita ativos desse tipo (`TRC000025`). Para ver o seu, consulte o `asset_type` na [listagem de configurações](/documentation/iaas/negociacao_recebiveis/listagem). Para mudar de tipo, fale com o time de integração.
:::
:::caution Atenção
O campo `external_id` do contrato identifica o ativo dentro do lote e não deve ser confundido com o `external_id` do lote.
:::
## Request
ENDPOINT /trade_receivables/fund_class/{fund_class_key}/assignment_configuration/{assignment_configuration_key}/assignment/{assignment_external_id}/asset
MÉTODO POST
```json title="Request Body"
{
"asset_type": "contract",
"total_purchase_value": 900.00,
"contract": {
"external_id": "80187a08-ea7d-44b2-b65c-131f1318e904",
"originator_document_number": "22.333.444/0001-81",
"contract_number": "1144927986/XXX",
"issue_date": "2026-11-01",
"interest_rate_type": "pre_fixed",
"calendar_base": "calendar_365",
"pre_fixed": {
"calendar_base": "calendar_365",
"monthly_rate": 0.015
},
"borrower": {
"name": "José de Souza",
"document_number": "969.698.790-03",
"person_type": "natural_person",
"email": "jose.souza@yopmail.com",
"address": {
"street": "Rua Gilberto Sabino",
"number": "215",
"neighborhood": "Pinheiros",
"city": "São Paulo",
"postal_code": "05245-020",
"uf": "SP",
"country": "BRA"
},
"phone": {
"area_code": "11",
"number": "26260447"
},
"natural_person": {
"birthdate": "1999-01-01",
"gender": "male",
"mother_name": "Maria de Souza"
}
},
"installments": [
{
"installment_number": 1,
"maturity_date": "2026-12-25",
"face_value": 500.46,
"principal_value": 450.00,
"external_id": "parcela-1"
},
{
"installment_number": 2,
"maturity_date": "2027-01-25",
"face_value": 500.46,
"principal_value": 450.00,
"external_id": "parcela-2"
}
],
"contract_data": {
"cost_center": "SP-01"
}
}
}
```
### Atributos do body
| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `asset_type` | string | obrigatório | Tipo do ativo. Para contrato parcelado, informar `contract`. |
| `total_purchase_value` | number | obrigatório | Valor total da compra do ativo — efetivamente quanto o cessionário vai pagar pelo contrato inteiro. Até 2 casas decimais. |
| `contract` | object | obrigatório | Dados do contrato. Veja [Atributos de `contract`](#atributos-de-contract). |
:::caution Ágios e deduções não se aplicam
Não envie `premiums` nem `deductions` em contrato parcelado: eles não são registrados para este tipo de ativo. O valor de aquisição do ativo é o `total_purchase_value` informado.
:::
#### Atributos de `contract`
| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `external_id` | string | obrigatório | Chave única de identificação deste ativo no sistema do parceiro. Máximo de 50 caracteres. |
| `originator_document_number` | string | obrigatório | CPF ou CNPJ do originador que viabilizou a operação, no formato `000.000.000-00` ou `00.000.000/0000-00`. O originador precisa estar cadastrado na QI Tech com esse documento; caso contrário, a inserção devolve `TRC000019`. |
| `contract_number` | string | obrigatório | Número do contrato. Máximo de 50 caracteres. Enviado exatamente como informado, sem normalização. |
| `borrower` | object | obrigatório | Dados do sacado/devedor do contrato. Veja [Atributos de `borrower`](#atributos-de-borrower). |
| `interest_rate_type` | string | obrigatório | Tipo de juros do contrato. |
| `installments` | array | obrigatório | Lista das parcelas do contrato. Precisa ter ao menos uma parcela. Veja [Atributos de `installments`](#atributos-de-installments). |
| `issue_date` | string | opcional | Data de emissão do contrato no formato `YYYY-MM-DD`. |
| `calendar_base` | string | opcional | Base de contagem de dias do contrato. Quando omitido, é assumido `workdays`. |
| `pre_fixed` | object | condicional | Dados da parte pré-fixada. Obrigatório quando `interest_rate_type` for `pre_fixed`. Veja [Atributos de `pre_fixed`](#atributos-de-pre_fixed). |
| `post_fixed` | object | condicional | Dados da parte pós-fixada. Obrigatório quando `interest_rate_type` for `post_fixed`. Veja [Atributos de `post_fixed`](#atributos-de-post_fixed). |
| `contract_data` | object | opcional | Objeto livre para informações adicionais do contrato. É armazenado e devolvido nas consultas e webhooks, sem interferir nos cálculos. |
**Enumeradores de `interest_rate_type`:**
| Valor | Descrição |
|---|---|
| `pre_fixed` | Para contratos pré-fixados. Informe o objeto `pre_fixed`. |
| `post_fixed` | Para contratos pós-fixados. Informe o objeto `post_fixed`. |
**Enumeradores de `calendar_base`:**
| Valor | Descrição |
|---|---|
| `workdays` | Base de cálculo em dias úteis (252). |
| `calendar_365` | Base de cálculo em 365 dias. |
| `calendar_360` | Base de cálculo em 360 dias. |
#### Atributos de `installments`
| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `installment_number` | integer | obrigatório | Número da parcela, começando em 1. Veja a regra de sequência abaixo. |
| `maturity_date` | string | obrigatório | Data de vencimento da parcela no formato `YYYY-MM-DD`. |
| `face_value` | number | obrigatório | Valor de face da parcela — quanto o sacado paga no vencimento. Maior que zero e até 8 casas decimais. |
| `principal_value` | number | opcional | Principal esperado a ser amortizado na data de vencimento. Até 8 casas decimais. |
| `external_id` | string | opcional | Chave de identificação da parcela no sistema do parceiro. Máximo de 50 caracteres. Em cessão com boleto, vira o número de controle do [boleto](/documentation/iaas/boletos/campos_do_boleto) da parcela: envie um valor único por parcela, com até 25 caracteres. |
:::caution Sequência das parcelas
Ordenando as parcelas pela `maturity_date`, os `installment_number` precisam formar a sequência `1, 2, 3, …` sem repetições e sem saltos. Uma numeração fora de ordem devolve o erro `TRC000174`.
:::
#### Atributos de `pre_fixed`
| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `calendar_base` | string | obrigatório | Base de contagem de dias utilizada na taxa. Mesmos enumeradores de [`calendar_base`](#atributos-de-contract). |
| `monthly_rate` | number | obrigatório | Taxa mensal do contrato, em fração decimal entre 0 e 1. Para 1,5% ao mês, informar `0.015`. Até 8 casas decimais. |
#### Atributos de `post_fixed`
| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `calendar_base` | string | obrigatório | Base de contagem de dias da correção. Mesmos enumeradores de [`calendar_base`](#atributos-de-contract). |
| `indexer` | string | obrigatório | Índice que corrige o contrato. |
| `rate` | number | obrigatório | Taxa aplicada sobre o indexador. Para 100% do DI, informar `1`. |
| `lag` | object | obrigatório | Defasagem entre a data do índice e a data da correção. Veja [Atributos de `lag`](#atributos-de-lag). |
**Enumeradores de `indexer`:**
| Valor | Descrição |
|---|---|
| `di` | Taxa DI, apurada pela B3. |
| `selic` | Taxa Selic. |
| `ipca` | IPCA. |
#### Atributos de `lag`
| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `reference` | string | obrigatório | Unidade da defasagem: `daily` (dias) ou `monthly` (meses). |
| `amount` | number | obrigatório | Quantidade de defasagem. Para usar o índice de dois meses antes, informar `2` com `reference` igual a `monthly`. |
#### Atributos de `borrower`
| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `name` | string | obrigatório | Nome do sacado. Máximo de 255 caracteres. |
| `document_number` | string | obrigatório | CPF ou CNPJ formatado do sacado. |
| `person_type` | string | obrigatório | Tipo de pessoa. |
| `email` | string | opcional | E-mail do sacado. Máximo de 255 caracteres. |
| `address` | object | opcional | Endereço do sacado. Veja [Atributos de `address`](#atributos-de-address). |
| `phone` | object | opcional | Telefone do sacado. Veja [Atributos de `phone`](#atributos-de-phone). |
**Enumeradores de `person_type`:**
| Valor | Descrição |
|---|---|
| `natural_person` | Pessoa Física. Quando informado, inclua o objeto `natural_person` dentro de `borrower`. Veja [Atributos de `natural_person`](#atributos-de-natural_person). |
| `legal_person` | Pessoa Jurídica. Quando informado, inclua o objeto `legal_person` dentro de `borrower`. Veja [Atributos de `legal_person`](#atributos-de-legal_person). |
#### Atributos de `address`
| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `postal_code` | string | obrigatório | CEP. 9 caracteres, no formato `00000-000`. Obrigatório sempre que o objeto `address` for informado. |
| `street` | string | opcional | Logradouro. Caso não tenha todas as informações, enviar o compilado neste campo. Máximo de 255 caracteres. |
| `number` | string | opcional | Número do endereço. Máximo de 40 caracteres. |
| `neighborhood` | string | opcional | Bairro. Máximo de 255 caracteres. |
| `city` | string | opcional | Cidade. Máximo de 255 caracteres. |
| `uf` | string | opcional | Sigla do estado. 2 caracteres. |
| `complement` | string | opcional | Complemento. Máximo de 255 caracteres. |
| `country` | string | opcional | País no formato ISO 3166-1 alpha-3. 3 caracteres. |
#### Atributos de `phone`
| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `area_code` | string | obrigatório | Código de área (DDD). 2 dígitos. |
| `number` | string | obrigatório | Número de telefone. 8 ou 9 dígitos. |
#### Atributos de `natural_person`
| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `birthdate` | string | opcional | Data de nascimento no formato `YYYY-MM-DD`. |
| `gender` | string | opcional | Gênero: `male` ou `female`. |
| `mother_name` | string | opcional | Nome da mãe. Máximo de 255 caracteres. |
#### Atributos de `legal_person`
| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `foundation_date` | string | opcional | Data de fundação no formato `YYYY-MM-DD`. |
| `activity_code` | string | opcional | Código de atividade (CNAE) no formato `11.11-1-11`. |
| `annual_revenues` | integer | opcional | Receita anual em centavos. |
| `representatives` | array | opcional | Lista de representantes legais. |
## Response
STATUS 201
```json title="Response Body"
{
"asset_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3",
"external_id": "80187a08-ea7d-44b2-b65c-131f1318e904",
"status": "pending_eligibility"
}
```
### Atributos da resposta
| Campo | Tipo | Descrição |
|---|---|---|
| `asset_key` | string | Identificador único do ativo gerado pela QI Tech (UUID). |
| `external_id` | string | A mesma chave externa fornecida no campo `external_id` do `contract`. |
| `status` | string | Status inicial do ativo. Sempre retorna `pending_eligibility`, indicando que o ativo foi inserido e aguarda análise de elegibilidade. |
:::info Valores calculados pela QI Tech
Na inserção do ativo, a QI Tech calcula e passa a devolver nas consultas e nos webhooks a taxa interna de retorno da compra (`purchase_irr`), a duration do contrato e o `purchase_value` de cada parcela — a fatia do `total_purchase_value` alocada a cada vencimento. Esses campos não devem ser enviados no request.
:::
## Erros
| Status | Código | Quando acontece |
|---|---|---|
| 400 | `QIT000001` | O request body não segue o formato esperado: campo obrigatório ausente, tipo ou formato inválido. A `description` aponta o campo. |
| 404 | `TRC000018` | Não existe lote com esse `assignment_external_id` nesta configuração de cessão. |
| 400 | `TRC000025` | O `asset_type` é diferente do tipo de ativo da configuração de cessão. |
| 400 | `TRC000084` | O objeto `contract` foi enviado com um `asset_type` diferente de `contract` (por exemplo, `financing_contract` ou `debt_acknowledgment`, que não são cedidos por este fluxo). |
| 400 | `TRC000174` | Ordenando as parcelas por `maturity_date`, os `installment_number` não formam a sequência `1, 2, 3, …`. |
| 400 | `TRC000022` | O lote não aceita mais ativos: a inserção já foi encerrada. Para incluir mais, [reabra o lote](/documentation/iaas/negociacao_recebiveis/asset/remocao_ativos). |
| 400 | `TRC000009` | CPF ou CNPJ inválido em `originator_document_number` ou no `document_number` de um sacado pessoa física. |
| 404 | `TRC000019` | Não há originador cadastrado com o `originator_document_number` informado. Confira se o documento está formatado exatamente como no cadastro. Apesar do título (*Originator bond not found*), o erro não se refere ao vínculo com a configuração. |
| 409 | `TRC000054` | Já existe um ativo com esse `external_id` neste lote. |
| 400 | `TRC1000xx` | A validação financeira do ativo recusou o fluxo. Exemplo: `TRC100014`, valor presente das parcelas diferente do `total_purchase_value`. |
O corpo de erro segue o formato abaixo:
```json
{
"title": "Contract must have an installment number sequence",
"description": "Contract 80187a08-ea7d-44b2-b65c-131f1318e904 must have installment numbers as a sequence starting at 1 ordered by maturity date",
"translation": "O contrato 80187a08-ea7d-44b2-b65c-131f1318e904 deve ter os numeros das parcelas em sequencia iniciando em 1 e ordenados pela data de vencimento",
"code": "TRC000174"
}
```
Em caso de erro, reenvie a requisição. Duplicidade (`TRC000054`) significa que o recurso já existe: consulte-o em vez de recriar, pelo endpoint de [consulta de ativo](/documentation/iaas/negociacao_recebiveis/asset/recuperar_ativos). Mais em [Reenvio e duplicidade](/documentation/iaas/introducao/erros#reenvio-e-duplicidade).
Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros).
## Próximos passos
Após inserir o ativo, o fluxo continua com:
1. **[Envio do lastro](/documentation/iaas/negociacao_recebiveis/asset/documents)** — envie, com `document_type` igual a `contract`, o PDF do contrato parcelado deste ativo (o contrato com o devedor, não o contrato de cessão). Um arquivo por ativo.
2. **[Encerramento da inserção](/documentation/iaas/negociacao_recebiveis/assignment/fechamento)** — sinalize que todos os ativos foram inseridos para que o lote siga para a análise de elegibilidade.
Para ceder contratos parcelados em volume, sem uma requisição por ativo, use a [Cessão por Arquivo](/documentation/iaas/negociacao_recebiveis/arquivo/csv_contrato_parcelado).
---
# Criação de Ativo — CTE
URL: /documentation/iaas/negociacao_recebiveis/asset/criacao_cte
Endpoint para inserir um ativo do tipo **CTE** (Conhecimento de Transporte Eletrônico) em um lote de cessão. O CTE é um documento fiscal eletrônico que comprova a prestação de serviço de transporte, utilizado como direito creditório na operação de cessão.
:::info Disponível em
| Perfil | Host | Permissão exigida |
| ----------- | ---------------- | -------------------------------------------- |
| Gestora | `manager-api` | Escrita |
| Consultoria | `consultant-api` | Lotes |
| Cedente | `assignor-api` | Escrita |
URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts).
:::
:::tip Onde estou no fluxo?
Este é o **2º passo** do fluxo de cessão. Antes, você deve ter [criado o lote](/documentation/iaas/negociacao_recebiveis/assignment/criacao). Após inserir os ativos, envie o [lastro](/documentation/iaas/negociacao_recebiveis/asset/documents) exigido de cada um e [encerre a inserção](/documentation/iaas/negociacao_recebiveis/assignment/fechamento).
:::
:::caution Atenção
O campo `external_id` do direito creditório identifica o ativo dentro do lote e não deve ser confundido com o `external_id` do lote.
:::
## Request
ENDPOINT /trade_receivables/fund_class/{fund_class_key}/assignment_configuration/{assignment_configuration_key}/assignment/{assignment_external_id}/asset
MÉTODO POST
```json title="Request Body"
{
"asset_type": "cte",
"total_purchase_value": 1231.21,
"discounted_credit_right": {
"external_id": "ccf6f331-d55f-46c0-a32f-fb909884dbb2",
"originator_document_number": "22.333.444/0001-81",
"maturity_date": "2023-12-10",
"order_number": "18923619954796912",
"face_value": 1023.01,
"person_type": "legal_person",
"borrower": {
"name": "Transportadora Exemplo Ltda",
"document_number": "11.222.333/0001-81",
"person_type": "legal_person",
"email": "contato@transportadora.com.br",
"address": {
"street": "Avenida Paulista",
"number": "1000",
"neighborhood": "Bela Vista",
"city": "São Paulo",
"postal_code": "01310-100",
"uf": "SP",
"country": "BRA"
},
"phone": {
"area_code": "11",
"number": "936360268"
},
"legal_person": {
"activity_code": "49.30-2-01"
}
},
"participant_control_number": "ICX841HWCPUGU4U101XPLDW8D",
"bankslip": {
"our_number": {
"number": 2,
"digit": "P"
}
},
"delay": {
"fine": {
"fine_type": "percentage",
"percentage_value": 0.0
},
"interest": {
"method": "pre_fixed",
"pre_fixed": {
"daily_rate": 0.0,
"calendar_base": "calendar_360"
}
}
},
"invoice": {
"access_key": "35231011222333000181570010000000011892361995",
"total_value": 1231.21,
"serie": "001",
"number": "958431587",
"issue_date": "2023-10-10"
}
}
}
```
### Atributos do body
| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `asset_type` | string | obrigatório | Tipo do ativo. Para CTE, informar `cte`. |
| `total_purchase_value` | number | obrigatório | Valor total da compra do ativo — efetivamente quanto o cessionário vai pagar. Até 2 casas decimais. |
| `discounted_credit_right` | object | obrigatório | Dados do direito creditório. Veja [Atributos de `discounted_credit_right`](#atributos-de-discounted_credit_right). |
#### Atributos de `discounted_credit_right`
| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `external_id` | string | obrigatório | Chave única de identificação deste ativo no sistema do parceiro. Máximo de 50 caracteres. |
| `originator_document_number` | string | obrigatório | CPF ou CNPJ formatado (`000.000.000-00` ou `00.000.000/0000-00`) do originador que viabilizou a operação. Precisa estar cadastrado na QI Tech; caso contrário, devolve `TRC000019`. |
| `maturity_date` | string | obrigatório | Data de vencimento no formato `YYYY-MM-DD`. |
| `order_number` | string | obrigatório | Número do pedido. Máximo de 45 caracteres. Sem ele, a inserção devolve `TRC000078`. Em cessão com boleto, os 10 últimos caracteres viram o número do documento do boleto. |
| `face_value` | number | obrigatório | Valor de face. Até 8 casas decimais. |
| `person_type` | string | opcional | Tipo de pessoa do sacado (`natural_person` ou `legal_person`). |
| `borrower` | object | obrigatório | Dados do sacado. Consulte os [Atributos de `borrower`](/documentation/iaas/negociacao_recebiveis/asset/criacao_co#atributos-de-borrower) na página de Criação de Ativo — CCB. |
| `invoice` | object | obrigatório | Dados do CT-e. Veja [Atributos de `invoice`](#atributos-de-invoice). Sem ele, a inserção devolve `TRC000075`. Não envie o objeto `contract` neste tipo de ativo (`TRC000076`). |
| `participant_control_number` | string | opcional | Número de controle do participante no sistema do parceiro. Máximo de 25 caracteres alfanuméricos. Em cessão com boleto, vira o número de controle do participante do boleto e deve ser enviado sempre, com valor único. Veja [Do ativo ao boleto](/documentation/iaas/boletos/campos_do_boleto). |
| `bankslip` | object | opcional | Dados do boleto. Veja [Atributos de `bankslip`](#atributos-de-bankslip). |
| `delay` | object | opcional | Dados de multa e juros por atraso. Veja [Atributos de `delay`](#atributos-de-delay). |
#### Atributos de `invoice`
| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `access_key` | string | obrigatório | Chave de acesso do CT-e. 44 caracteres. As posições 21 e 22 da chave precisam ser o modelo do documento (`57` ou `67`). |
| `total_value` | number | opcional | Valor total do CT-e. Até 2 casas decimais. |
| `serie` | string | obrigatório | Número de série do CT-e. Máximo de 3 caracteres. |
| `number` | string | obrigatório | Número do CT-e. Máximo de 9 caracteres. |
| `issue_date` | string | obrigatório | Data de emissão no formato `YYYY-MM-DD`. |
#### Atributos de `bankslip`
| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `our_number` | object | opcional | Dados do nosso número. Aplicável apenas quando o nosso número é emitido pelo cliente. Veja [Atributos de `our_number`](#atributos-de-our_number). |
#### Atributos de `our_number`
| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `number` | number | obrigatório | Nosso número. Número bancário para cobrança com registro. 1 a 11 caracteres numéricos. |
| `digit` | string | obrigatório | Dígito verificador de auto conferência do nosso número. 1 caractere alfanumérico. |
#### Atributos de `delay`
| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `fine` | object | obrigatório | Dados da multa por atraso. Veja [Atributos de `fine`](#atributos-de-fine). |
| `interest` | object | obrigatório | Dados do juros de mora. Veja [Atributos de `interest`](#atributos-de-interest). |
Quando enviar `delay`, informe `fine` e `interest`. Este objeto vale para todos os direitos creditórios (duplicatas e CT-e).
#### Atributos de `fine`
| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `fine_type` | string | obrigatório | Tipo da multa. |
| `percentage_value` | number | condicional | Valor da multa quando `fine_type` for `percentage`. De 0 a 1, representando 0% a 100%. Até 2 casas decimais. |
| `amount` | number | condicional | Valor fixo da multa quando `fine_type` for `fixed`. Até 2 casas decimais. |
**Enumeradores de `fine_type`:**
| Valor | Descrição |
|---|---|
| `percentage` | Multa percentual sobre o valor da parcela. |
| `fixed` | Valor fixo de multa. |
#### Atributos de `interest`
| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `method` | string | obrigatório | Método do juros de mora. |
| `pre_fixed` | object | obrigatório | Dados da taxa pré-fixada. Veja [Atributos de `pre_fixed`](#atributos-de-pre_fixed). |
**Enumeradores de `method`:**
| Valor | Descrição |
|---|---|
| `compound` | Juros de mora composto. |
| `simple` | Juros de mora simples. |
| `pre_fixed` | Juros de mora pré-fixado. |
#### Atributos de `pre_fixed`
| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `daily_rate` | number | condicional | Taxa diária. Para 1%, informar `0.01`. Informe `daily_rate` **ou** `monthly_rate`. |
| `monthly_rate` | number | condicional | Taxa mensal. Para 1%, informar `0.01`. Informe `daily_rate` **ou** `monthly_rate`. |
| `calendar_base` | string | obrigatório | Base de cálculo utilizada. |
**Enumeradores de `calendar_base`:**
| Valor | Descrição |
|---|---|
| `workdays` | Base de cálculo em dias úteis (252). |
| `calendar_365` | Base de cálculo em 365 dias. |
| `calendar_360` | Base de cálculo em 360 dias. |
## Response
STATUS 201
```json title="Response Body"
{
"asset_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3",
"external_id": "ccf6f331-d55f-46c0-a32f-fb909884dbb2",
"status": "pending_eligibility"
}
```
### Atributos da resposta
| Campo | Tipo | Descrição |
|---|---|---|
| `asset_key` | string | Identificador único do ativo gerado pela QI Tech (UUID). |
| `external_id` | string | A mesma chave externa fornecida no campo `external_id` do `discounted_credit_right`. |
| `status` | string | Status inicial do ativo. Sempre retorna `pending_eligibility`, indicando que o ativo foi inserido e aguarda análise de elegibilidade. |
## Erros
| Status | Código | Quando acontece |
|---|---|---|
| 400 | `QIT000001` | O request body não segue o formato esperado: campo obrigatório ausente, tipo ou formato inválido. A `description` aponta o campo. |
| 404 | `TRC000018` | Não existe lote com esse `assignment_external_id` nesta configuração de cessão. |
| 400 | `TRC000025` | O `asset_type` é diferente do tipo de ativo da configuração de cessão. |
| 400 | `TRC000022` | O lote não aceita mais ativos: a inserção já foi encerrada. Para incluir mais, [reabra o lote](/documentation/iaas/negociacao_recebiveis/asset/remocao_ativos). |
| 400 | `TRC000009` | CPF ou CNPJ inválido em `originator_document_number` ou no `document_number` de um sacado pessoa física. |
| 404 | `TRC000019` | Não há originador cadastrado com o `originator_document_number` informado. Apesar do título (*Originator bond not found*), o erro não se refere ao vínculo com a configuração. |
| 400 | `TRC000078` | `order_number` ausente. |
| 400 | `TRC000075` | Objeto `invoice` ausente. |
| 400 | `TRC000076` | Objeto `contract` enviado num CT-e. |
| 400 | `TRC000134` | `invoice.access_key` ausente. |
| 400 | `TRC000133` | `invoice.access_key` não é de um CT-e (modelo `57` ou `67` nas posições 21 e 22). |
| 409 | `TRC000054` | Já existe um ativo com esse `external_id` neste lote. |
| 409 | `TRC100026` | Já existe um direito creditório com esse `external_id` para o mesmo cedente na carteira do fundo. |
| 400 | `TRC1000xx` | A validação financeira do ativo recusou o payload. Exemplo: `TRC100017` (409), o fundo não compra ativos vencidos. |
O corpo de erro segue o formato abaixo:
```json
{
"title": "Already Exist This External Id",
"description": "Already exist an asset with this External Id and asset_key->41d6ff41-1dac-4df7-9e50-d15210ec57f3",
"translation": "Ja existe um ativo com esse External Id e asset_key->41d6ff41-1dac-4df7-9e50-d15210ec57f3",
"code": "TRC000054"
}
```
Em caso de erro, reenvie a requisição. Duplicidade (`TRC000054`) significa que o recurso já existe: consulte-o em vez de recriar, pelo endpoint de [consulta de ativo](/documentation/iaas/negociacao_recebiveis/asset/recuperar_ativos). Mais em [Reenvio e duplicidade](/documentation/iaas/introducao/erros#reenvio-e-duplicidade).
Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros).
## Próximos passos
Após inserir o ativo, o fluxo continua com:
1. **[Envio do lastro](/documentation/iaas/negociacao_recebiveis/asset/documents)** — envie os documentos de lastro exigidos para cada ativo aprovado na elegibilidade.
2. **[Encerramento da inserção](/documentation/iaas/negociacao_recebiveis/assignment/fechamento)** — sinalize que todos os ativos foram inseridos para que o lote siga para a análise de elegibilidade.
---
# Criação de ativo — contrato descontado
URL: /documentation/iaas/negociacao_recebiveis/asset/criacao_discounted_contract
Endpoint para inserir um ativo do tipo **Contrato Descontado** em um lote de cessão. Este tipo de ativo representa uma parcela de um contrato de crédito cujo direito creditório será cedido ao fundo.
:::info Disponível em
| Perfil | Host | Permissão exigida |
| ----------- | ---------------- | -------------------------------------------- |
| Gestora | `manager-api` | Escrita |
| Consultoria | `consultant-api` | Lotes |
| Cedente | `assignor-api` | Escrita |
URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts).
:::
:::tip Onde estou no fluxo?
Este é o **2º passo** do fluxo de cessão. Antes, você deve ter [criado o lote](/documentation/iaas/negociacao_recebiveis/assignment/criacao). Após inserir os ativos, envie o [lastro](/documentation/iaas/negociacao_recebiveis/asset/documents) exigido de cada um e [encerre a inserção](/documentation/iaas/negociacao_recebiveis/assignment/fechamento).
:::
:::caution Atenção
O campo `external_id` do direito creditório identifica o ativo dentro do lote e não deve ser confundido com o `external_id` do lote.
:::
:::tip Contrato descontado ou contrato parcelado?
Pense num contrato de 5 parcelas como uma cartela com 5 cupons.
- **[Contrato descontado](/documentation/iaas/negociacao_recebiveis/asset/criacao_discounted_contract)** (`discounted_contract`): você cede **cupons soltos**. Cada parcela é um ativo e vai numa requisição só dela.
- **[Contrato parcelado](/documentation/iaas/negociacao_recebiveis/asset/criacao_contract)** (`contract`): você cede **a cartela inteira**. O contrato é um ativo só e vai numa requisição, com as parcelas dentro.
| | Contrato descontado | Contrato parcelado |
|---|---|---|
| O ativo é | uma parcela | o contrato inteiro |
| Requisições por contrato | uma por parcela | uma |
| O que você precisa ter na hora | só a parcela que vai ceder | valor e vencimento de todas as parcelas que vai ceder |
| Preço (`total_purchase_value`) | de cada parcela | do contrato; a QI Tech reparte entre as parcelas |
| Como as parcelas são cedidas | uma a uma, cada uma no lote que você quiser | juntas, no mesmo ativo |
| Recusa na elegibilidade | sai só a parcela | sai o contrato inteiro |
| [Boleto](/documentation/iaas/boletos/campos_do_boleto) | um por parcela | um por parcela |
| [Pagamentos informados por você](/documentation/iaas/liquidacao_ativos/ativos/ativos) | todos os tipos de direito creditório, inclusive devolução, glosa e juros | só liquidação e amortização, do contrato ou de uma parcela |
| Prorrogar o vencimento | sim, parcela a parcela (`asset_extension`) | não |
| [Recompra](/documentation/iaas/negociacao_recebiveis/asset/criacao_repurchased_asset) | parcela a parcela | só o contrato inteiro |
| [Relatório de estoque](/documentation/iaas/relatorios_dtvm/assets_wallet_composition) | uma linha por parcela; a coluna de número do contrato traz o `order_number` | uma linha por parcela, com o número do contrato e o da parcela |
**Qual combina com a sua operação:**
- Vende parcelas aos poucos, escolhe quais vender ou precisa prorrogar, devolver ou recomprar parcelas soltas: **contrato descontado**.
- Vende o contrato como uma unidade, com um preço só, e todas as parcelas são conhecidas na hora da cessão: **contrato parcelado**.
O tipo não é escolhido no envio: ele vem da sua configuração de cessão, e o lote só aceita ativos desse tipo (`TRC000025`). Para ver o seu, consulte o `asset_type` na [listagem de configurações](/documentation/iaas/negociacao_recebiveis/listagem). Para mudar de tipo, fale com o time de integração.
:::
## Parcela e contrato
Neste tipo de ativo, **cada parcela é um ativo**. Um contrato de 5 parcelas vira 5 inserções, cada uma com o seu `external_id`, o seu `face_value` (o valor daquela parcela), o seu `maturity_date` e o seu `installment_number`. Você não envia os valores das demais parcelas.
O objeto `contract` identifica o contrato de origem e se repete, igual, em todas as parcelas do mesmo contrato:
- `number` agrupa as parcelas. É por ele que você filtra os ativos de um contrato na [consulta de ativos](/documentation/iaas/negociacao_recebiveis/asset/recuperar_ativos), e é ele que aparece no anexo do Termo de Cessão e identifica o ativo na recompra. Mantenha o mesmo valor em todas as parcelas.
- `issue_date` é a data de emissão do contrato e passa a ser a data de emissão do ativo.
- `total_face_value` e `number_of_installments` são informativos. Eles descrevem o contrato inteiro e não entram no preço, na elegibilidade nem no boleto. A QI Tech não confere esses valores contra as parcelas recebidas.
As parcelas podem ser cedidas em lotes diferentes, na ordem que você quiser. Não é preciso ceder todas, nem ceder a primeira antes das outras.
## Request
ENDPOINT /trade_receivables/fund_class/{fund_class_key}/assignment_configuration/{assignment_configuration_key}/assignment/{assignment_external_id}/asset
MÉTODO POST
```json title="Request Body"
{
"asset_type": "discounted_contract",
"total_purchase_value": 1231.21,
"discounted_credit_right": {
"external_id": "mdf27za1-ra5f-46c0-a32f-fb909884dbb2",
"originator_document_number": "22.333.444/0001-81",
"face_value": 1231.21,
"maturity_date": "2025-12-10",
"installment_number": 1,
"borrower": {
"name": "Natália Nascimento",
"document_number": "969.698.790-03",
"person_type": "natural_person",
"email": "natalia.nascimento@yopmail.com",
"address": {
"street": "Gilberto Sabino",
"number": "215",
"neighborhood": "Pinheiros",
"city": "São Paulo",
"postal_code": "05425-020",
"uf": "SP",
"country": "BRA"
},
"phone": {
"area_code": "11",
"number": "36360268"
},
"natural_person": {
"mother_name": "Lívia Santos",
"birthdate": "2001-01-05"
}
},
"participant_control_number": "CT958431587P01",
"contract": {
"number_of_installments": 5,
"total_face_value": 6156.05,
"number": "958431587",
"issue_date": "2023-10-10"
}
}
}
```
### Atributos do body
| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `asset_type` | string | obrigatório | Tipo do ativo. Para contrato descontado, informar `discounted_contract`. |
| `total_purchase_value` | number | obrigatório | Valor total da compra do ativo — efetivamente quanto o cessionário vai pagar. Até 2 casas decimais. |
| `discounted_credit_right` | object | obrigatório | Dados do direito creditório. Veja [Atributos de `discounted_credit_right`](#atributos-de-discounted_credit_right). |
#### Atributos de `discounted_credit_right`
| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `external_id` | string | obrigatório | Chave única de identificação deste ativo no sistema do parceiro. Máximo de 50 caracteres. |
| `originator_document_number` | string | obrigatório | CPF ou CNPJ formatado (`000.000.000-00` ou `00.000.000/0000-00`) do originador que viabilizou a operação. Precisa estar cadastrado na QI Tech; caso contrário, devolve `TRC000019`. |
| `face_value` | number | obrigatório | Valor de face. Até 8 casas decimais. |
| `maturity_date` | string | obrigatório | Data de vencimento da parcela no formato `YYYY-MM-DD`. |
| `installment_number` | integer | obrigatório | Número da parcela do contrato que este ativo representa. Sem ele, a inserção devolve `TRC000077`. |
| `participant_control_number` | string | opcional | Seu número de controle do ativo. Máximo de 25 caracteres. Em cessão com boleto, vira o número de controle do participante do boleto e deve ser enviado sempre, com valor único. Veja [Do ativo ao boleto](/documentation/iaas/boletos/campos_do_boleto). |
| `order_number` | string | opcional | Número do documento no seu sistema. Máximo de 45 caracteres. Em cessão com boleto, os 10 últimos caracteres viram o número do documento do boleto. |
| `bankslip` | object | opcional | Dados do boleto, quando o nosso número é emitido por você. Consulte os [Atributos de `bankslip`](/documentation/iaas/negociacao_recebiveis/asset/criacao_duplicata#atributos-de-bankslip) na página de Criação de Ativo — Duplicata. |
| `delay` | object | opcional | Multa e juros por atraso do boleto. Consulte os [Atributos de `delay`](/documentation/iaas/negociacao_recebiveis/asset/criacao_cte#atributos-de-delay) na página de Criação de Ativo — CTE. Sem ele, valem os encargos da configuração de cobrança do fundo. |
| `borrower` | object | obrigatório | Dados do sacado. Consulte os [Atributos de `borrower`](/documentation/iaas/negociacao_recebiveis/asset/criacao_co#atributos-de-borrower) na página de Criação de Ativo — CCB. |
| `contract` | object | obrigatório | Dados do contrato. Veja [Atributos de `contract`](#atributos-de-contract). Sem ele, a inserção devolve `TRC000075`. Não envie o objeto `invoice` neste tipo de ativo (`TRC000076`). |
#### Atributos de `contract`
| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `number_of_installments` | integer | obrigatório | Quantidade total de parcelas do contrato, cedidas ou não. Informativo. |
| `total_face_value` | number | obrigatório | Soma do valor de face de todas as parcelas do contrato, cedidas ou não. Informativo. Até 2 casas decimais. |
| `number` | string | obrigatório | Número do contrato no seu sistema. Máximo de 50 caracteres. Use o mesmo valor em todas as parcelas do contrato. |
| `issue_date` | string | obrigatório | Data de emissão do contrato no formato `YYYY-MM-DD`. Use a mesma data em todas as parcelas. |
Veja em [Parcela e contrato](#parcela-e-contrato) como cada campo é usado.
## Response
STATUS 201
```json title="Response Body"
{
"asset_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3",
"external_id": "mdf27za1-ra5f-46c0-a32f-fb909884dbb2",
"status": "pending_eligibility"
}
```
### Atributos da resposta
| Campo | Tipo | Descrição |
|---|---|---|
| `asset_key` | string | Identificador único do ativo gerado pela QI Tech (UUID). |
| `external_id` | string | A mesma chave externa fornecida no campo `external_id` do `discounted_credit_right`. |
| `status` | string | Status inicial do ativo. Sempre retorna `pending_eligibility`, indicando que o ativo foi inserido e aguarda análise de elegibilidade. |
## Erros
| Status | Código | Quando acontece |
|---|---|---|
| 400 | `QIT000001` | O request body não segue o formato esperado: campo obrigatório ausente, tipo ou formato inválido. A `description` aponta o campo. |
| 404 | `TRC000018` | Não existe lote com esse `assignment_external_id` nesta configuração de cessão. |
| 400 | `TRC000025` | O `asset_type` é diferente do tipo de ativo da configuração de cessão. |
| 400 | `TRC000022` | O lote não aceita mais ativos: a inserção já foi encerrada. Para incluir mais, [reabra o lote](/documentation/iaas/negociacao_recebiveis/asset/remocao_ativos). |
| 400 | `TRC000009` | CPF ou CNPJ inválido em `originator_document_number` ou no `document_number` de um sacado pessoa física. |
| 404 | `TRC000019` | Não há originador cadastrado com o `originator_document_number` informado. Apesar do título (*Originator bond not found*), o erro não se refere ao vínculo com a configuração. |
| 400 | `TRC000077` | `installment_number` ausente. |
| 400 | `TRC000075` | Objeto `contract` ausente. |
| 400 | `TRC000076` | Objeto `invoice` enviado num ativo `discounted_contract`. |
| 409 | `TRC000054` | Já existe um ativo com esse `external_id` neste lote. |
| 409 | `TRC100026` | Já existe um direito creditório com esse `external_id` para o mesmo cedente na carteira do fundo. |
| 400 | `TRC1000xx` | A validação financeira do ativo recusou o payload. Exemplo: `TRC100017` (409), o fundo não compra ativos vencidos. |
O corpo de erro segue o formato abaixo:
```json
{
"title": "Already Exist This External Id",
"description": "Already exist an asset with this External Id and asset_key->41d6ff41-1dac-4df7-9e50-d15210ec57f3",
"translation": "Ja existe um ativo com esse External Id e asset_key->41d6ff41-1dac-4df7-9e50-d15210ec57f3",
"code": "TRC000054"
}
```
Em caso de erro, reenvie a requisição. Duplicidade (`TRC000054`) significa que o recurso já existe: consulte-o em vez de recriar, pelo endpoint de [consulta de ativo](/documentation/iaas/negociacao_recebiveis/asset/recuperar_ativos). Mais em [Reenvio e duplicidade](/documentation/iaas/introducao/erros#reenvio-e-duplicidade).
Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros).
## Próximos passos
Após inserir o ativo, o fluxo continua com:
1. **[Envio do lastro](/documentation/iaas/negociacao_recebiveis/asset/documents)** — envie os documentos de lastro exigidos para cada ativo aprovado na elegibilidade.
2. **[Encerramento da inserção](/documentation/iaas/negociacao_recebiveis/assignment/fechamento)** — sinalize que todos os ativos foram inseridos para que o lote siga para a análise de elegibilidade.
---
# Criação de Ativo — Duplicata
URL: /documentation/iaas/negociacao_recebiveis/asset/criacao_duplicata
Endpoint para inserir um ativo do tipo **Duplicata** em um lote de cessão. Existem dois subtipos aceitos: **Duplicata Mercantil** (`duplicata_mercantil`) — vinculada a uma nota fiscal de venda de mercadorias — e **Duplicata de Serviços** (`duplicata_servicos`) — vinculada a uma nota fiscal de prestação de serviços.
:::info Disponível em
| Perfil | Host | Permissão exigida |
| ----------- | ---------------- | -------------------------------------------- |
| Gestora | `manager-api` | Escrita |
| Consultoria | `consultant-api` | Lotes |
| Cedente | `assignor-api` | Escrita |
URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts).
:::
:::info Diferença entre os tipos
Ambos os tipos utilizam a mesma estrutura de request body. As diferenças: na **duplicata mercantil**, a chave de acesso da NF-e é obrigatória e, após a elegibilidade, o documento da duplicata é gerado pela QI Tech a partir desses dados; na **duplicata de serviços**, a chave é opcional e os documentos exigidos são os definidos na configuração de cessão. Consulte a página de [Inserção de Documentos](/documentation/iaas/negociacao_recebiveis/asset/documents) para mais detalhes.
:::
:::tip Onde estou no fluxo?
Este é o **2º passo** do fluxo de cessão. Antes, você deve ter [criado o lote](/documentation/iaas/negociacao_recebiveis/assignment/criacao). Após inserir os ativos, envie o [lastro](/documentation/iaas/negociacao_recebiveis/asset/documents) exigido de cada um e [encerre a inserção](/documentation/iaas/negociacao_recebiveis/assignment/fechamento).
:::
:::caution Atenção
O campo `external_id` do direito creditório identifica o ativo dentro do lote e não deve ser confundido com o `external_id` do lote.
:::
## Request
ENDPOINT /trade_receivables/fund_class/{fund_class_key}/assignment_configuration/{assignment_configuration_key}/assignment/{assignment_external_id}/asset
MÉTODO POST
```json title="Request Body"
{
"asset_type": "duplicata_mercantil",
"total_purchase_value": 1231.21,
"discounted_credit_right": {
"external_id": "ccf6f331-d55f-46c0-a32f-fb909884dbb2",
"originator_document_number": "22.333.444/0001-81",
"maturity_date": "2023-12-10",
"order_number": "18923619954796912",
"face_value": 1023.01,
"person_type": "natural_person",
"borrower": {
"name": "Natália Nascimento",
"document_number": "969.698.790-03",
"person_type": "natural_person",
"email": "natalia.nascimento@yopmail.com",
"address": {
"street": "Gilberto Sabino",
"number": "215",
"neighborhood": "Pinheiros",
"city": "São Paulo",
"postal_code": "05425-020",
"uf": "SP",
"country": "BRA"
},
"phone": {
"area_code": "11",
"number": "36360268"
},
"natural_person": {
"mother_name": "Lívia Santos",
"birthdate": "2001-01-05"
}
},
"participant_control_number": "ICX841HWCPUGU4U101XPLDW8D",
"bankslip": {
"our_number": {
"number": 2,
"digit": "P"
}
},
"delay": {
"fine": {
"fine_type": "percentage",
"percentage_value": 0.0
},
"interest": {
"method": "pre_fixed",
"pre_fixed": {
"daily_rate": 0.0,
"calendar_base": "calendar_360"
}
}
},
"invoice": {
"access_key": "35231011222333000181551239584315871861703272",
"total_value": 1231.21,
"serie": "123",
"number": "958431587",
"issue_date": "2023-10-10"
}
}
}
```
### Atributos do body
| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `asset_type` | string | obrigatório | Tipo do ativo. Valores aceitos: `duplicata_mercantil` ou `duplicata_servicos`. |
| `total_purchase_value` | number | obrigatório | Valor total da compra do ativo — efetivamente quanto o cessionário vai pagar. Até 2 casas decimais. |
| `discounted_credit_right` | object | obrigatório | Dados do direito creditório. Veja [Atributos de `discounted_credit_right`](#atributos-de-discounted_credit_right). |
#### Atributos de `discounted_credit_right`
| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `external_id` | string | obrigatório | Chave única de identificação deste ativo no sistema do parceiro. Máximo de 50 caracteres. |
| `originator_document_number` | string | obrigatório | CPF ou CNPJ formatado (`000.000.000-00` ou `00.000.000/0000-00`) do originador que viabilizou a operação. Precisa estar cadastrado na QI Tech; caso contrário, devolve `TRC000019`. |
| `maturity_date` | string | obrigatório | Data de vencimento no formato `YYYY-MM-DD`. |
| `order_number` | string | obrigatório | Número do pedido. Máximo de 45 caracteres. Sem ele, a inserção devolve `TRC000078`. Em cessão com boleto, os 10 últimos caracteres viram o número do documento do boleto. |
| `face_value` | number | obrigatório | Valor de face. Até 8 casas decimais. |
| `person_type` | string | opcional | Tipo de pessoa do sacado (`natural_person` ou `legal_person`). |
| `borrower` | object | obrigatório | Dados do sacado. Consulte os [Atributos de `borrower`](/documentation/iaas/negociacao_recebiveis/asset/criacao_co#atributos-de-borrower) na página de Criação de Ativo — CCB. |
| `participant_control_number` | string | opcional | Número de controle do participante no sistema do parceiro. Máximo de 25 caracteres alfanuméricos. Em cessão com boleto, vira o número de controle do participante do boleto e deve ser enviado sempre, com valor único. Veja [Do ativo ao boleto](/documentation/iaas/boletos/campos_do_boleto). |
| `bankslip` | object | opcional | Dados do boleto. Veja [Atributos de `bankslip`](#atributos-de-bankslip). |
| `delay` | object | opcional | Dados de multa e juros por atraso. Consulte os [Atributos de `delay`](/documentation/iaas/negociacao_recebiveis/asset/criacao_cte#atributos-de-delay) na página de Criação de Ativo — CTE. |
| `invoice` | object | obrigatório | Dados da nota fiscal. Veja [Atributos de `invoice`](#atributos-de-invoice). Sem ele, a inserção devolve `TRC000075`. Não envie o objeto `contract` neste tipo de ativo (`TRC000076`). |
#### Atributos de `bankslip`
| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `our_number` | object | opcional | Dados do nosso número. Aplicável apenas quando o nosso número é emitido pelo cliente. Veja [Atributos de `our_number`](#atributos-de-our_number). |
#### Atributos de `our_number`
| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `number` | number | obrigatório | Nosso número. Número bancário para cobrança com registro. 1 a 11 caracteres numéricos. |
| `digit` | string | obrigatório | Dígito verificador de auto conferência do nosso número. 1 caractere alfanumérico. |
#### Atributos de `invoice`
| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `access_key` | string | condicional | Chave de acesso da NF-e, 44 caracteres. Obrigatória para `duplicata_mercantil` (`TRC000134`), e as posições 21 e 22 da chave precisam ser o modelo `55` (NF-e); outro modelo devolve `TRC000135`. Opcional para `duplicata_servicos`. |
| `total_value` | number | opcional | Valor total da nota fiscal. Até 2 casas decimais. |
| `serie` | string | obrigatório | Número de série da nota fiscal. Máximo de 3 caracteres. |
| `number` | string | obrigatório | Número da nota fiscal. Máximo de 9 caracteres. |
| `issue_date` | string | obrigatório | Data de emissão no formato `YYYY-MM-DD`. |
## Response
STATUS 201
```json title="Response Body"
{
"asset_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3",
"external_id": "ccf6f331-d55f-46c0-a32f-fb909884dbb2",
"status": "pending_eligibility"
}
```
### Atributos da resposta
| Campo | Tipo | Descrição |
|---|---|---|
| `asset_key` | string | Identificador único do ativo gerado pela QI Tech (UUID). |
| `external_id` | string | A mesma chave externa fornecida no campo `external_id` do `discounted_credit_right`. |
| `status` | string | Status inicial do ativo. Sempre retorna `pending_eligibility`, indicando que o ativo foi inserido e aguarda análise de elegibilidade. |
## Erros
| Status | Código | Quando acontece |
|---|---|---|
| 400 | `QIT000001` | O request body não segue o formato esperado: campo obrigatório ausente, tipo ou formato inválido. A `description` aponta o campo. |
| 404 | `TRC000018` | Não existe lote com esse `assignment_external_id` nesta configuração de cessão. |
| 400 | `TRC000025` | O `asset_type` é diferente do tipo de ativo da configuração de cessão. |
| 400 | `TRC000022` | O lote não aceita mais ativos: a inserção já foi encerrada. Para incluir mais, [reabra o lote](/documentation/iaas/negociacao_recebiveis/asset/remocao_ativos). |
| 400 | `TRC000009` | CPF ou CNPJ inválido em `originator_document_number` ou no `document_number` de um sacado pessoa física. |
| 404 | `TRC000019` | Não há originador cadastrado com o `originator_document_number` informado. Apesar do título (*Originator bond not found*), o erro não se refere ao vínculo com a configuração. |
| 400 | `TRC000078` | `order_number` ausente. |
| 400 | `TRC000075` | Objeto `invoice` ausente. |
| 400 | `TRC000076` | Objeto `contract` enviado numa duplicata. |
| 400 | `TRC000134` | `invoice.access_key` ausente numa `duplicata_mercantil`. |
| 400 | `TRC000135` | `invoice.access_key` não é de uma NF-e (modelo `55` nas posições 21 e 22). |
| 409 | `TRC000054` | Já existe um ativo com esse `external_id` neste lote. |
| 409 | `TRC100026` | Já existe um direito creditório com esse `external_id` para o mesmo cedente na carteira do fundo. |
| 400 | `TRC1000xx` | A validação financeira do ativo recusou o payload. Exemplo: `TRC100017` (409), o fundo não compra ativos vencidos. |
O corpo de erro segue o formato abaixo:
```json
{
"title": "Already Exist This External Id",
"description": "Already exist an asset with this External Id and asset_key->41d6ff41-1dac-4df7-9e50-d15210ec57f3",
"translation": "Ja existe um ativo com esse External Id e asset_key->41d6ff41-1dac-4df7-9e50-d15210ec57f3",
"code": "TRC000054"
}
```
Em caso de erro, reenvie a requisição. Duplicidade (`TRC000054`) significa que o recurso já existe: consulte-o em vez de recriar, pelo endpoint de [consulta de ativo](/documentation/iaas/negociacao_recebiveis/asset/recuperar_ativos). Mais em [Reenvio e duplicidade](/documentation/iaas/introducao/erros#reenvio-e-duplicidade).
Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros).
## Próximos passos
Após inserir o ativo, o fluxo continua com:
1. **[Envio do lastro](/documentation/iaas/negociacao_recebiveis/asset/documents)** — envie os documentos de lastro exigidos para cada ativo aprovado na elegibilidade.
2. **[Encerramento da inserção](/documentation/iaas/negociacao_recebiveis/assignment/fechamento)** — sinalize que todos os ativos foram inseridos para que o lote siga para a análise de elegibilidade.
---
# Inserção de Ativo para Recompra
URL: /documentation/iaas/negociacao_recebiveis/asset/criacao_repurchased_asset
Endpoint para inserir, num lote de substituição, um ativo da carteira do fundo que será **recomprado** pelo cedente. O valor dos ativos recomprados é abatido do pagamento da cessão dos novos ativos do mesmo lote.
:::info Disponível em
| Perfil | Host | Permissão exigida |
| ----------- | ---------------- | --------------------------------------------------- |
| Gestora | `manager-api` | Escrita |
| Consultoria | `consultant-api` | Lotes |
URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts).
:::
:::info Lotes de substituição
Este endpoint só aceita lotes criados numa configuração de cessão **de recompra** (`assignment_configuration_type` = `repurchase_configuration`). O lote precisa estar em `pending_assets_insertion`. Os ativos de recompra e os novos ativos podem ser inseridos em qualquer ordem enquanto o lote estiver aberto.
Para encerrar a inserção, o lote precisa ter pelo menos um ativo de recompra, e o valor dos novos ativos não pode ser menor que o dos ativos recomprados — veja [Encerrar Inserção de Ativos](/documentation/iaas/negociacao_recebiveis/assignment/fechamento).
:::
:::tip Onde estou no fluxo?
Antes, você deve ter [criado o lote](/documentation/iaas/negociacao_recebiveis/assignment/criacao). Insira também os [novos ativos](/documentation/iaas/negociacao_recebiveis/asset/criacao_co) que substituirão os recomprados.
:::
## Request
ENDPOINT /trade_receivables/fund_class/{fund_class_key}/assignment_configuration/{assignment_configuration_key}/assignment/{assignment_external_id}/repurchased_asset
MÉTODO POST
```json title="Request Body"
{
"asset_type": "duplicata_mercantil",
"external_id": "88c2304e-8eb3-44e0-acb4-25811ae20cf1",
"assignor_document_number": "11.222.333/0001-81",
"repurchase_value": 1000.00,
"settlement_type": "asset_settlement"
}
```
### Atributos do body
| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `asset_type` | string | obrigatório | Tipo do ativo que será recomprado (ex.: `ccb`, `duplicata_mercantil`, `discounted_contract`). |
| `external_id` | string | obrigatório | O `external_id` com que o ativo foi originalmente cedido ao fundo. De 1 a 50 caracteres. |
| `assignor_document_number` | string | obrigatório | CPF ou CNPJ, com pontuação, do cedente que cedeu o ativo ao fundo. |
| `settlement_type` | string | obrigatório | Modalidade da recompra. Veja a tabela abaixo. |
| `repurchase_value` | number | opcional | Valor de recompra, em reais. Mínimo `0.01`. Se omitido, vale o valor justo atual do ativo na carteira do fundo. |
**Valores de `settlement_type`:**
| Valor | Descrição |
|---|---|
| `asset_settlement` | Recompra total do ativo. |
| `asset_amortization` | Recompra parcial (amortização) do ativo. |
## Response
STATUS 201
```json title="Response Body (assignment resumido)"
{
"repurchased_asset_key": "a6115a17-8b4d-49a3-aed6-47c9574eab88",
"asset_type": "duplicata_mercantil",
"asset_key": "65bbce6d-e0b4-4471-a702-e0ced4542e5b",
"external_id": "88c2304e-8eb3-44e0-acb4-25811ae20cf1",
"assignor": {
"assignor_key": "c1d2e3f4-a5b6-4890-abcd-ef1234567890",
"document_number": "11.222.333/0001-81",
"name": "Cedente Exemplo Ltda"
},
"status": "pending_assignment_validation",
"assignment": {
"assignment_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3",
"external_id": "931e9437-d025-41ab-bb53-6b94e10fd361",
"name": "CESSÃO #12345",
"assignment_number": "12345",
"assignment_date": "2024-04-01",
"status": "pending_assets_insertion",
"origin_type": "client"
},
"repurchase_value": 1000.00,
"contract_number": "000123",
"maturity_date": "2024-09-30"
}
```
### Atributos da resposta
| Campo | Tipo | Descrição |
|---|---|---|
| `repurchased_asset_key` | string | Identificador único da recompra gerado pela QI Tech (UUID). |
| `asset_type` | string | Tipo do ativo recomprado. |
| `asset_key` | string | Identificador do ativo na carteira do fundo (UUID). |
| `external_id` | string | O `external_id` do ativo, conforme informado na requisição. |
| `assignor` | object | Cedente que cedeu o ativo: `assignor_key`, `document_number` e `name`. |
| `status` | string | Status da recompra. Veja a tabela abaixo. |
| `assignment` | object | Lote de substituição, com a mesma estrutura da [Recuperação do Lote](/documentation/iaas/negociacao_recebiveis/assignment/recuperacao#atributos-da-resposta), sem `status_events`. |
| `repurchase_value` | number | Valor de recompra, em reais. |
| `contract_number` | string | Número do contrato do ativo recomprado, quando houver. |
| `maturity_date` | string | Vencimento do ativo recomprado, no formato `YYYY-MM-DD`. |
**Status da recompra:**
| Status | Descrição |
|---|---|
| `pending_assignment_validation` | Recompra registrada, aguardando o lote seguir o fluxo. |
| `sending_to_wallet` | Recompra sendo liquidada na carteira do fundo. |
| `completed` | Recompra concluída. |
| `discarded` | Recompra descartada junto com o lote. |
## Erros
| Status | Código | Quando acontece |
|---|---|---|
| 400 | `TRC000088` | A configuração de cessão do lote não é de recompra. |
| 400 | `TRC000089` | O lote não está em `pending_assets_insertion`. |
| 400 | `TRC000090` | O ativo não foi encontrado na carteira do fundo para esse cedente, tipo e `external_id`, ou não pode ser recomprado. |
| 404 | `TRC000005` | Nenhum cedente com esse `assignor_document_number`. |
| 404 | `TRC000012` | `asset_type` inexistente. |
| 404 | `TRC000018` | Nenhum lote com esse `external_id` nesta configuração de cessão. |
Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros).
## Próximos passos
1. **[Inserção dos novos ativos](/documentation/iaas/negociacao_recebiveis/asset/criacao_co)** — adicione os ativos que substituirão os recomprados.
2. **[Envio do lastro](/documentation/iaas/negociacao_recebiveis/asset/documents)** — envie os documentos de lastro exigidos para cada novo ativo.
3. **[Encerramento da inserção](/documentation/iaas/negociacao_recebiveis/assignment/fechamento)** — sinalize que todos os ativos foram inseridos para que o lote siga para a análise de elegibilidade.
---
# Envio do Lastro do Ativo
URL: /documentation/iaas/negociacao_recebiveis/asset/documents
Endpoint para enviar o lastro de um ativo do lote de cessão: os documentos que comprovam o direito creditório, como a CCB, a nota fiscal, o CT-e ou o contrato parcelado. O arquivo vai codificado em Base64, um documento por requisição, e cada ativo recebe o seu.
:::caution Lastro não é Termo de Cessão
O lastro é **por ativo** e quem envia é você, por este endpoint. O Termo de Cessão é **por lote**, gerado pela QI Tech depois da aprovação: você só o consulta, em [Termo de Cessão do Lote](/documentation/iaas/negociacao_recebiveis/assignment/documento_da_cessao). Para baixar o lastro já enviado de todos os ativos de uma cessão, use o relatório [Lastros da Cessão](/documentation/iaas/relatorios_dtvm/assignment_documents).
:::
:::info Disponível em
| Perfil | Host | Permissão exigida |
| ----------- | ---------------- | --------------------------------------------------- |
| Gestora | `manager-api` | Escrita |
| Consultoria | `consultant-api` | Lotes |
| Cedente | `assignor-api` | Escrita |
URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts).
:::
:::tip Onde estou no fluxo?
Você pode enviar os documentos logo depois de inserir o ativo (status `pending_eligibility`) ou depois do [webhook](/documentation/iaas/negociacao_recebiveis/asset/webhooks) `pending_documentation`, que indica que o ativo foi aprovado na elegibilidade e aguarda documentação. Um ativo reprovado por documento (`denied` com `denied_by` = `document`) volta para `pending_documentation` quando recebe um novo documento.
:::
:::info Quais documentos compõem o lastro?
Os tipos exigidos são definidos por produto e vêm na [configuração de cessão](/documentation/iaas/negociacao_recebiveis/listagem), nos campos `required_documents` (antes da cessão) e `after_assignment_required_documents` (depois da cessão). Só esses tipos são aceitos.
- **Duplicata mercantil** (`duplicata_mercantil`): não é preciso enviar documento — a QI Tech gera o documento da duplicata a partir dos dados da nota fiscal. A chamada é aceita e devolve um `document_key`, mas nada é armazenado.
- **Contrato parcelado** (`contract`): veja [Qual documento enviar no contrato parcelado](#qual-documento-enviar-no-contrato-parcelado).
O ativo só avança para `pre_approved` depois que todos os documentos exigidos forem enviados e validados.
:::
:::info Formato do documento
Arquivo em **PDF**, **P7S** ou **XML**, codificado em Base64, com até 10 MB. Outros formatos são recusados com `TRC000166`.
:::
## Request
ENDPOINT /trade_receivables/fund_class/{fund_class_key}/assignment_configuration/{assignment_configuration_key}/assignment/{assignment_external_id}/asset/{asset_external_id}/document
MÉTODO POST
### Path params
| Parâmetro | Tipo | Descrição |
|---|---|---|
| `fund_class_key` | string | Chave única do fundo (UUID). |
| `assignment_configuration_key` | string | Chave da configuração de cessão (UUID). |
| `assignment_external_id` | string | Identificador externo do lote, informado na criação do lote. |
| `asset_external_id` | string | O `external_id` informado na criação do ativo. |
```json title="Request Body"
{
"document_type": "ccb",
"document_b64": "aGVsbG8gd29ybGQgaWYgeW91IGRlY29kZWQgbWUsIGJlIGNhcmVmdWwuIEl0IG11c3QgYmUgYSBQREYgRmlsZSBvdGhlcndpc2UgSSB3aWxsIHJhaXNlIGFuIEVycm9yLg=="
}
```
### Atributos do body
| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `document_type` | string | obrigatório | Tipo do documento que está sendo enviado. Os valores aceitos são os configurados na configuração de cessão utilizada — veja os enumeradores abaixo. |
| `document_b64` | string | obrigatório | Conteúdo do arquivo codificado em Base64 (PDF, P7S ou XML; até 10 MB). |
**Valores de `document_type`** (aceitos só quando constam da configuração de cessão):
| Valor | Descrição |
|---|---|
| `ccb` | Cédula de Crédito Bancário — ativos do tipo CCB. |
| `duplicata_servicos` | Duplicata de serviços. |
| `invoice` | Nota fiscal. |
| `cte` | Conhecimento de Transporte Eletrônico. |
| `discounted_contract` | Contrato descontado. |
| `contract` | O próprio contrato parcelado cedido (o ativo), e não o contrato de cessão. |
| `legal_fees_contract` | Contrato de honorários advocatícios. |
| `check` | Cheque. |
| `promissory_note` | Nota promissória. |
| `disbursement_receipt` | Comprovante de desembolso. |
| `vehicle_reservation_receipt` | Comprovante de reserva do veículo — operações com garantia de veículo. Documento **pós-cessão**. |
### Qual documento enviar no contrato parcelado
No `document_type` `contract`, envie **o contrato que está sendo cedido**: o instrumento firmado entre o originador e o devedor, com as parcelas informadas na [criação do ativo](/documentation/iaas/negociacao_recebiveis/asset/criacao_contract). Ele é o lastro do ativo.
Não envie aqui o contrato de cessão nem o Termo de Cessão. Esses documentos formalizam a transferência dos ativos ao fundo: o contrato é firmado na [homologação do cedente](/documentation/iaas/homologacao_cedente/contrato_de_cessao/pedido_de_contrato) e o termo é gerado pela QI Tech para cada lote — veja [Termo de Cessão do Lote](/documentation/iaas/negociacao_recebiveis/assignment/documento_da_cessao).
Cada ativo recebe **um PDF com o seu próprio contrato**. Em um lote com três contratos (A, B e C), envie três arquivos: o contrato A no ativo A, o B no ativo B e o C no ativo C. Não junte vários contratos no mesmo PDF. Um ativo aceita um único documento de cada tipo; enviar outro `contract` para o mesmo ativo devolve `TRC000035`, a menos que o anterior tenha sido reprovado.
:::info Dois momentos de envio de documento
Este endpoint atende a **dois momentos distintos** do fluxo, e o que muda entre eles é apenas o status do ativo:
- **Antes da cessão.** O ativo entra em `pending_documentation` depois de aprovado na elegibilidade individual e aguarda os documentos configurados como obrigatórios do produto. Com todos enviados, ele avança para `pre_approved`.
- **Depois da cessão.** Se a configuração de cessão exigir documentos pós-cessão, o ativo entra em `pending_after_assignment_documentation` após a liquidação do lote. É aqui que entra o **comprovante de reserva do veículo** (`vehicle_reservation_receipt`) das operações com garantia de veículo. Com todos enviados, o ativo avança para `completed` e é enviado o webhook `completed` do ativo, se você assina esse status. Também é possível acompanhar pela [consulta do ativo](/documentation/iaas/negociacao_recebiveis/asset/recuperar_ativos).
A lista de documentos exigidos em cada momento é definida por produto e vem na resposta da [configuração de cessão](/documentation/iaas/negociacao_recebiveis/listagem), nos campos `required_documents` (antes da cessão) e `after_assignment_required_documents` (depois da cessão). Enviar um `document_type` que não está configurado para aquela cessão, inclusive um valor que não existe, devolve `TRC000032`.
:::
## Response
STATUS 201
```json title="Response Body"
{
"document_key": "8e515a17-8b4d-49a3-aed6-47c9574e426a"
}
```
### Atributos da resposta
| Campo | Tipo | Descrição |
|---|---|---|
| `document_key` | string | Identificador único do documento gerado pela QI Tech (UUID). |
## Erros
| Status | Código | Quando acontece |
|---|---|---|
| 400 | `TRC000032` | `document_type` não consta de `required_documents` nem de `after_assignment_required_documents` da configuração de cessão (inclui valores inexistentes). |
| 400 | `TRC000034` | `document_b64` não é um Base64 válido. |
| 400 | `TRC000155` | Arquivo acima de 10 MB. |
| 400 | `TRC000166` | Formato não aceito. Formatos aceitos: PDF, P7S e XML. |
| 404 | `TRC000020` | Nenhum ativo com esse `asset_external_id` no lote. |
| 409 | `TRC000026` | O ativo não está num status que receba documentos (`pending_eligibility`, `pending_documentation`, `denied` por documento ou `pending_after_assignment_documentation`). |
| 409 | `TRC000035` | O ativo já tem um documento desse tipo que não foi reprovado. |
| 409 | `TRC000162` | O lote está `denied` ou `discarded`. |
Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros).
## Próximos passos
Após enviar todos os documentos exigidos, o fluxo continua com:
1. **[Encerramento da inserção](/documentation/iaas/negociacao_recebiveis/assignment/fechamento)** — sinalize que todos os ativos foram inseridos para que o lote siga para a análise de elegibilidade.
---
# Qual ativo enviar
URL: /documentation/iaas/negociacao_recebiveis/asset/qual_ativo_enviar
O tipo do ativo é definido pelo **documento que comprova o recebível**: uma cédula, uma nota fiscal, um CT-e ou um contrato. Encontre o seu na tabela e siga para a página de criação.
## Encontre o seu tipo
| O que você tem | `asset_type` | Página de criação |
|---|---|---|
| Cédula de Crédito Bancário | `ccb` | [CCB](/documentation/iaas/negociacao_recebiveis/asset/criacao_co) |
| Cédula de Crédito Imobiliário estruturada | `structured_cci` | [CCB](/documentation/iaas/negociacao_recebiveis/asset/criacao_co), com o mesmo corpo |
| Nota fiscal de venda de mercadoria (NF-e) | `duplicata_mercantil` | [Duplicatas](/documentation/iaas/negociacao_recebiveis/asset/criacao_duplicata) |
| Nota fiscal de prestação de serviço | `duplicata_servicos` | [Duplicatas](/documentation/iaas/negociacao_recebiveis/asset/criacao_duplicata) |
| Conhecimento de Transporte Eletrônico | `cte` | [CT-e](/documentation/iaas/negociacao_recebiveis/asset/criacao_cte) |
| Contrato com parcelas, cedido **parcela a parcela** | `discounted_contract` | [Contrato descontado](/documentation/iaas/negociacao_recebiveis/asset/criacao_discounted_contract) |
| Contrato com parcelas, cedido **inteiro** | `contract` | [Contrato parcelado](/documentation/iaas/negociacao_recebiveis/asset/criacao_contract) |
Para **trocar** ativos que já estão no fundo por outros, não existe um tipo próprio: você usa um lote de substituição, com os ativos novos e os recomprados. Veja [Criação do Ativo — Substituição](/documentation/iaas/negociacao_recebiveis/asset/criacao_repurchased_asset).
:::info O tipo vem da configuração de cessão
Cada configuração de cessão tem um único `asset_type`, e os lotes dela só aceitam ativos desse tipo; um ativo de outro tipo é recusado com `TRC000025`. Consulte o tipo da sua na [listagem de configurações](/documentation/iaas/negociacao_recebiveis/listagem). Se a sua operação cede mais de um tipo, você precisa de uma configuração para cada. Para criar ou alterar uma configuração, fale com o time de integração.
:::
## Título ou operação parcelada
Os tipos se dividem em dois grupos, e o grupo decide o que conta como **um ativo**. Elegibilidade, pagamento e recompra acontecem sempre por ativo.
- **Um vencimento por ativo:** duplicatas, CT-e e contrato descontado. Cada ativo tem um valor e um vencimento. Uma nota com três vencimentos vira três ativos, cada um com o seu `external_id` e `installment_number`.
- **Várias parcelas num ativo:** CCB, CCI estruturada e contrato parcelado. O ativo leva a lista de parcelas, e todas precisam ser informadas no envio.
## O que muda depois da cessão
| | Duplicatas e CT-e | Contrato descontado | CCB e CCI estruturada | Contrato parcelado |
|---|---|---|---|---|
| O ativo é | o título | a parcela | a operação | o contrato |
| Recusa na elegibilidade | tira o título | tira a parcela | tira a operação | tira o contrato |
| Pagamentos informados | do título | da parcela | da operação ou de uma parcela | do contrato ou de uma parcela |
| Prorrogar o vencimento | sim | sim | não | não |
| Recompra | do título | da parcela | da operação ou de uma parcela | do contrato, total ou parcial; nunca de uma parcela |
| Boleto na cessão | um por título | um por parcela | consulte o time de integração | um por parcela |
Detalhes de cada linha em [liquidação de ativos](/documentation/iaas/liquidacao_ativos/ativos/ativos), [substituição](/documentation/iaas/negociacao_recebiveis/asset/criacao_repurchased_asset) e [do ativo ao boleto](/documentation/iaas/boletos/campos_do_boleto).
O [lastro](/documentation/iaas/negociacao_recebiveis/asset/documents) não depende do tipo: os documentos exigidos vêm da sua configuração de cessão. A exceção é a duplicata mercantil, cujo documento é gerado pela QI Tech a partir da nota fiscal.
:::tip Contrato descontado ou contrato parcelado?
Os dois cedem contratos com parcelas. A diferença está em ceder uma parcela por vez ou o contrato inteiro, e isso muda o preço, a recompra, a prorrogação e o relatório de estoque. A comparação completa está em [Contrato descontado ou contrato parcelado](/documentation/iaas/negociacao_recebiveis/asset/criacao_discounted_contract).
:::
---
# Consulta de Ativos do Lote
URL: /documentation/iaas/negociacao_recebiveis/asset/recuperar_ativos
Endpoints para consultar os ativos inseridos em um lote de cessão. Existem dois modos de consulta: a **listagem paginada** de todos os ativos de um lote, e a **consulta individual** de um ativo específico.
:::tip Quando utilizar
Utilize estes endpoints para acompanhar o status dos ativos após a inserção, verificar quais foram aprovados ou reprovados na elegibilidade, e consultar os motivos de reprovação quando houver.
A listagem aceita **filtros** — inclusive por status — o que permite consultar diretamente apenas os ativos reprovados, sem precisar paginar o lote inteiro. Veja [Consultar apenas os ativos reprovados](#consultar-apenas-os-ativos-reprovados).
:::
## Listagem de ativos
Retorna a lista paginada dos ativos de um lote, com suporte a filtros. A resposta traz só os ativos que o seu perfil pode ver.
:::info Disponível em
| Perfil | Host | Permissão exigida |
| ----------- | ---------------- | --------------------------------------------------- |
| Gestora | `manager-api` | Leitura |
| Consultoria | `consultant-api` | Ler Cessões |
URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts).
:::
### Request
ENDPOINT /trade_receivables/fund_class/{fund_class_key}/assignment/{assignment_external_id}/assets
MÉTODO GET
### Query params
Todos os filtros são opcionais e podem ser combinados entre si. Quando nenhum filtro é informado, a rota devolve todos os ativos do lote.
| Parâmetro | Tipo | Padrão | Descrição |
|---|---|---|---|
| `page` | integer | `0` | Número da página (começa em 0). |
| `limit` | integer | `10` | Quantidade de registros por página. Máximo: `100`. |
| `status` | string | — | Filtra por um status de ativo. Aceita **um único valor**, que deve ser um dos [enumeradores de status](#enumeradores-de-status-do-ativo). Use `denied` para obter apenas os ativos reprovados. |
| `external_id` | string | — | Filtra pelo `external_id` do ativo informado na criação. |
| `contract_number` | string | — | Filtra pelo número do contrato da operação. |
| `invoice_access_key` | string | — | Filtra pela chave de acesso da nota fiscal (duplicatas e CT-e). |
| `invoice_number` | string | — | Filtra pelo número da nota fiscal. |
| `invoice_serie` | string | — | Filtra pela série da nota fiscal. |
| `borrower_document_number` | string | — | Filtra pelo CPF/CNPJ do devedor (sacado ou tomador, conforme o tipo de ativo). |
| `purchase_value_min` | number | — | Valor mínimo de compra do ativo (inclusive). |
| `purchase_value_max` | number | — | Valor máximo de compra do ativo (inclusive). |
| `maturity_date_start` | string (`AAAA-MM-DD`) | — | Data de vencimento inicial do intervalo. |
| `maturity_date_end` | string (`AAAA-MM-DD`) | — | Data de vencimento final do intervalo. |
```text title="Exemplo — listagem simples"
GET /trade_receivables/fund_class/{fund_class_key}/assignment/{assignment_external_id}/assets?page=0&limit=10
```
```text title="Exemplo — filtros combinados"
GET /trade_receivables/fund_class/{fund_class_key}/assignment/{assignment_external_id}/assets?status=denied&limit=100&maturity_date_start=2024-01-01&maturity_date_end=2024-12-31
```
:::caution Status inválido
Se o valor enviado em `status` não corresponder a nenhum enumerador válido, a requisição retorna `TRC000163` (400). Consulte a [tabela de enumeradores](#enumeradores-de-status-do-ativo) antes de montar o filtro.
:::
### Response
STATUS 200
```json title="Response Body"
{
"data": [
{
"asset_key": "f4348106-01c4-4c59-a261-7c09db811c47",
"external_id": "e292656f-f7fb-44dc-96f3-667c36c88442",
"total_purchase_value": 1231.21,
"asset_type": "duplicata_mercantil",
"status": "denied",
"duration": 9177,
"denied_by": "document",
"denial_reason": "Invalid documents"
}
],
"limit": 10,
"page": 0,
"is_last_page": true
}
```
### Atributos da resposta
| Campo | Tipo | Descrição |
|---|---|---|
| `data` | array | Lista de objetos de ativo. Veja tabela abaixo. |
| `page` | integer | Número da página atual. |
| `limit` | integer | Quantidade de registros por página. |
| `is_last_page` | boolean | Indica se esta é a última página de resultados. |
#### Atributos de cada ativo (objetos dentro de `data`)
| Campo | Tipo | Descrição |
|---|---|---|
| `asset_key` | string | Identificador único do ativo (UUID). |
| `external_id` | string | Chave externa fornecida pelo parceiro na criação. |
| `total_purchase_value` | number | Valor total de compra do ativo. |
| `asset_type` | string | Tipo do ativo (ex: `ccb`, `duplicata_mercantil`, `discounted_contract`). |
| `ipoc_code` | string | Código IPOC do ativo, quando houver. |
| `purchase_irr` | number | Taxa de compra do ativo, quando calculada. |
| `contract_number` | string | Número do contrato, quando houver. |
| `premiums` | array | Ágios do ativo (`premium_type`, `total_value`). Ausente quando não há. |
| `deductions` | array | Deságios do ativo (`deduction_type`, `total_value`). Ausente quando não há. |
| `status` | string | Status atual do ativo. Consulte a [tabela de status](#enumeradores-de-status-do-ativo) abaixo. |
| `duration` | integer | Duração do ativo em dias. Pode não estar presente se ainda não foi calculada. |
| `denied_by` | string | Origem da reprovação. Presente apenas quando o ativo foi reprovado. Consulte a [tabela de origens](#origens-de-reprovacao-denied_by). |
| `denial_reason` | string | Descrição do motivo da reprovação. Presente apenas quando há detalhe da reprovação. |
| `denial_translation` | string | Tradução do motivo, quando houver. |
| `denial_description` | string | Descrição complementar do motivo, quando houver. |
:::info Objetos aninhados
Dependendo do tipo de ativo, a resposta inclui o objeto `credit_operation` (CCB), `discounted_credit_right` (duplicatas, CT-e, contratos descontados) ou `contract` (contratos parcelados), com os dados enviados na criação e o objeto `originator`.
:::
## Consultar apenas os ativos reprovados
Este é o uso mais comum da listagem: descobrir **quais contratos do lote foram reprovados**, para refletir a decisão da QI Tech no controle interno do parceiro e decidir se algum ativo precisa ser [removido do lote](/documentation/iaas/negociacao_recebiveis/asset/remocao_ativos).
Basta informar `status=denied`:
```text title="Request"
GET /trade_receivables/fund_class/{fund_class_key}/assignment/{assignment_external_id}/assets?status=denied&limit=100
```
A resposta traz somente os ativos reprovados, cada um com `denied_by` (a origem da reprovação) e `denial_reason` (a descrição):
```json title="Response Body"
{
"data": [
{
"asset_key": "f4348106-01c4-4c59-a261-7c09db811c47",
"external_id": "e292656f-f7fb-44dc-96f3-667c36c88442",
"total_purchase_value": 1231.21,
"asset_type": "ccb",
"status": "denied",
"duration": 9177,
"denied_by": "eligibility",
"denial_reason": "Prazo do contrato acima do permitido pela política do fundo"
}
],
"limit": 100,
"page": 0,
"is_last_page": true
}
```
:::tip Recomendações de uso
- Use `limit=100` (o máximo permitido) para reduzir o número de páginas e pagine até `is_last_page` ser `true`.
- Consulte após receber o webhook [`pending_manager_approval`](/documentation/iaas/negociacao_recebiveis/assignment/webhooks#eventos-por-status) — nesse momento a análise de elegibilidade de todos os ativos já foi concluída e a lista de reprovados está estável.
- Para o inverso — os ativos aprovados na elegibilidade — use `status=pre_approved`.
:::
### Origens de reprovação (`denied_by`)
| Valor | Significado |
|---|---|
| `eligibility` | Reprovado na análise de elegibilidade. |
| `document` | Reprovado na validação dos documentos enviados. |
| `inconsistency` | Reprovado por inconsistência nos dados da operação identificada na validação. |
| `invalid_invoice` | Reprovado na validação da nota fiscal. |
| `registry` | Reprovado no processo de registro do ativo. |
| `term` | Reprovado na etapa do Termo de Cessão. |
| `manager` | Reprovado/removido por ação do gestor do fundo. |
| `consultant` | Reprovado/removido por ação do consultor. |
| `assignor` | Reprovado/removido por ação do cedente. |
| `accounting_close` | Reprovado por fechamento contábil do fundo. |
| `denial_file` | Reprovado por arquivo de reprovação processado em lote. |
## Consulta de ativo específico
Retorna os dados completos de um ativo específico do lote, com o histórico de status e os documentos enviados.
:::info Disponível em
| Perfil | Host | Permissão exigida |
| ----------- | ---------------- | --------------------------------------------------- |
| Gestora | `manager-api` | Leitura |
| Consultoria | `consultant-api` | Ler Cessões |
| Cedente | `assignor-api` | Leitura |
URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts).
:::
### Request
ENDPOINT /trade_receivables/fund_class/{fund_class_key}/assignment_configuration/{assignment_configuration_key}/assignment/{assignment_external_id}/asset/{asset_external_id}
MÉTODO GET
### Path params
| Parâmetro | Tipo | Descrição |
|---|---|---|
| `asset_external_id` | string | O `external_id` informado na criação do ativo. |
### Response
STATUS 200
```json title="Response Body"
{
"asset_key": "074f8786-447f-4524-9f4f-a5cf8a890bb4",
"external_id": "acfbc329-4e67-40ea-bd8d-5debdaebe144",
"total_purchase_value": 1231.21,
"asset_type": "duplicata_mercantil",
"status": "denied",
"duration": 9184,
"denied_by": "document",
"denial_reason": "Invalid documents"
}
```
### Atributos da resposta
A resposta possui a mesma estrutura de cada objeto do array `data` retornado pela [listagem de ativos](#atributos-de-cada-ativo-objetos-dentro-de-data), acrescida de:
| Campo | Tipo | Descrição |
|---|---|---|
| `status_events` | array | Histórico de status do ativo: `status`, `event_datetime` (UTC) e, em reprovações, `denial_reason` e `denial_metadata`. |
| `documents` | array | Documentos enviados para o ativo. |
## Enumeradores de status do ativo
Qualquer um dos valores abaixo pode ser usado no filtro `status` da listagem.
| Status | Descrição |
|---|---|
| `created` | Ativo criado, ainda não submetido à análise. |
| `pending_eligibility` | Ativo inserido, aguardando análise de elegibilidade. |
| `pending_documentation` | Ativo aprovado na elegibilidade, aguardando envio de documentos. |
| `pending_invoice_validation` | Aguardando validação da nota fiscal. |
| `pre_approved` | Ativo pré-aprovado na elegibilidade individual. |
| `pending_registry` | Aguardando início do registro do ativo. |
| `pending_external_registry` | Aguardando registro em câmara externa. |
| `sending_to_registry` | Em envio para a câmara de registro. |
| `waiting_registry` | Registro submetido, aguardando retorno da câmara. |
| `pending_formalization` | Ativo formalizado e apto a seguir no lote. |
| `registry_denied` | Registro do ativo recusado pela câmara. |
| `sending_to_wallet` | Em processo de encarteiramento na carteira do fundo. |
| `denied` | Ativo reprovado. Consulte `denied_by` para a origem da reprovação. |
| `discarded` | Ativo descartado do lote. |
| `pending_after_assignment_documentation` | Ativo encarteirado, aguardando documentos pós-cessão. |
| `pending_deferred_registry` | Aguardando o registro pós-cessão (registro diferido). |
| `completed` | Ativo encarteirado na carteira do fundo. |
## Erros
| Status | Código | Quando acontece |
|---|---|---|
| 400 | `TRC000163` | Listagem: valor de `status` que não é um status de ativo. |
| 400 | — | Listagem: `limit` acima de 100 ou `page` negativo (validação de parâmetro). |
| 404 | `TRC000020` | Consulta individual: nenhum ativo com esse `asset_external_id` no lote. |
Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros).
---
# Remoção de Ativos do Lote
URL: /documentation/iaas/negociacao_recebiveis/asset/remocao_ativos
Para retirar um ativo de um lote antes da aprovação, atualize o status do ativo para `denied`. O ativo deixa de compor o lote e seu valor sai do total da cessão. Se for preciso também **incluir** ativos, reabra o lote, ajuste os ativos e encerre a inserção de novo.
:::info Quando cada perfil pode remover ativos
O ativo precisa estar em `pending_eligibility`, `pending_invoice_validation`, `pending_documentation` ou `pre_approved`. O lote precisa estar num destes status:
| Perfil | Status do lote em que pode remover ativos |
|---|---|
| Gestora | `pending_assets_insertion`, `completed_assets_insertion`, `pending_consultant_approval`, `pending_manager_approval` |
| Consultoria | `pending_assets_insertion`, `completed_assets_insertion`, `pending_consultant_approval` |
| Cedente | `pending_assets_insertion`, `completed_assets_insertion` |
A gestora remove ativos de um lote em `pending_manager_approval` sem reabri-lo e depois [aprova](/documentation/iaas/negociacao_recebiveis/assignment/aprovacao) o lote.
:::
## Remover um ativo
Faça uma requisição para cada ativo a ser removido.
:::info Disponível em
| Perfil | Host | Permissão exigida |
| ----------- | ---------------- | --------------------------------------------------- |
| Gestora | `manager-api` | Escrita |
| Consultoria | `consultant-api` | Lotes |
| Cedente | `assignor-api` | Escrita |
URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts).
:::
### Request
ENDPOINT /trade_receivables/fund_class/{fund_class_key}/assignment_configuration/{assignment_configuration_key}/assignment/{assignment_external_id}/asset/{asset_external_id}
MÉTODO PUT
#### Path params
| Parâmetro | Tipo | Descrição |
|---|---|---|
| `assignment_external_id` | string | O `external_id` do lote. |
| `asset_external_id` | string | O `external_id` do ativo que será removido. |
```json title="Request Body"
{
"asset_status": "denied",
"denial_reason": {
"reason_type": "manager",
"denial_reason": "Sacado fora da política do fundo"
}
}
```
#### Atributos do body
| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `asset_status` | string | obrigatório | Único valor aceito: `denied`. |
| `denial_reason` | object | opcional | Motivo da remoção: `reason_type` (obrigatório dentro do objeto; use `manager`, `consultant` ou `assignor`) e `denial_reason` (texto livre). Sem esse objeto, a origem registrada é o seu perfil. |
### Response
STATUS 200
A resposta é o ativo atualizado, no mesmo formato de cada item da [Consulta de Ativos do Lote](/documentation/iaas/negociacao_recebiveis/asset/recuperar_ativos#atributos-de-cada-ativo-objetos-dentro-de-data), com o objeto da operação (`credit_operation`, `discounted_credit_right` ou `contract`). Trecho:
```json title="Response Body (trecho)"
{
"asset_key": "f4348106-01c4-4c59-a261-7c09db811c47",
"external_id": "9eec85be-97c9-41e0-88b3-b17a39869b36",
"total_purchase_value": 1231.21,
"asset_type": "ccb",
"status": "denied",
"denied_by": "manager",
"denial_reason": "Sacado fora da política do fundo"
}
```
## Reabrir e encerrar o lote
Para incluir novos ativos num lote que já teve a inserção encerrada, reabra-o com `pending_assets_insertion`, insira ou remova os ativos e encerre de novo com `completed_assets_insertion`. Depois de encerrado, o lote passa outra vez pela elegibilidade e pelas aprovações.
:::info Disponível em
| Perfil | Host | Permissão exigida |
| ----------- | ---------------- | --------------------------------------------------- |
| Gestora | `manager-api` | Escrita |
| Consultoria | `consultant-api` | Lotes |
| Cedente | `assignor-api` | Escrita |
URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts).
:::
O lote pode ser reaberto quando está em `completed_assets_insertion`, `pending_consultant_approval` ou `pending_manager_approval`. A consultoria não reabre lotes em `pending_manager_approval`.
### Request
ENDPOINT /trade_receivables/fund_class/{fund_class_key}/assignment_configuration/{assignment_configuration_key}/assignment/{assignment_external_id}
MÉTODO PUT
```json title="Request Body — reabrir"
{
"assignment_status": "pending_assets_insertion"
}
```
| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `assignment_status` | string | obrigatório | `pending_assets_insertion` para reabrir. Para encerrar de novo, envie `completed_assets_insertion` — veja [Encerrar Inserção de Ativos](/documentation/iaas/negociacao_recebiveis/assignment/fechamento). |
### Response
STATUS 200
```json title="Response Body"
{
"assignment_key": "8e515a17-8b4d-49a3-aed6-47c9574e426a",
"external_id": "9eec85be-97c9-41e0-88b3-b17a39869b36",
"status": "pending_assets_insertion",
"number_of_approved_assets": 0,
"assignment_total_value": 1234.99
}
```
| Campo | Tipo | Descrição |
|---|---|---|
| `assignment_key` | string | Identificador único do lote (UUID). |
| `external_id` | string | Chave externa do lote fornecida pelo parceiro. |
| `status` | string | Novo status do lote: `pending_assets_insertion`. |
| `number_of_approved_assets` | integer | Sempre `0` nesta chamada. |
| `assignment_total_value` | number | Último valor total calculado para o lote, em reais. É recalculado no próximo encerramento. |
## Erros
| Status | Código | Quando acontece |
|---|---|---|
| 400 | `TRC000086` | O ativo não está em `pending_eligibility`, `pending_invoice_validation`, `pending_documentation` ou `pre_approved` (por exemplo, já reprovado ou formalizado). |
| 400 | `TRC000023` | `asset_status` diferente de `denied`, ou `assignment_status` com valor não aceito. |
| 400 | `TRC000087` | O status do lote não permite que o seu perfil remova ativos ou reabra o lote (veja as tabelas acima). |
| 400 | `TRC000024` | Reabertura pedida para um lote que não está em `completed_assets_insertion`, `pending_consultant_approval` ou `pending_manager_approval`. |
| 404 | `TRC000018` | Nenhum lote com esse `external_id` nesta configuração de cessão. |
| 404 | `TRC000020` | Nenhum ativo com esse `asset_external_id` no lote. |
Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros).
---
# Webhooks do Ativo
URL: /documentation/iaas/negociacao_recebiveis/asset/webhooks
Ao longo do fluxo de cessão, o sistema envia webhooks para notificar o parceiro integrador sobre mudanças de status dos ativos individuais. Existem dois tipos de webhook: `trade_receivables.asset_status_change` para mudanças de status e `trade_receivables.asset_creation` para confirmação de criação do ativo.
:::info Configuração de webhooks
Para receber webhooks, é necessário ter uma URL de callback configurada junto à QI Tech. A configuração define **quais status** você recebe: só são enviados os eventos assinados nela. O webhook de criação (`asset_creation`) é enviado a quem assina o status `pending_eligibility`. Entre em contato com [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br) para configurar. Entrega, tentativas e assinatura: veja [Recebimento de Webhooks](/documentation/iaas/introducao/autenticacao_webhooks).
:::
## Fluxo de status do ativo
O ativo entra em `pending_eligibility` assim que é inserido no lote e, a partir da análise de elegibilidade, segue por um dos caminhos abaixo. O diagrama mostra o caminho principal; a lista completa de status está em [Enumeradores de status do ativo](/documentation/iaas/negociacao_recebiveis/asset/recuperar_ativos#enumeradores-de-status-do-ativo).
_Como ler o diagrama: **azul** = status intermediário · **verde** = ativo cedido e encarteirado · **vermelho** = status final de recusa ou descarte._
## Estrutura do webhook
Todos os webhooks de ativo seguem a mesma estrutura base:
| Campo | Tipo | Descrição |
|---|---|---|
| `webhook_type` | string | Tipo do webhook: `trade_receivables.asset_status_change` ou `trade_receivables.asset_creation`. |
| `webhook_datetime` | string | Data e hora do envio, no formato `YYYY-MM-DDTHH:MM:SSZ`. |
| `data` | object | Dados do evento. Veja tabela abaixo. |
### Atributos de `data`
| Campo | Tipo | Descrição |
|---|---|---|
| `assignment_external_id` | string | O `external_id` do lote ao qual o ativo pertence. |
| `asset_external_id` | string | O `external_id` do ativo. |
| `asset_new_status` | string | Novo status do ativo. |
| `assignment_configuration_key` | string | Identificador da configuração de cessão à qual o lote pertence — a mesma chave usada nas URLs dos endpoints. |
| `fund_class_key` | string | Identificador da classe do fundo associada ao lote. |
| `operation_type` | string | Tipo de operação da configuração de cessão (ex.: `unsecured_credit`, `duplicata_mercantil`). |
| `asset_payload` | object | Presente apenas no webhook de criação (`asset_creation`). Contém os dados do ativo conforme enviados na criação, com `purchase_irr` calculado dentro de `credit_operation` (CCB) ou `contract` (contratos). |
| `denial_reason` | string | Presente em `denied` e `registry_denied`: origem da reprovação (os valores de [`denied_by`](/documentation/iaas/negociacao_recebiveis/asset/recuperar_ativos#origens-de-reprovacao-denied_by)). |
| `denial_metadata` | object | Presente em `denied` e `registry_denied` quando há detalhe — por exemplo, as regras de elegibilidade reprovadas ou o motivo informado na [remoção do ativo](/documentation/iaas/negociacao_recebiveis/asset/remocao_ativos). |
:::info O que é a `assignment_configuration_key`
A **configuração de cessão** é o acordo já cadastrado entre o cedente e o fundo: ela define para qual fundo os recebíveis são cedidos, qual tipo de ativo é aceito e sob quais regras a operação acontece. É a mesma chave que você já usa nas URLs dos endpoints de cessão, obtida na [Homologação de Cedente](/documentation/iaas/homologacao_cedente/contrato_de_cessao/pedido_de_contrato).
Como um mesmo cedente pode ter mais de uma configuração ativa ao mesmo tempo, esse campo informa **sob qual acordo** o ativo está sendo cedido. Assim você direciona o webhook para o fluxo certo sem precisar consultar a API para descobrir a origem do ativo.
:::
```json title="Estrutura padrão do webhook"
{
"data": {
"assignment_external_id": "ac597f90-a13e-4f78-86f0-11c66f5fa6d6",
"asset_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
"asset_new_status": "STATUS",
"assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef",
"fund_class_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c",
"operation_type": "unsecured_credit"
},
"webhook_type": "trade_receivables.asset_status_change",
"webhook_datetime": "2024-04-23T15:08:30Z"
}
```
---
## Eventos por status
### Ativo Criado
STATUS pending_eligibility
Enviado quando um ativo é inserido no lote com sucesso. Este webhook inclui o campo `asset_payload` com todos os dados da operação de crédito enviados na criação. O tipo do webhook é `trade_receivables.asset_creation`.
```json title="Webhook Body"
{
"data": {
"assignment_external_id": "ac597f90-a13e-4f78-86f0-11c66f5fa6d6",
"asset_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
"asset_new_status": "pending_eligibility",
"assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef",
"fund_class_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c",
"operation_type": "unsecured_credit",
"asset_payload": {
"premiums": [
{
"total_value": 1.2,
"premium_type": "spread"
}
],
"asset_type": "ccb",
"credit_operation": {
"delay": {
"fine": {
"amount": 0.0,
"fine_type": "percentage"
},
"interest": {
"method": "compound",
"pre_fixed": {
"monthly_rate": 0.0,
"calendar_base": "workdays"
}
}
},
"borrower": {
"name": "João Pereira",
"email": "exemplo3@gmail.com",
"phone": {
"number": "948386674",
"area_code": "11"
},
"address": {
"uf": "SP",
"city": "São Paulo",
"number": "84",
"street": "RUA GILBERTO SABINO",
"country": "BRA",
"postal_code": "05425-020",
"neighborhood": "Pinheiros"
},
"person_type": "natural_person",
"natural_person": {
"birthdate": "1970-02-18",
"mother_name": "Natalia Nascimento"
},
"document_number": "969.698.790-03"
},
"contract": {
"cet": 0.0314,
"number": "0032226586/NNT",
"iof_value": 3.04,
"issue_date": "2024-04-24",
"issue_value": 93.05,
"signature_date": "2024-04-24",
"disbursement_date": "2024-04-24",
"disbursement_value": 62.1
},
"pre_fixed": {
"monthly_rate": 0.0179,
"calendar_base": "calendar_365"
},
"external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
"installments": [
{
"face_value": 30.81,
"maturity_date": "2025-02-01",
"installment_number": 1
},
{
"face_value": 26.19,
"maturity_date": "2026-02-01",
"installment_number": 2
},
{
"face_value": 29.68,
"maturity_date": "2027-02-01",
"installment_number": 3
},
{
"face_value": 23.74,
"maturity_date": "2028-02-01",
"installment_number": 4
},
{
"face_value": 28.49,
"maturity_date": "2029-02-01",
"installment_number": 5
},
{
"face_value": 19.94,
"maturity_date": "2030-02-01",
"installment_number": 6
},
{
"face_value": 13.96,
"maturity_date": "2031-02-01",
"installment_number": 7
},
{
"face_value": 13.03,
"maturity_date": "2032-02-01",
"installment_number": 8
}
],
"principal_value": 93.05,
"amortization_type": "price",
"interest_rate_type": "pre_fixed",
"originator_document_number": "22.333.444/0001-81"
},
"total_purchase_value": 94.86
}
},
"webhook_type": "trade_receivables.asset_creation",
"webhook_datetime": "2024-04-23T15:08:30Z"
}
```
---
### Aprovado na Elegibilidade — Pendente Documentação
STATUS pending_documentation
Enviado quando o ativo é **aprovado** na análise de elegibilidade e a configuração de cessão exige documentos (duplicata mercantil e CT-e sempre passam por este status). Envie o lastro exigido pelo [Envio do Lastro do Ativo](/documentation/iaas/negociacao_recebiveis/asset/documents), se ainda não tiver enviado.
```json title="Webhook Body"
{
"data": {
"assignment_external_id": "ac597f90-a13e-4f78-86f0-11c66f5fa6d6",
"asset_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
"asset_new_status": "pending_documentation",
"assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef",
"fund_class_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c",
"operation_type": "unsecured_credit"
},
"webhook_type": "trade_receivables.asset_status_change",
"webhook_datetime": "2024-04-23T15:08:30Z"
}
```
---
### Pré-Aprovado
STATUS pre_approved
Enviado quando o ativo é **pré-aprovado**, após validação bem-sucedida dos documentos (ou quando nenhuma documentação adicional é exigida). O ativo está apto para avançar para a etapa de formalização/registro.
```json title="Webhook Body"
{
"data": {
"assignment_external_id": "ac597f90-a13e-4f78-86f0-11c66f5fa6d6",
"asset_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
"asset_new_status": "pre_approved",
"assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef",
"fund_class_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c",
"operation_type": "unsecured_credit"
},
"webhook_type": "trade_receivables.asset_status_change",
"webhook_datetime": "2024-04-23T15:08:30Z"
}
```
---
### Pendente Registro
STATUS pending_registry
Enviado quando o ativo pré-aprovado é encaminhado para a **registradora**. Só ocorre em configurações de cessão cujo `registry_type` exige registro — `internal_registry`, `external_registry`, `registry_transfer` ou `unfit`. O ativo permanece nesse status até a registradora responder.
```json title="Webhook Body"
{
"data": {
"assignment_external_id": "ac597f90-a13e-4f78-86f0-11c66f5fa6d6",
"asset_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
"asset_new_status": "pending_registry",
"assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef",
"fund_class_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c",
"operation_type": "unsecured_credit"
},
"webhook_type": "trade_receivables.asset_status_change",
"webhook_datetime": "2024-04-23T15:08:30Z"
}
```
---
### Pendente Formalização
STATUS pending_formalization
Status em que o ativo foi formalizado (registrado, quando a configuração exige registro) e está apto a seguir no lote até o encarteiramento. Hoje esta passagem **não gera webhook**, mesmo que o status esteja assinado. Acompanhe pela [consulta do ativo](/documentation/iaas/negociacao_recebiveis/asset/recuperar_ativos) ou pelo webhook do lote `waiting_assets_to_formalize`, nos [webhooks do lote](/documentation/iaas/negociacao_recebiveis/assignment/webhooks#eventos-por-status).
---
### Ativo Concluído
STATUS completed
Enviado quando o ativo foi **encarteirado com sucesso** na carteira do fundo. Este é o status final de um ativo bem-sucedido — a partir desse momento, o ativo encontra-se dentro do estoque do fundo.
```json title="Webhook Body"
{
"data": {
"assignment_external_id": "ac597f90-a13e-4f78-86f0-11c66f5fa6d6",
"asset_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
"asset_new_status": "completed",
"assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef",
"fund_class_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c",
"operation_type": "unsecured_credit"
},
"webhook_type": "trade_receivables.asset_status_change",
"webhook_datetime": "2024-04-23T15:08:30Z"
}
```
---
### Reprovado na Elegibilidade
STATUS denied
Enviado quando o ativo é **reprovado** — na elegibilidade, na validação de documentos ou da nota fiscal — ou [removido do lote](/documentation/iaas/negociacao_recebiveis/asset/remocao_ativos). O webhook traz `denial_reason` e, quando houver, `denial_metadata`. Um ativo reprovado por documento volta para `pending_documentation` se você enviar um novo documento.
```json title="Webhook Body"
{
"data": {
"assignment_external_id": "ac597f90-a13e-4f78-86f0-11c66f5fa6d6",
"asset_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
"asset_new_status": "denied",
"assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef",
"fund_class_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c",
"operation_type": "unsecured_credit"
},
"webhook_type": "trade_receivables.asset_status_change",
"webhook_datetime": "2024-04-23T15:08:30Z"
}
```
---
### Registro Recusado
STATUS registry_denied
Enviado quando a **registradora recusa** o registro do ativo. O ativo não segue para a formalização nem para o encarteiramento; quando o lote é aprovado, ele passa a `denied`. O webhook traz `denial_reason` e, quando houver, `denial_metadata`; o detalhe também aparece na [consulta do ativo](/documentation/iaas/negociacao_recebiveis/asset/recuperar_ativos).
```json title="Webhook Body"
{
"data": {
"assignment_external_id": "ac597f90-a13e-4f78-86f0-11c66f5fa6d6",
"asset_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
"asset_new_status": "registry_denied",
"assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef",
"fund_class_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c",
"operation_type": "unsecured_credit"
},
"webhook_type": "trade_receivables.asset_status_change",
"webhook_datetime": "2024-04-23T15:08:30Z"
}
```
---
### Ativo Descartado
STATUS discarded
Status do ativo descartado junto com o lote — por exemplo, no fechamento contábil do fundo. Depois da assinatura do Termo de Cessão, os ativos reprovados (`denied`) do lote também passam para `discarded`. Hoje esta passagem **não gera webhook do ativo**, mesmo que o status esteja assinado. Acompanhe pela [consulta do ativo](/documentation/iaas/negociacao_recebiveis/asset/recuperar_ativos); o descarte do lote é avisado pelo webhook `discarded` dos [webhooks do lote](/documentation/iaas/negociacao_recebiveis/assignment/webhooks#eventos-por-status). Para retirar um ativo do lote, use a [remoção de ativos](/documentation/iaas/negociacao_recebiveis/asset/remocao_ativos), que leva o ativo a `denied`.
---
# Aprovação do Lote
URL: /documentation/iaas/negociacao_recebiveis/assignment/aprovacao
Quando a configuração de cessão exige aprovação manual, o lote aprovado na elegibilidade fica aguardando a decisão da consultoria (`pending_consultant_approval`) e/ou da gestora (`pending_manager_approval`). Este endpoint registra essa decisão: aprovar ou reprovar o lote.
:::info Disponível em
| Perfil | Host | Permissão exigida |
| ----------- | ---------------- | --------------------------------------------------- |
| Gestora | `manager-api` | Escrita |
| Consultoria | `consultant-api` | Lotes |
URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts).
O cedente acessa o mesmo endpoint pela `assignor-api` para [encerrar a inserção](/documentation/iaas/negociacao_recebiveis/assignment/fechamento), mas não pode enviar `approved` nem `denied` (`TRC000059`).
:::
:::info Quem decide em cada status
| Status do lote | Gestora | Consultoria |
|---|---|---|
| `pending_consultant_approval` | Pode reprovar (`denied`) ou reabrir (`pending_assets_insertion`). Não pode aprovar. | Pode aprovar, reprovar ou reabrir. |
| `pending_manager_approval` | Pode aprovar, reprovar ou reabrir. | Não pode agir (`TRC000087`). |
A mesma decisão pode ser tomada pelo [Portal do Gestor](https://portal-do-gestor.fundos.qitech.com.br/) ou pelo [Portal do Consultor](https://portal-do-consultor.fundos.qitech.com.br/).
:::
:::tip Onde estou no fluxo?
Este passo ocorre após a **elegibilidade do lote**. Você recebe um [webhook](/documentation/iaas/negociacao_recebiveis/assignment/webhooks) com o status `pending_consultant_approval` ou `pending_manager_approval` indicando que o lote aguarda decisão. Para conferir a quantidade de ativos e o valor que serão aprovados, consulte o [Resumo de Ativos do Lote](/documentation/iaas/negociacao_recebiveis/assignment/resumo_ativos). Para retirar ativos antes de aprovar, veja [Remoção de Ativos do Lote](/documentation/iaas/negociacao_recebiveis/asset/remocao_ativos).
:::
## Request
ENDPOINT /trade_receivables/fund_class/{fund_class_key}/assignment_configuration/{assignment_configuration_key}/assignment/{assignment_external_id}
MÉTODO PUT
### Path params
| Parâmetro | Tipo | Descrição |
|---|---|---|
| `assignment_external_id` | string | O `external_id` informado na criação do lote. |
```json title="Request Body — Aprovação"
{
"assignment_status": "approved",
"disbursement_account_key": "764746ce-a530-4a71-af66-3f7c879627df",
"number_of_approved_assets": 45,
"assignment_total_value": 150000.00
}
```
```json title="Request Body — Reprovação"
{
"assignment_status": "denied",
"denial_reason": {
"reason_type": "manager",
"denial_reason": "Concentração por sacado acima do limite do fundo"
}
}
```
### Atributos do body
| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `assignment_status` | string | obrigatório | `approved` aprova o lote; `denied` reprova. |
| `disbursement_account_key` | string | opcional | Só na aprovação. Chave (UUID) da conta do cedente que receberá o pagamento, entre as contas cadastradas na homologação do cedente. Se omitida, é usada a conta marcada como padrão do cedente. Recusada quando o lote já tem conta de desembolso definida ou quando o contrato de cessão fixa outra conta. |
| `transfer_type` | string | opcional | Só na aprovação. Forma de pagamento ao cedente: `pix` ou `wire_transfer`. Se omitida, vale a do lote ou da configuração de cessão. |
| `number_of_approved_assets` | integer | opcional | Só na aprovação. Quantidade de ativos aprovados que você espera no lote. Se enviado, `assignment_total_value` também é obrigatório, e os dois são conferidos com o lote antes de aprovar. Use para garantir que aprova exatamente o que analisou. A conferência só é feita na aprovação que encerra a decisão: quando a aprovação da consultoria leva o lote para `pending_manager_approval`, os dois campos são ignorados. |
| `assignment_total_value` | number | opcional | Só na aprovação. Valor total do lote que você espera, em reais. Enviado junto com `number_of_approved_assets`. |
| `denial_reason` | object | opcional | Só na reprovação. Motivo da reprovação: `reason_type` (obrigatório dentro do objeto; use `manager` ou `consultant`) e `denial_reason` (texto livre). Fica registrado em `status_events[].denial_reason` e `status_events[].denial_metadata` na [Recuperação do Lote](/documentation/iaas/negociacao_recebiveis/assignment/recuperacao). |
## Response
STATUS 200
```json title="Response Body — Aprovação"
{
"assignment_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3",
"external_id": "931e9437-d025-41ab-bb53-6b94e10fd361",
"status": "waiting_assets_to_formalize",
"number_of_approved_assets": 45,
"assignment_total_value": 150000.00
}
```
```json title="Response Body — Reprovação"
{
"assignment_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3",
"external_id": "931e9437-d025-41ab-bb53-6b94e10fd361",
"status": "denied"
}
```
### Atributos da resposta
| Campo | Tipo | Descrição |
|---|---|---|
| `assignment_key` | string | Identificador único do lote (UUID). |
| `external_id` | string | Chave externa do lote fornecida pelo parceiro. |
| `status` | string | Novo status do lote. Na aprovação: `pending_manager_approval` (consultoria aprovou e a gestora ainda precisa aprovar), `pending_assets_registry` (configurações com registro dos ativos) ou `waiting_assets_to_formalize`. Na reprovação: `denied`. |
| `number_of_approved_assets` | integer | Só na aprovação. Quantidade de ativos aprovados no lote. É `0` quando o lote segue para a gestora. |
| `assignment_total_value` | number | Só na aprovação. Valor total da cessão, em reais. |
:::caution Aprovação final sem webhook
Quando a aprovação leva o lote para `pending_assets_registry` ou `waiting_assets_to_formalize`, nenhum webhook do lote é enviado nessa transição: use o `status` da resposta. O próximo webhook do lote chega na etapa seguinte (termo de cessão, custódia ou pagamento). A transição para `pending_manager_approval` gera webhook normalmente.
:::
Um lote reprovado (`denied`) não volta para a esteira pela API. No fechamento contábil do dia ele passa para `discarded`.
## Erros
| Status | Código | Quando acontece |
|---|---|---|
| 400 | `TRC000024` | O lote não está em um status que aceite essa decisão (por exemplo, já aprovado ou ainda em elegibilidade). Consulte a [Recuperação do Lote](/documentation/iaas/negociacao_recebiveis/assignment/recuperacao). |
| 400 | `TRC000087` | A gestora tentou aprovar um lote em `pending_consultant_approval`, ou a consultoria tentou agir num lote em `pending_manager_approval`. |
| 400 | `TRC000059` | O cedente enviou `approved` ou `denied`. |
| 400 | `TRC000095` | Foi enviado só um entre `number_of_approved_assets` e `assignment_total_value`. |
| 400 | `TRC000096` | `assignment_total_value` não confere com o valor atual do lote. |
| 400 | `TRC000097` | `number_of_approved_assets` não confere com a quantidade de ativos aprovados. |
| 400 | `TRC000118` | Foi enviado `disbursement_account_key`, mas o lote já tem conta de desembolso definida. |
| 400 | `TRC000149` | Os descontos ao cedente superam o limite permitido para o lote. |
| 400 | `TRC000185` | `disbursement_account_key` diferente da conta fixada no contrato de cessão. |
| 404 | `TRC000018` | Nenhum lote com esse `external_id` nesta configuração de cessão. |
| 404 | `TRC000116` | `disbursement_account_key` não corresponde a nenhuma conta do cedente. |
| 422 | `TRC000186` | A conta de desembolso fixada no contrato de cessão não está mais ativa no cadastro do cedente. Contate o time de integração. |
Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros).
## Próximos passos
Após a aprovação, o fluxo continua automaticamente:
1. **Registro e formalização dos ativos** — conforme o tipo de registro da configuração de cessão.
2. **Termo de Cessão** — o termo é gerado e enviado para assinatura. Você recebe um [webhook](/documentation/iaas/negociacao_recebiveis/assignment/webhooks) com status `pending_assignment_term_signature`. O termo pode ser baixado em [Termo de Cessão do Lote](/documentation/iaas/negociacao_recebiveis/assignment/documento_da_cessao).
3. **Pagamento** — após a assinatura, o sistema realiza o pagamento ao cedente. Um [webhook](/documentation/iaas/negociacao_recebiveis/assignment/webhooks) com status `pending_payment` é enviado.
4. **Encarteiramento** — os ativos são incluídos na carteira do fundo e o lote é finalizado com status `completed`.
---
# Criação do Lote de Cessão
URL: /documentation/iaas/negociacao_recebiveis/assignment/criacao
Este é o **primeiro passo** do fluxo de cessão de direitos creditórios. A criação do lote (*assignment*) reserva um agrupamento onde os ativos que serão cedidos ao fundo serão inseridos nas etapas seguintes.
:::info Disponível em
| Perfil | Host | Permissão exigida |
| ----------- | ---------------- | --------------------------------------------------- |
| Gestora | `manager-api` | Escrita |
| Consultoria | `consultant-api` | Lotes |
| Cedente | `assignor-api` | Escrita |
URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts).
:::
:::info Pré-requisitos
Antes de criar um lote, você precisa ter em mãos:
- A `fund_class_key` — chave única do fundo cessionário.
- A `assignment_configuration_key` — chave única da configuração de cessão, obtida na [Homologação de Cedente](/documentation/iaas/homologacao_cedente/contrato_de_cessao/pedido_de_contrato) ou na [Listagem de Configurações de Cessão](/documentation/iaas/negociacao_recebiveis/listagem). A configuração precisa estar com status `active`.
Essas duas chaves compõem o caminho de todos os endpoints de cessão:
```text
/trade_receivables/fund_class/{fund_class_key}/assignment_configuration/{assignment_configuration_key}
```
:::
## Request
ENDPOINT /trade_receivables/fund_class/{fund_class_key}/assignment_configuration/{assignment_configuration_key}/assignment
MÉTODO POST
```json title="Request Body"
{
"external_id": "931e9437-d025-41ab-bb53-6b94e10fd361",
"assignment_date": "2024-04-01"
}
```
### Atributos do body
| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `external_id` | string | obrigatório | Identificador do lote no seu sistema, de 1 a 50 caracteres. É único em **toda** a plataforma, não só no fundo: use um UUID. É por ele que você consulta o lote e que os webhooks identificam o lote. |
| `assignment_date` | string | opcional | Data da cessão, no formato `YYYY-MM-DD`. Não pode ser anterior à data contábil vigente do fundo. Se omitida, vale a data contábil vigente. Com data futura, o lote fica em `waiting_assignment_date` depois do encerramento da inserção e só entra na esteira nessa data. |
| `payment_type` | string | opcional | Forma de pagamento ao cedente: `pix` ou `wire_transfer`. Se omitido, vale a forma definida na configuração de cessão. |
| `disbursement` | object | opcional | Conta de desembolso específica deste lote, no campo `target_account` (veja abaixo). Se omitido, a conta é definida na aprovação. Recusado quando o contrato de cessão fixa uma única conta de desembolso. |
| `assignor_discounts` | array | opcional | Descontos ao cedente, deduzidos do pagamento da cessão. Só aceito quando a configuração de cessão permite descontos (veja abaixo). |
| `assignment_number` | number | opcional | Número do lote. Se omitido, a QI Tech gera um. |
#### Atributos de `disbursement.target_account`
| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `account_branch` | string | obrigatório | Agência, com 4 dígitos. |
| `account_number` | string | obrigatório | Número da conta, sem o dígito. |
| `account_digit` | string | obrigatório | Dígito da conta (1 caractere). |
| `account_type` | string | obrigatório | `checking_account` ou `escrow_account`. |
| `financial_institution_ispb` | string | obrigatório | ISPB da instituição, com 8 dígitos. |
| `financial_institution_code` | string | opcional | Código COMPE da instituição, com 3 dígitos. |
| `owner.document_number` | string | obrigatório | CPF ou CNPJ do titular, com pontuação. |
#### Atributos de cada item de `assignor_discounts`
| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `assignor_discount_type` | string | obrigatório | `expense_reimbursement` (reembolso de despesa) ou `others`. |
| `total_value` | number | obrigatório | Valor do desconto, em reais. Mínimo `0.01`. |
| `description` | string | obrigatório | Descrição do desconto, de 1 a 500 caracteres. |
| `assignor_discount_key` | string | opcional | UUID v4 do desconto. Se omitido, a QI Tech gera um. |
## Response
STATUS 201
```json title="Response Body"
{
"assignment_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3",
"external_id": "931e9437-d025-41ab-bb53-6b94e10fd361",
"status": "pending_assets_insertion"
}
```
### Atributos da resposta
| Campo | Tipo | Descrição |
|---|---|---|
| `assignment_key` | string | Identificador único do lote gerado pela QI Tech (UUID). |
| `external_id` | string | A mesma chave externa fornecida na requisição. |
| `status` | string | Status inicial do lote: `pending_assets_insertion`, pronto para receber ativos. |
## Reenvio e duplicidade
Em caso de erro, reenvie a requisição. Duplicidade (`TRC000041`) significa que o lote já existe: consulte-o pela [Recuperação do Lote](/documentation/iaas/negociacao_recebiveis/assignment/recuperacao) em vez de recriar. Veja [Reenvio e duplicidade](/documentation/iaas/introducao/erros#reenvio-e-duplicidade).
## Erros
| Status | Código | Quando acontece |
|---|---|---|
| 400 | `TRC000014` | A configuração de cessão não está ativa. |
| 400 | `TRC000083` | `assignment_date` é anterior à data contábil vigente do fundo. Omita o campo ou envie a data contábil vigente. |
| 400 | `TRC000136` | Foram enviados `assignor_discounts`, mas a configuração de cessão não permite descontos ao cedente. |
| 400 | `TRC000185` | Foi enviado `disbursement`, mas o contrato de cessão fixa uma única conta de desembolso. |
| 404 | `TRC000016` | A combinação de `fund_class_key` e `assignment_configuration_key` não corresponde a nenhuma configuração de cessão. |
| 409 | `TRC000041` | Já existe um lote com esse `external_id`. Veja [Reenvio e duplicidade](#reenvio-e-duplicidade). |
| 422 | `TRC000161` | A configuração exige registro dos ativos, mas não tem câmara de registro configurada. Contate o time de integração. |
Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros).
## Próximos passos
1. **[Inserção dos ativos](/documentation/iaas/negociacao_recebiveis/asset/criacao_co)** — adicione os ativos (CCBs, duplicatas etc.) que serão cedidos ao fundo.
2. **[Envio do lastro](/documentation/iaas/negociacao_recebiveis/asset/documents)** — envie os documentos de lastro exigidos para cada ativo. O Termo de Cessão não é enviado por você: a QI Tech o gera depois da aprovação do lote.
3. **[Encerramento da inserção](/documentation/iaas/negociacao_recebiveis/assignment/fechamento)** — sinalize que todos os ativos foram inseridos para que o lote siga para a análise de elegibilidade.
---
# Termo de Cessão do Lote
URL: /documentation/iaas/negociacao_recebiveis/assignment/documento_da_cessao
O Termo de Cessão é o documento que formaliza a transferência dos ativos de **um lote** ao fundo. Quem gera o termo é a QI Tech, depois da aprovação do lote; você não envia nada nesta página, só consulta o termo e acompanha a assinatura.
:::caution Termo de Cessão não é lastro
São três documentos diferentes, cada um com o seu lugar:
| Documento | De quê | Quem produz | Onde fica |
|---|---|---|---|
| **Contrato de cessão** | Do acordo entre cedente e fundo, que vale para todos os lotes | Firmado na homologação do cedente | [Consulta dos Documentos do contrato](/documentation/iaas/homologacao_cedente/contrato_de_cessao/consulta_de_documentos) |
| **Termo de Cessão** | De cada lote | A QI Tech, após a aprovação do lote | Esta página |
| **Lastro** | De cada ativo (CCB, nota fiscal, CT-e, contrato parcelado etc.) | Você envia | [Envio do Lastro do Ativo](/documentation/iaas/negociacao_recebiveis/asset/documents); para baixar depois, o relatório [Lastros da Cessão](/documentation/iaas/relatorios_dtvm/assignment_documents) |
:::
## Qual consulta usar
O termo existe a partir do status `pending_assignment_term_signature` (veja o [webhook do lote](/documentation/iaas/negociacao_recebiveis/assignment/webhooks)). Antes disso, as consultas desta página devolvem `TRC000099`. Na [Recuperação do Lote](/documentation/iaas/negociacao_recebiveis/assignment/recuperacao), `assignment_term_key` preenchido indica que o termo já foi gerado.
| Você quer | Use |
|---|---|
| Baixar o termo (original e assinado) de um lote | [`GET .../assignment/{assignment_external_id}/assignment_term_link`](#link-do-termo-de-cessao) |
| Baixar os termos de vários lotes, por data, status ou cedente | [`GET /trade_receivables/fund_class/{fund_class_key}/assignment_terms`](#listagem-de-termos-de-cessao) |
| Abrir a tela de assinatura do termo na CertifiQI (consultoria) | [`GET .../assignment/{assignment_external_id}/assignment_signature_url`](#link-de-assinatura) |
| Receber o termo assinado sem consultar | Campo `signed_term_url` do [webhook](/documentation/iaas/negociacao_recebiveis/assignment/webhooks) `pending_payment`, válido por 24 horas |
## Link do Termo de Cessão
Recupera os links para download do Termo de Cessão — tanto a versão original quanto a versão assinada. O endpoint responde a partir do momento em que o Termo é gerado; antes disso devolve `TRC000099`.
:::info Disponível em
| Perfil | Host | Permissão exigida |
| ----------- | ---------------- | --------------------------------------------------- |
| Gestora | `manager-api` | Leitura |
| Consultoria | `consultant-api` | Ler Cessões |
| Cedente | `assignor-api` | Leitura |
URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts).
:::
:::tip Quando utilizar
Após receber o [webhook](/documentation/iaas/negociacao_recebiveis/assignment/webhooks) com status `pending_assignment_term_signature`, utilize este endpoint para obter o link do Termo de Cessão e acompanhar se a assinatura já foi concluída.
:::
### Request
ENDPOINT /trade_receivables/fund_class/{fund_class_key}/assignment_configuration/{assignment_configuration_key}/assignment/{assignment_external_id}/assignment_term_link
MÉTODO GET
#### Path params
| Parâmetro | Tipo | Descrição |
|---|---|---|
| `fund_class_key` | string | Chave única do fundo (UUID). |
| `assignment_configuration_key` | string | Chave da configuração de cessão (UUID). |
| `assignment_external_id` | string | O `external_id` informado na criação do lote. |
### Response
STATUS 200
```json title="Response Body"
{
"assignment_term_url": "https://storage.example.com/term/abc123.pdf",
"signed_assignment_term_url": "https://storage.example.com/term/abc123_signed.pdf"
}
```
#### Atributos da resposta
| Campo | Tipo | Descrição |
|---|---|---|
| `assignment_term_url` | string | URL que direciona para o download do termo. |
| `signed_assignment_term_url` | string | URL pré-assinada para download do Termo de Cessão assinado. O arquivo só fica disponível depois que todas as partes assinarem. |
:::info Observação
As duas URLs são pré-assinadas e expiram em 1 hora. Gere um novo link chamando o endpoint novamente.
O campo `signed_assignment_term_url` é sempre retornado, mas o arquivo só existe depois que o Termo de Cessão for assinado por todas as partes envolvidas. Antes disso, o acesso à URL retorna erro. Após a conclusão da assinatura, o lote avança para `pending_payment`, com [webhook](/documentation/iaas/negociacao_recebiveis/assignment/webhooks), ou para `pending_custody`, sem webhook, conforme a configuração de cessão. Nesse segundo caso, acompanhe pela [Recuperação do Lote](/documentation/iaas/negociacao_recebiveis/assignment/recuperacao).
:::
---
## Listagem de Termos de Cessão
Endpoint de consulta paginada que retorna os Termos de Cessão dos lotes de uma classe de fundo, com os links pré-assinados para download do termo original e do termo assinado. Utilize os filtros para buscar os termos por data da cessão, período, status ou por um lote específico.
:::info Disponível em
| Perfil | Host | Permissão exigida |
| ----------- | ---------------- | --------------------------------------------------- |
| Gestora | `manager-api` | Leitura |
| Consultoria | `consultant-api` | Ler Cessões |
URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts).
:::
:::info Endpoint por classe de fundo
Assim como a [Listagem de Lotes](/documentation/iaas/negociacao_recebiveis/assignment/listagem), este endpoint utiliza apenas a `fund_class_key` na URL — não é necessário informar a `assignment_configuration_key`. Para obter o termo de um lote específico, informe o `external_id` do lote como filtro.
:::
São retornados apenas os lotes que já possuem Termo de Cessão gerado e que pertencem ao agente autenticado (gestor ou consultor vinculado à classe de fundo).
### Request
ENDPOINT /trade_receivables/fund_class/{fund_class_key}/assignment_terms
MÉTODO GET
#### Path params
| Parâmetro | Tipo | Descrição |
|---|---|---|
| `fund_class_key` | string | Chave única do fundo (UUID). |
#### Query params
| Parâmetro | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `assignment_date` | string | opcional | Filtra por data da cessão no formato `YYYY-MM-DD`. |
| `start_date` | string | opcional | Retorna lotes com data da cessão igual ou posterior à data informada, no formato `YYYY-MM-DD`. |
| `end_date` | string | opcional | Retorna lotes com data da cessão igual ou anterior à data informada, no formato `YYYY-MM-DD`. |
| `external_id` | string | opcional | Filtra pelo `external_id` informado na criação do lote. |
| `assignment_key` | string | opcional | Filtra pela chave do lote (UUID). |
| `assignment_status` | string | opcional | Filtra por um status específico do lote. |
| `in_status` | string | opcional | Lista de status separados por vírgula. Retorna apenas lotes que estejam em um dos status informados. |
| `not_in_status` | string | opcional | Lista de status separados por vírgula. Exclui os lotes nesses status. |
| `assignor_document_number` | string | opcional | Filtra por número de documento (CPF/CNPJ) do cedente. Deve ser enviado **com pontuação** (ex.: `11.222.333/0001-81` ou `969.698.790-03`). |
| `origin_type` | string | opcional | Filtra pela origem do lote (ex: `client`). |
| `page` | integer | opcional | Número da página (começa em 0). Padrão: `0`. |
| `limit` | integer | opcional | Quantidade de registros por página. Padrão: `25`. Máximo: `155`. |
```text title="Exemplo de chamada — termos de uma data"
GET /trade_receivables/fund_class/{fund_class_key}/assignment_terms?assignment_date=2024-04-01&page=0&limit=25
```
```text title="Exemplo de chamada — termo de um lote pelo external_id"
GET /trade_receivables/fund_class/{fund_class_key}/assignment_terms?external_id=931e9437-d025-41ab-bb53-6b94e10fd361
```
### Response
STATUS 200
```json title="Response Body"
{
"data": [
{
"assignment_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3",
"external_id": "931e9437-d025-41ab-bb53-6b94e10fd361",
"name": "CESSÃO #12345",
"assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef",
"assignment_number": "00012345",
"assignment_date": "2024-04-01",
"status": "completed",
"assignment_term_key": "b1c2d3e4-f5a6-7890-abcd-ef1234567890",
"assignment_term_url": "https://storage.example.com/term/abc123.pdf",
"signed_assignment_term_url": "https://storage.example.com/term/abc123_signed.pdf"
}
],
"limit": 25,
"page": 0,
"is_last_page": true
}
```
#### Atributos da resposta
| Campo | Tipo | Descrição |
|---|---|---|
| `data` | array | Lista de Termos de Cessão. Veja tabela abaixo. |
| `page` | integer | Número da página atual. |
| `limit` | integer | Quantidade de registros por página. |
| `is_last_page` | boolean | Indica se esta é a última página de resultados. |
**Atributos de cada termo (objetos dentro de `data`)**
| Campo | Tipo | Descrição |
|---|---|---|
| `assignment_key` | string | Identificador único do lote (UUID). |
| `external_id` | string | Chave externa fornecida pelo parceiro. |
| `name` | string | Nome identificador da cessão. |
| `assignment_configuration_key` | string | Chave da configuração de cessão do lote (UUID). |
| `assignment_number` | string | Número do lote de cessão. |
| `assignment_date` | string | Data da cessão no formato `YYYY-MM-DD`. |
| `status` | string | Status atual do lote. Consulte os [enumeradores de status do lote](/documentation/iaas/negociacao_recebiveis/assignment/listagem#enumeradores-de-status-do-lote). |
| `assignment_term_key` | string | Chave do Termo de Cessão (UUID). |
| `assignment_term_url` | string | URL pré-assinada para download do Termo de Cessão original. |
| `signed_assignment_term_url` | string | URL pré-assinada para download do Termo de Cessão assinado. O arquivo só fica disponível depois que todas as partes assinarem. |
:::info Observação
As URLs são pré-assinadas e expiram em 1 hora. Para obter novos links, chame o endpoint novamente.
Os lotes são ordenados do mais recente para o mais antigo. Lotes que ainda não tiveram o Termo de Cessão gerado não aparecem na listagem.
:::
---
## Link de Assinatura
Recupera o link para acesso à interface de assinatura do Termo de Cessão na CertifiQI, além de informações sobre os lotes e o link para download do documento. O endpoint responde a partir do momento em que o Termo é gerado. Não está disponível quando a assinatura é feita pela QCertifica ou quando a configuração de cessão dispensa assinatura (`TRC000131`).
:::info Disponível em
| Perfil | Host | Permissão exigida |
| ----------- | ---------------- | --------------------------------------------------- |
| Consultoria | `consultant-api` | Ler Cessões |
URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts).
:::
### Request
ENDPOINT /trade_receivables/fund_class/{fund_class_key}/assignment_configuration/{assignment_configuration_key}/assignment/{assignment_external_id}/assignment_signature_url
MÉTODO GET
#### Path params
| Parâmetro | Tipo | Descrição |
|---|---|---|
| `fund_class_key` | string | Chave única do fundo (UUID). |
| `assignment_configuration_key` | string | Chave da configuração de cessão (UUID). |
| `assignment_external_id` | string | O `external_id` informado na criação do lote. |
### Response
STATUS 200
```json title="Response Body"
{
"batches": [
{
"name": "Termo de Cessão - Lote 001",
"document_type": "assignment_term",
"status": "pending",
"document_key": "doc-uuid-example",
"related_parties": []
}
],
"signature_url": "https://certifiqi.com/events/{external_batch_group_key}",
"download_url": "https://storage.example.com/term/abc123.pdf"
}
```
#### Atributos da resposta
| Campo | Tipo | Descrição |
|---|---|---|
| `batches` | array | Lista de lotes vinculados ao Termo de Cessão. |
| `batches[].name` | string | Nome do lote. |
| `batches[].document_type` | string | Tipo do documento (ex: `assignment_term`, `duplicata`). |
| `batches[].status` | string | Status atual da assinatura do lote. |
| `batches[].document_key` | string | Chave identificadora do documento. |
| `batches[].related_parties` | array | Partes envolvidas na assinatura do lote. |
| `signature_url` | string | URL para acesso à interface de assinatura na CertifiQI. |
| `download_url` | string | URL pré-assinada para download do Termo de Cessão. |
:::info Observação
O campo `download_url` aponta para o documento original (não assinado) enquanto o lote estiver em `pending_send_to_signature` ou `pending_assignment_term_signature`. Depois da assinatura por todas as partes, passa a apontar para o Termo de Cessão assinado. A URL é pré-assinada e expira em 1 hora.
:::
## Erros
| Status | Código | Endpoint | Quando acontece |
|---|---|---|---|
| 400 | `TRC000099` | Link do termo, link de assinatura | O Termo de Cessão do lote ainda não foi gerado. |
| 400 | `TRC000131` | Link de assinatura | A configuração de cessão não usa assinatura eletrônica com link (por exemplo, assinatura pela QCertifica ou sem assinatura), ou o link ainda não está disponível. |
| 400 | — | Listagem de termos | `limit` acima de 155 ou `page` negativo (validação de parâmetro). |
| 404 | `TRC000018` | Link do termo, link de assinatura | Nenhum lote com esse `external_id` nesta configuração de cessão. |
Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros).
---
# Encerrar Inserção de Ativos
URL: /documentation/iaas/negociacao_recebiveis/assignment/fechamento
Após inserir todos os ativos desejados no lote, utilize este endpoint para sinalizar que a inserção foi concluída. A partir desse momento o lote não recebe novos ativos. Quando todos os ativos estiverem com a análise individual concluída (`pre_approved`, `pending_formalization`, `denied` ou `registry_denied`), a elegibilidade do lote como um todo é avaliada automaticamente.
:::info Disponível em
| Perfil | Host | Permissão exigida |
| ----------- | ---------------- | --------------------------------------------------- |
| Gestora | `manager-api` | Escrita |
| Consultoria | `consultant-api` | Lotes |
| Cedente | `assignor-api` | Escrita |
URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts).
:::
:::info Não é necessário aguardar os webhooks dos ativos
Você pode encerrar a inserção a qualquer momento após inserir os ativos. Não é preciso esperar que todos os ativos passem pela elegibilidade individual: o sistema aguarda até que todos estejam com a análise concluída antes de prosseguir com a elegibilidade do lote.
:::
:::tip Onde estou no fluxo?
Este é o **3º passo** do fluxo de cessão. Antes deste passo, você deve ter:
1. [Criado o lote](/documentation/iaas/negociacao_recebiveis/assignment/criacao)
2. [Inserido os ativos](/documentation/iaas/negociacao_recebiveis/asset/criacao_co) e [enviado o lastro](/documentation/iaas/negociacao_recebiveis/asset/documents) de cada ativo
:::
## Request
ENDPOINT /trade_receivables/fund_class/{fund_class_key}/assignment_configuration/{assignment_configuration_key}/assignment/{assignment_external_id}
MÉTODO PUT
### Path params
| Parâmetro | Tipo | Descrição |
|---|---|---|
| `assignment_external_id` | string | O `external_id` informado na criação do lote. |
```json title="Request Body"
{
"assignment_status": "completed_assets_insertion"
}
```
### Atributos do body
| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `assignment_status` | string | obrigatório | Para encerrar a inserção de ativos, envie `completed_assets_insertion`. O lote precisa estar em `pending_assets_insertion`. |
## Response
STATUS 200
```json title="Response Body"
{
"assignment_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3",
"external_id": "931e9437-d025-41ab-bb53-6b94e10fd361",
"status": "completed_assets_insertion",
"number_of_approved_assets": 0,
"assignment_total_value": 15230.75
}
```
### Atributos da resposta
| Campo | Tipo | Descrição |
|---|---|---|
| `assignment_key` | string | Identificador único do lote (UUID). |
| `external_id` | string | Chave externa do lote fornecida pelo parceiro. |
| `status` | string | Novo status do lote: `completed_assets_insertion`, ou `waiting_assignment_date` quando a `assignment_date` do lote é posterior à data contábil do fundo. Nesse caso o lote passa para `completed_assets_insertion` na data da cessão. Essa passagem não gera webhook. |
| `number_of_approved_assets` | integer | Sempre `0` nesta chamada: a contagem de ativos aprovados só é feita na aprovação. |
| `assignment_total_value` | number | Soma do `total_purchase_value` dos ativos não reprovados (`denied`/`registry_denied`), em reais. Em lotes de substituição, já descontado o valor dos ativos recomprados. |
## Erros
| Status | Código | Quando acontece |
|---|---|---|
| 400 | `TRC000023` | `assignment_status` com valor não aceito. Os valores aceitos neste endpoint são `completed_assets_insertion`, `pending_assets_insertion`, `approved` e `denied`. |
| 400 | `TRC000024` | O lote não está em `pending_assets_insertion`. |
| 400 | `TRC000042` | O lote não tem nenhum ativo em análise ou aprovado. [Insira pelo menos um ativo](/documentation/iaas/negociacao_recebiveis/asset/criacao_co) antes de encerrar. |
| 400 | `TRC000160` | Todos os ativos do lote foram reprovados. |
| 400 | `TRC000092` | Lote de substituição: o valor dos novos ativos é menor que o valor dos ativos recomprados. |
| 400 | `TRC000093` | Lote de substituição sem nenhum [ativo de recompra](/documentation/iaas/negociacao_recebiveis/asset/criacao_repurchased_asset). |
| 404 | `TRC000018` | Nenhum lote com esse `external_id` nesta configuração de cessão. |
Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros).
## Próximos passos
Após encerrar a inserção, o fluxo segue automaticamente:
1. **Elegibilidade dos ativos** — cada ativo é analisado individualmente. Você recebe [webhooks dos ativos](/documentation/iaas/negociacao_recebiveis/asset/webhooks) informando aprovação ou reprovação.
2. **Elegibilidade do lote** — quando todos os ativos tiverem sido analisados, a elegibilidade do lote é avaliada. O resultado é informado via [webhook do lote](/documentation/iaas/negociacao_recebiveis/assignment/webhooks).
3. **[Aprovação](/documentation/iaas/negociacao_recebiveis/assignment/aprovacao)** — se a configuração de cessão exigir, a consultoria e/ou a gestora aprovam o lote.
---
# Listagem de Lotes de Cessão
URL: /documentation/iaas/negociacao_recebiveis/assignment/listagem
Endpoint de consulta paginada que retorna os lotes de cessão de uma classe de fundo, de todas as configurações de cessão. Use os filtros para buscar lotes por data, status, cedente ou identificador.
:::info Disponível em
| Perfil | Host | Permissão exigida |
| ----------- | ---------------- | --------------------------------------------------- |
| Gestora | `manager-api` | Leitura |
| Consultoria | `consultant-api` | Ler Cessões |
URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts).
:::
:::info Endpoint por classe de fundo
Diferente dos demais endpoints de lote, este usa apenas a `fund_class_key` na URL. A resposta traz só os lotes que o seu perfil pode ver.
:::
## Request
ENDPOINT /trade_receivables/fund_class/{fund_class_key}/assignments
MÉTODO GET
### Query params
Todos os filtros são opcionais e podem ser combinados.
| Parâmetro | Tipo | Descrição |
|---|---|---|
| `assignment_date` | string | Data da cessão, no formato `YYYY-MM-DD`. |
| `start_date` | string | Lotes com data da cessão igual ou posterior, no formato `YYYY-MM-DD`. |
| `end_date` | string | Lotes com data da cessão igual ou anterior, no formato `YYYY-MM-DD`. |
| `assignment_status` | string | Um status do lote. |
| `in_status` | string | Lista de status separados por vírgula. Retorna só os lotes em um deles. |
| `not_in_status` | string | Lista de status separados por vírgula. Exclui os lotes nesses status. |
| `assignor_document_number` | string | CPF/CNPJ do cedente, **com pontuação** (ex.: `11.222.333/0001-81` ou `969.698.790-03`). |
| `external_id` | string | O `external_id` do lote. |
| `assignment_key` | string | A chave do lote (UUID). |
| `origin_type` | string | Origem do lote (ex.: `client`). |
| `page` | integer | Número da página (começa em 0). Padrão: `0`. |
| `limit` | integer | Registros por página. Padrão: `25`. Máximo: `155`. |
```text title="Exemplo de chamada"
GET /trade_receivables/fund_class/{fund_class_key}/assignments?assignment_date=2024-04-01&in_status=pending_manager_approval,completed&page=0&limit=10
```
## Response
STATUS 200
```json title="Response Body (objetos de data resumidos)"
{
"data": [
{
"assignment_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3",
"external_id": "931e9437-d025-41ab-bb53-6b94e10fd361",
"name": "CESSÃO #12345",
"assignment_configuration": {
"assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef",
"asset_type": "ccb"
},
"assignment_number": "12345",
"assignment_date": "2024-04-01",
"status": "completed",
"assignment_term_key": "b1c2d3e4-f5a6-4890-abcd-ef1234567890",
"disbursement": null,
"origin_type": "client",
"payment_type": "pix",
"assignment_total_value": 150000.00,
"assignment_irr": 0.0215
}
],
"limit": 10,
"page": 0,
"is_last_page": true
}
```
### Atributos da resposta
| Campo | Tipo | Descrição |
|---|---|---|
| `data` | array | Lotes encontrados, do mais recente para o mais antigo. |
| `page` | integer | Número da página atual. |
| `limit` | integer | Registros por página. |
| `is_last_page` | boolean | `true` na última página de resultados. |
Cada objeto de `data` tem a mesma estrutura da [Recuperação do Lote](/documentation/iaas/negociacao_recebiveis/assignment/recuperacao#atributos-da-resposta) — inclusive o objeto `assignment_configuration` completo —, exceto `status_events`, que não vem na listagem.
## Enumeradores de status do lote
| Status | Descrição |
|---|---|
| `created` | Lote criado; passa imediatamente para `pending_assets_insertion`. |
| `pending_assets_insertion` | Aguardando inserção de ativos. |
| `waiting_assignment_date` | Inserção encerrada, aguardando a data da cessão (lote com `assignment_date` futura). |
| `completed_assets_insertion` | Inserção encerrada, aguardando a análise individual dos ativos terminar. |
| `pending_eligibility` | Em análise de elegibilidade do lote. |
| `pending_consultant_approval` | Aguardando aprovação da consultoria. |
| `pending_manager_approval` | Aguardando aprovação da gestora. |
| `pending_assets_registry` | Aguardando o registro dos ativos. |
| `waiting_assets_to_formalize` | Aguardando a formalização dos ativos aprovados. |
| `pending_assignment_term` | Gerando o Termo de Cessão. |
| `pending_send_to_signature` | Termo de Cessão gerado, sendo enviado para assinatura. |
| `pending_assignment_term_signature` | Aguardando assinatura do Termo de Cessão. |
| `pending_assignment_term_validation` | Termo de Cessão em validação. |
| `pending_custody` | Aguardando custódia. |
| `pending_payment` | Aguardando pagamento ao cedente. |
| `pending_assets_wallet_inclusion` | Aguardando encarteiramento dos ativos. |
| `pending_after_assignment_documentation` | Ativos encarteirados; aguardando documentos pós-cessão. |
| `pending_after_assignment_registry` | Ativos encarteirados; aguardando o registro pós-cessão (registro diferido). |
| `waiting_after_assignment_registry` | Registro pós-cessão enviado, aguardando retorno. |
| `completed` | Cessão finalizada com sucesso. |
| `denied` | Lote reprovado (elegibilidade, registro ou decisão da consultoria/gestora). |
| `discarded` | Lote descartado, por exemplo no fechamento contábil do fundo. |
Quais desses status geram webhook está em [Webhooks do Lote de Cessão](/documentation/iaas/negociacao_recebiveis/assignment/webhooks).
## Erros
| Status | Código | Quando acontece |
|---|---|---|
| 400 | — | `limit` acima de 155 ou `page` negativo (validação de parâmetro). |
Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros).
---
# Recuperação do Lote de Cessão
URL: /documentation/iaas/negociacao_recebiveis/assignment/recuperacao
Recupera os detalhes completos de um lote de cessão específico, incluindo a configuração de cessão, o status atual, o histórico de eventos, os dados de desembolso e os valores financeiros.
:::info Disponível em
| Perfil | Host | Permissão exigida |
| ----------- | ---------------- | --------------------------------------------------- |
| Gestora | `manager-api` | Leitura |
| Consultoria | `consultant-api` | Ler Cessões |
| Cedente | `assignor-api` | Leitura |
URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts).
:::
:::tip Quando utilizar
Use este endpoint para consultar o estado atual de um lote a qualquer momento do fluxo — por exemplo, para verificar se o lote já passou pela elegibilidade, se já foi aprovado ou se o pagamento foi realizado. Também é a consulta a fazer quando a criação devolve duplicidade (`TRC000041`).
:::
## Request
ENDPOINT /trade_receivables/fund_class/{fund_class_key}/assignment_configuration/{assignment_configuration_key}/assignment/{assignment_external_id}
MÉTODO GET
### Path params
| Parâmetro | Tipo | Descrição |
|---|---|---|
| `fund_class_key` | string | Chave única do fundo (UUID). |
| `assignment_configuration_key` | string | Chave da configuração de cessão (UUID). |
| `assignment_external_id` | string | O `external_id` informado na criação do lote. |
## Response
STATUS 200
**Response Body**
```json title="Response Body"
{
"assignment_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3",
"external_id": "931e9437-d025-41ab-bb53-6b94e10fd361",
"name": "CESSÃO #12345",
"assignment_configuration": {
"assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef",
"validation_configuration_key": "5f0e3a4c-2b7d-4c1e-9a8f-0d6b1c2e3f40",
"assignment_configuration_name": "Config CCB Fundo Alpha",
"assignment_contract_key": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
"registry_type": "internal_registry",
"asset_type": "ccb",
"fund_class": {
"fund_class_key": "f1a2b3c4-d5e6-4890-abcd-ef1234567890",
"name": "Fundo Alpha FIDC",
"document_number": "11.222.333/0001-81",
"accounting_date": "2024-04-01",
"manager": {
"manager_key": "e1f2a3b4-c5d6-4890-abcd-ef1234567890",
"document_number": "22.222.222/0001-91",
"manager_name": "Gestora Exemplo S.A."
}
},
"assignor": {
"assignor_key": "c1d2e3f4-a5b6-4890-abcd-ef1234567890",
"document_number": "33.333.333/0001-91",
"name": "Cedente Exemplo Ltda"
},
"assignment_reports": {
"send_reports": false
},
"assignment_configuration_type": "default_configuration",
"status": "active",
"consultant_decision_type": "manual_approval",
"manager_decision_type": "manual_approval",
"asset_fees": null,
"payment_type": "pix",
"custody_type": "internal",
"required_documents": ["ccb"],
"after_assignment_required_documents": [],
"certifier": "certifiqi",
"disbursement_account_policy": "all_assignor_accounts",
"consultant": {
"consultant_key": "a7b8c9d0-e1f2-4a3b-8c4d-5e6f7a8b9c0d",
"document_number": "44.444.444/0001-91",
"name": "Consultoria Exemplo Ltda"
},
"operation_type": "unsecured_credit",
"originator_bonds": [
{
"originator": {
"originator_key": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
"document_number": "33.333.333/0001-91",
"name": "Cedente Exemplo Ltda"
}
}
]
},
"assignment_number": "12345",
"assignment_date": "2024-04-01",
"status": "completed",
"assignment_term_key": "b1c2d3e4-f5a6-4890-abcd-ef1234567890",
"disbursement": {
"target_account": {
"account_key": "d1e2f3a4-b5c6-4890-abcd-ef1234567890",
"account_type": "checking_account",
"account_branch": "0001",
"account_number": "12345",
"account_digit": "4",
"financial_institution_code": "341",
"financial_institution_ispb": "60701190",
"owner": {
"document_number": "33.333.333/0001-91"
},
"payment_type": "pix"
}
},
"origin_type": "client",
"payment_type": "pix",
"assignment_total_value": 150000.00,
"assignment_irr": 0.0215,
"status_events": [
{
"status": "pending_assets_insertion",
"event_datetime": "2024-04-01 10:00:00.123456",
"selected_agent": {
"AGENT-TYPE": "assignor",
"AGENT-KEY": "c1d2e3f4-a5b6-4890-abcd-ef1234567890",
"AGENT-USER": "usuario@exemplo.com"
}
},
{
"status": "completed_assets_insertion",
"event_datetime": "2024-04-01 11:30:00.654321"
},
{
"status": "completed",
"event_datetime": "2024-04-01 16:00:00.000000"
}
]
}
```
### Atributos da resposta
| Campo | Tipo | Descrição |
|---|---|---|
| `assignment_key` | string | Identificador único do lote gerado pela QI Tech (UUID). |
| `external_id` | string | Chave externa fornecida pelo parceiro na criação. |
| `name` | string | Nome identificador da cessão. |
| `assignment_number` | string | Número do lote de cessão. |
| `assignment_date` | string | Data da cessão no formato `YYYY-MM-DD`. |
| `status` | string | Status atual do lote. Veja os [status do lote](/documentation/iaas/negociacao_recebiveis/assignment/listagem#enumeradores-de-status-do-lote). |
| `origin_type` | string | Origem do lote. Lotes criados pela API de integração têm `client`. |
| `payment_type` | string \| null | Forma de pagamento ao cedente: `pix` ou `wire_transfer`. Vem do lote ou, se não informada nele, da configuração de cessão. |
| `assignment_term_key` | string \| null | Chave do Termo de Cessão (UUID). Preenchida depois que o termo é gerado; a partir daí, baixe-o em [Termo de Cessão do Lote](/documentation/iaas/negociacao_recebiveis/assignment/documento_da_cessao). |
| `assignment_total_value` | number | Valor total da cessão em reais. Ausente até o primeiro cálculo, feito no encerramento da inserção. |
| `assignment_irr` | number | Taxa interna de retorno do lote. Ausente enquanto não calculada. |
| `assignment_configuration` | object | Configuração de cessão do lote. Os campos estão em [Listagem de Configurações de Cessão](/documentation/iaas/negociacao_recebiveis/listagem#atributos-de-cada-configuracao-objetos-dentro-de-data). |
| `disbursement` | object \| null | Conta de desembolso do lote, em `target_account`, com os campos da conta e a `payment_type` usada. `null` enquanto não definida. |
| `assignor_discounts` | array | Descontos ao cedente. Presente apenas quando o lote tem descontos. Veja tabela abaixo. |
| `status_events` | array | Histórico de transições de status do lote. Veja tabela abaixo. |
#### Atributos de `assignor_discounts`
| Campo | Tipo | Descrição |
|---|---|---|
| `assignor_discount_key` | string | Chave única do desconto (UUID). |
| `assignor_discount_type` | string | `expense_reimbursement` ou `others`. |
| `status` | string | `created`, `pending_execution`, `executed` ou `rejected`. |
| `total_value` | number | Valor do desconto em reais. |
| `description` | string | Descrição do desconto. |
#### Atributos de `status_events`
| Campo | Tipo | Descrição |
|---|---|---|
| `status` | string | Status para o qual o lote foi. |
| `event_datetime` | string | Data e hora da transição, em UTC, no formato `YYYY-MM-DD HH:MM:SS.ffffff`. |
| `selected_agent` | object | Agente que fez a transição (`AGENT-TYPE`, `AGENT-KEY` e `AGENT-USER`). Ausente em transições automáticas. |
| `denial_reason` | string | Presente em `denied` e `discarded`: origem da reprovação ou do descarte (`eligibility`, `registry`, `accounting_close`, `payment`, `manager`, `asset_documents`, `manual`, `consultant` ou `inconsistency`). |
| `denial_metadata` | object | Detalhe da reprovação, quando houver — por exemplo, as regras de elegibilidade reprovadas ou o `denial_reason` enviado na [aprovação](/documentation/iaas/negociacao_recebiveis/assignment/aprovacao). |
## Erros
| Status | Código | Quando acontece |
|---|---|---|
| 404 | `TRC000016` | A combinação de `fund_class_key` e `assignment_configuration_key` não corresponde a nenhuma configuração de cessão. |
| 404 | `TRC000018` | Nenhum lote com esse `external_id` nesta configuração de cessão. |
Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros).
---
# Resumo de ativos do lote
URL: /documentation/iaas/negociacao_recebiveis/assignment/resumo_ativos
Retorna a quantidade de ativos de um lote de cessão, separada entre aprovados e reprovados, e o valor total do lote. São os mesmos números conferidos na [aprovação do lote](/documentation/iaas/negociacao_recebiveis/assignment/aprovacao).
:::info Disponível em
| Perfil | Host | Permissão exigida |
| ----------- | ---------------- | --------------------------------------------------- |
| Gestora | `manager-api` | Leitura |
| Consultoria | `consultant-api` | Ler Cessões |
URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts).
:::
:::tip Quando utilizar
O [webhook](/documentation/iaas/negociacao_recebiveis/assignment/webhooks) `pending_consultant_approval` ou `pending_manager_approval` informa só a mudança de status do lote. Consulte este endpoint nesse momento para saber quantos ativos o lote tem, por exemplo para confirmar que todos os ativos esperados chegaram, sem precisar paginar a [listagem de ativos](/documentation/iaas/negociacao_recebiveis/asset/recuperar_ativos). Os valores de `number_of_approved_assets` e `assignment_total_value` podem ser enviados sem alteração no corpo da aprovação.
:::
## Request
ENDPOINT /trade_receivables/fund_class/{fund_class_key}/assignment_configuration/{assignment_configuration_key}/assignment/{assignment_external_id}/assets_summary
MÉTODO GET
### Path params
| Parâmetro | Tipo | Descrição |
|---|---|---|
| `fund_class_key` | string | Chave única do fundo (UUID). |
| `assignment_configuration_key` | string | Chave da configuração de cessão (UUID). |
| `assignment_external_id` | string | O `external_id` informado na criação do lote. |
## Response
STATUS 200
```json title="Response Body"
{
"assignment_external_id": "931e9437-d025-41ab-bb53-6b94e10fd361",
"assignment_status": "pending_manager_approval",
"number_of_assets": 198,
"number_of_approved_assets": 195,
"number_of_denied_assets": 3,
"assignment_total_value": 1234567.89
}
```
### Atributos da resposta
| Campo | Tipo | Descrição |
|---|---|---|
| `assignment_external_id` | string | O `external_id` do lote informado na criação. |
| `assignment_status` | string | Status atual do lote. Veja os [status do lote](/documentation/iaas/negociacao_recebiveis/assignment/listagem#enumeradores-de-status-do-lote). |
| `number_of_assets` | integer | Quantidade total de ativos do lote, em qualquer status. Inclui os ativos ainda em análise. |
| `number_of_approved_assets` | integer | Ativos em `pre_approved` ou `pending_formalization`. É o número conferido em `number_of_approved_assets` na aprovação. |
| `number_of_denied_assets` | integer | Ativos em `denied` ou `registry_denied`. |
| `assignment_total_value` | number | Valor total do lote, em reais: soma do valor de compra dos ativos não reprovados, descontado o valor dos ativos recomprados no lote. É o valor conferido em `assignment_total_value` na aprovação. |
`number_of_assets` pode ser maior que a soma de aprovados e reprovados enquanto houver ativos em análise. Quando o lote chega em `pending_consultant_approval` ou `pending_manager_approval`, a análise de todos os ativos já terminou e os números ficam estáveis até a decisão, salvo se ativos forem [removidos do lote](/documentation/iaas/negociacao_recebiveis/asset/remocao_ativos).
:::caution Envie o valor sem arredondar
A aprovação compara `assignment_total_value` com o valor do lote de forma exata. Envie o número como ele veio na resposta: um valor arredondado ou truncado devolve `TRC000096`.
:::
## Erros
| Status | Código | Quando acontece |
|---|---|---|
| 404 | `TRC000016` | A combinação de `fund_class_key` e `assignment_configuration_key` não corresponde a nenhuma configuração de cessão. |
| 404 | `TRC000018` | Nenhum lote com esse `external_id` nesta configuração de cessão. |
Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros).
---
# Como criar uma cessão?
URL: /documentation/iaas/negociacao_recebiveis/assignment/video_cessao
Este guia apresenta o fluxo completo de criação de uma cessão de direitos creditórios, desde a criação do lote até o encarteiramento dos ativos no fundo. Utilize o vídeo abaixo como referência visual e os links para acessar a documentação detalhada de cada etapa.
:::tip Manual completo
Para um entendimento aprofundado das regras de negócio e do produto, consulte o [Manual de Cessão de Direitos Creditórios](/documentation/iaas/negociacao_recebiveis/manual_api).
:::
## Vídeo — Fluxo de cessão via Python
## Passo a passo
### 1. Criação do Lote
Crie um lote de cessão informando um identificador único (`external_id`). O lote será o contêiner para todos os ativos que serão cedidos ao fundo.
**[Acessar documentação da criação do lote](/documentation/iaas/negociacao_recebiveis/assignment/criacao)**
### 2. Inserção dos Ativos
Adicione os ativos (CCBs, duplicatas, etc.) ao lote criado. Cada ativo deve ser inserido individualmente com suas informações de operação, parcelas e dados do sacado.
**[Acessar documentação da inserção de ativos](/documentation/iaas/negociacao_recebiveis/asset/criacao_co)**
### 3. Envio do Lastro
Para cada ativo inserido, envie o lastro exigido pelo produto: os documentos que comprovam o ativo (CCB, contrato, nota fiscal etc.) — pode ser logo após a inserção. O ativo só prossegue na esteira após todos os documentos exigidos serem enviados.
**[Acessar documentação do envio do lastro](/documentation/iaas/negociacao_recebiveis/asset/documents)**
### 4. Encerramento da Inserção
Sinalize que todos os ativos foram inseridos no lote. Esse comando permite que o sistema avalie a elegibilidade do lote como um todo após todos os ativos serem analisados.
**[Acessar documentação do encerramento](/documentation/iaas/negociacao_recebiveis/assignment/fechamento)**
### 5. Aprovação
Após a elegibilidade do lote, se a configuração de cessão exigir, a consultoria e/ou a gestora aprovam ou reprovam o lote. Com aprovação automática, nenhuma ação é necessária.
**[Acessar documentação da aprovação](/documentation/iaas/negociacao_recebiveis/assignment/aprovacao)**
### 6. Assinatura, Pagamento e Encarteiramento
Os passos finais são automatizados: o Termo de Cessão é assinado pelas partes, o pagamento é realizado ao cedente e os ativos são encarteirados na carteira do fundo. Acompanhe o progresso através dos [webhooks do lote](/documentation/iaas/negociacao_recebiveis/assignment/webhooks). Para baixar o termo, original ou assinado, ou abrir o link de assinatura, veja [Termo de Cessão do Lote](/documentation/iaas/negociacao_recebiveis/assignment/documento_da_cessao).
---
# Webhooks do Lote de Cessão
URL: /documentation/iaas/negociacao_recebiveis/assignment/webhooks
Ao longo do fluxo de cessão, o sistema envia webhooks para notificar mudanças de status do lote. Todos têm o tipo `trade_receivables.assignment_status_change` e identificam o lote pelo `assignment_external_id` informado na criação.
:::info Configuração de webhooks
Para receber webhooks, é necessário ter uma URL de callback configurada junto à QI Tech. A configuração define **quais status** você recebe: só são enviados os eventos assinados nela. Entre em contato com [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br) para configurar. Entrega, tentativas e assinatura: veja [Recebimento de Webhooks](/documentation/iaas/introducao/autenticacao_webhooks).
:::
## Fluxo de status do lote
_Como ler o diagrama: **azul** = status intermediário com webhook · **tracejado** = status sem webhook · **verde** = cessão concluída · **vermelho** = status final de recusa ou descarte._
A lista completa de status, inclusive os que não geram webhook, está em [Enumeradores de status do lote](/documentation/iaas/negociacao_recebiveis/assignment/listagem#enumeradores-de-status-do-lote).
## Estrutura do webhook
| Campo | Tipo | Descrição |
|---|---|---|
| `webhook_type` | string | Sempre `trade_receivables.assignment_status_change`. |
| `webhook_datetime` | string | Data e hora do envio, no formato `YYYY-MM-DDTHH:MM:SSZ`. |
| `data` | object | Dados do evento. Veja tabela abaixo. |
### Atributos de `data`
| Campo | Tipo | Descrição |
|---|---|---|
| `assignment_external_id` | string | O `external_id` do lote informado na criação. |
| `assignment_new_status` | string | Novo status do lote. |
| `assignment_configuration_key` | string | Configuração de cessão à qual o lote pertence — a mesma chave usada nas URLs dos endpoints. Como um cedente pode ter mais de uma configuração ativa, ela indica sob qual acordo o evento aconteceu. |
| `fund_class_key` | string | Classe do fundo do lote. |
| `signed_term_url` | string | Só no webhook `pending_payment`, quando o Termo de Cessão foi assinado eletronicamente: URL pré-assinada para download do termo assinado, válida por 24 horas. Depois disso, gere um novo link em [Termo de Cessão do Lote](/documentation/iaas/negociacao_recebiveis/assignment/documento_da_cessao). |
```json title="Webhook Body"
{
"data": {
"assignment_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
"assignment_new_status": "pending_manager_approval",
"assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef",
"fund_class_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c"
},
"webhook_type": "trade_receivables.assignment_status_change",
"webhook_datetime": "2024-04-23T15:08:30Z"
}
```
## Eventos por status
O corpo é sempre o mesmo; muda o `assignment_new_status`.
| `assignment_new_status` | Quando é enviado |
|---|---|
| `pending_assets_insertion` | Lote criado e pronto para receber ativos. Também quando um lote é reaberto. |
| `completed_assets_insertion` | Inserção de ativos encerrada. Também quando o lote volta do registro com ativos recusados pela registradora. Não é enviado para lote com `assignment_date` futura: ele passa por `waiting_assignment_date` e entra em `completed_assets_insertion` na data da cessão, sem webhook. |
| `pending_eligibility` | Todos os ativos foram analisados e o lote entrou na análise de elegibilidade. |
| `pending_consultant_approval` | Lote aprovado na elegibilidade, aguardando a [aprovação](/documentation/iaas/negociacao_recebiveis/assignment/aprovacao) da consultoria. |
| `pending_manager_approval` | Lote aprovado na elegibilidade (e pela consultoria, quando aplicável), aguardando a [aprovação](/documentation/iaas/negociacao_recebiveis/assignment/aprovacao) da gestora. |
| `pending_assets_registry` | Lote aprovado automaticamente, com ativos sendo registrados. |
| `waiting_assets_to_formalize` | Ativos registrados (ou lote aprovado automaticamente sem registro), aguardando formalização. |
| `pending_assignment_term` | Termo de Cessão sendo gerado. |
| `pending_assignment_term_signature` | Termo de Cessão enviado para assinatura. A partir daqui o termo pode ser baixado em [Termo de Cessão do Lote](/documentation/iaas/negociacao_recebiveis/assignment/documento_da_cessao). |
| `pending_custody` | Aguardando custódia, conforme a configuração de cessão. Enviado só quando a configuração dispensa a assinatura do termo; depois da assinatura, a passagem para `pending_custody` não gera webhook. |
| `pending_payment` | Termo assinado (ou dispensado) e pagamento ao cedente em processamento. Pode trazer `signed_term_url`. |
| `pending_assets_wallet_inclusion` | Pagamento confirmado; ativos sendo encarteirados. |
| `waiting_after_assignment_registry` | Registro pós-cessão (registro diferido) enviado à registradora. |
| `completed` | Ativos encarteirados na carteira do fundo — cessão concluída. Em configurações com registro diferido, é enviado no encarteiramento, antes do registro pós-cessão. |
| `denied` | Lote reprovado: na elegibilidade, por todos os ativos terem sido reprovados, no registro, ou pela consultoria/gestora. Não volta para a esteira pela API. |
| `discarded` | Lote descartado — por exemplo, no fechamento contábil do fundo, quando ainda não tinha sido pago. Lotes `denied` também são descartados nesse momento. |
:::caution Transições sem webhook
- A aprovação final feita pela API ou pelo portal (que leva o lote para `pending_assets_registry` ou `waiting_assets_to_formalize`) **não** gera webhook nessa transição. Use o `status` da resposta da [aprovação](/documentation/iaas/negociacao_recebiveis/assignment/aprovacao).
- `waiting_assignment_date`, `pending_send_to_signature`, `pending_assignment_term_validation` e `pending_after_assignment_documentation` não geram webhook.
- A passagem para `pending_custody` depois da assinatura do Termo de Cessão.
Para conferir o status a qualquer momento, use a [Recuperação do Lote](/documentation/iaas/negociacao_recebiveis/assignment/recuperacao).
:::
---
# Fluxo de Cessão
URL: /documentation/iaas/negociacao_recebiveis/fluxo_cessao
Esta página oferece uma visão holística de todo o fluxo de cessão de direitos creditórios, desde a criação do lote até o encarteiramento dos ativos na carteira do fundo. Acompanhe a evolução dos **status do lote**, dos **status dos ativos** e dos **webhooks** recebidos em cada etapa.
:::tip Como usar este fluxograma
Passe o mouse sobre cada etapa para ver os detalhes do endpoint e acessar a documentação completa. As três trilhas coloridas mostram simultaneamente o que acontece com o lote, com os ativos e quais webhooks você pode receber — só chegam os status assinados na sua configuração de webhook.
:::
{`
.cf-legend{display:flex;flex-wrap:wrap;gap:8px;margin-bottom:24px}
.cf-legend-item{display:flex;align-items:center;gap:6px;font-size:0.8rem;font-weight:600}
.cf-legend-dot{width:12px;height:12px;border-radius:3px}
.cf-step{position:relative;margin-bottom:4px}
.cf-step:not(:last-child)::after{content:'';display:block;width:2px;height:16px;margin:0 auto;background:var(--ifm-color-emphasis-300)}
.cf-card{border:1.5px solid var(--ifm-color-emphasis-200);border-radius:10px;padding:16px 20px;transition:box-shadow 0.2s,border-color 0.2s;cursor:pointer;background:var(--ifm-background-surface-color,var(--ifm-background-color))}
.cf-card:hover{box-shadow:0 4px 16px rgba(0,0,0,0.08);border-color:var(--ifm-color-primary)}
.cf-card-header{display:flex;align-items:center;gap:10px;flex-wrap:wrap}
.cf-num{width:28px;height:28px;border-radius:50%;display:flex;align-items:center;justify-content:center;font-size:0.8rem;font-weight:800;color:#fff;flex-shrink:0}
.cf-num-int{background:#3b82f6}
.cf-num-qi{background:#8b5cf6}
.cf-num-ges{background:#d946ef}
.cf-title{font-size:1rem;font-weight:700;color:var(--ifm-font-color-base)}
.cf-actor{font-size:0.7rem;font-weight:700;padding:2px 8px;border-radius:12px;margin-left:auto}
.cf-actor-int{background:rgba(59,130,246,0.12);color:#2563eb}
.cf-actor-qi{background:rgba(139,92,246,0.12);color:#7c3aed}
.cf-actor-ges{background:rgba(217,70,239,0.12);color:#c026d3}
.cf-subtitle{font-size:0.82rem;color:var(--ifm-color-emphasis-700);margin-top:4px;margin-left:38px}
.cf-tracks{display:flex;flex-wrap:wrap;gap:8px;margin-top:12px;margin-left:38px}
.cf-track{display:inline-flex;align-items:center;gap:5px;padding:3px 10px;border-radius:6px;font-size:0.75rem;font-family:var(--ifm-font-family-monospace);border:1px solid}
.cf-track-lote{background:rgba(34,197,94,0.1);color:#16a34a;border-color:rgba(34,197,94,0.25)}
.cf-track-ativo{background:rgba(59,130,246,0.1);color:#2563eb;border-color:rgba(59,130,246,0.25)}
.cf-track-wh{background:rgba(245,158,11,0.1);color:#b45309;border-color:rgba(245,158,11,0.25)}
.cf-track-err{background:rgba(239,68,68,0.1);color:#dc2626;border-color:rgba(239,68,68,0.25)}
.cf-track-label{font-family:var(--ifm-font-family-base);font-weight:700;font-size:0.7rem;text-transform:uppercase;letter-spacing:0.03em}
.cf-new{font-weight:700}
.cf-unchanged{opacity:0.5}
.cf-details{max-height:0;overflow:hidden;opacity:0;transition:max-height 0.35s ease,opacity 0.25s ease,margin 0.3s ease;margin-left:38px}
.cf-card:hover .cf-details{max-height:300px;opacity:1;margin-top:14px;padding-top:12px;border-top:1px solid var(--ifm-color-emphasis-200)}
.cf-endpoint{font-family:var(--ifm-font-family-monospace);font-size:0.82rem;padding:8px 12px;border-radius:6px;background:var(--ifm-color-emphasis-100);margin-bottom:8px;display:flex;align-items:center;gap:8px;flex-wrap:wrap}
.cf-method{font-weight:800;padding:2px 6px;border-radius:4px;font-size:0.72rem}
.cf-method-post{background:#f97316;color:#fff}
.cf-method-put{background:#3b82f6;color:#fff}
.cf-method-get{background:#22c55e;color:#fff}
.cf-desc{font-size:0.82rem;color:var(--ifm-color-emphasis-700);margin-bottom:8px}
.cf-link{font-size:0.82rem;font-weight:600;color:var(--ifm-color-primary);text-decoration:none}
.cf-link:hover{text-decoration:underline}
.cf-branch{margin-top:12px;margin-left:38px;display:flex;gap:12px;flex-wrap:wrap}
.cf-branch-path{flex:1;min-width:200px;border-radius:8px;padding:10px 14px;border:1.5px dashed}
.cf-branch-ok{border-color:rgba(34,197,94,0.4);background:rgba(34,197,94,0.05)}
.cf-branch-err{border-color:rgba(239,68,68,0.4);background:rgba(239,68,68,0.05)}
.cf-branch-label{font-size:0.78rem;font-weight:700;margin-bottom:4px}
.cf-branch-label-ok{color:#16a34a}
.cf-branch-label-err{color:#dc2626}
html[data-theme='dark'] .cf-track-lote{background:rgba(34,197,94,0.15);color:#4ade80;border-color:rgba(34,197,94,0.3)}
html[data-theme='dark'] .cf-track-ativo{background:rgba(59,130,246,0.15);color:#60a5fa;border-color:rgba(59,130,246,0.3)}
html[data-theme='dark'] .cf-track-wh{background:rgba(245,158,11,0.15);color:#fbbf24;border-color:rgba(245,158,11,0.3)}
html[data-theme='dark'] .cf-track-err{background:rgba(239,68,68,0.15);color:#f87171;border-color:rgba(239,68,68,0.3)}
html[data-theme='dark'] .cf-branch-ok{background:rgba(34,197,94,0.08)}
html[data-theme='dark'] .cf-branch-err{background:rgba(239,68,68,0.08)}
html[data-theme='dark'] .cf-actor-int{background:rgba(59,130,246,0.2);color:#60a5fa}
html[data-theme='dark'] .cf-actor-qi{background:rgba(139,92,246,0.2);color:#a78bfa}
html[data-theme='dark'] .cf-actor-ges{background:rgba(217,70,239,0.2);color:#e879f9}
`}
## Legenda
Agente Integrador
QI Tech (automático)
Consultoria / Gestora
Status do Lote
Status do Ativo
Webhook
## Fluxograma
1
Criação do Lote
Agente Integrador
Cria um lote de cessão com um identificador único ( external_id ).
Lote: pending_assets_insertion
POST /trade_receivables/fund_class/{fund_class_key}/assignment_configuration/{assignment_configuration_key}/assignment
O lote é criado em status pending_assets_insertion , pronto para receber ativos.
Ver documentação completa →
2
Inserção dos Ativos
Agente Integrador
Insere os ativos no lote (CCB, duplicata, contrato descontado ou contrato parcelado). Repita para cada ativo.
Lote: pending_assets_insertion
Ativo: pending_eligibility
Webhook: asset_creation
POST /trade_receivables/.../assignment/{assignment_external_id}/asset
Cada ativo é criado com status pending_eligibility . Você receberá um webhook trade_receivables.asset_creation confirmando a inserção.
CCB →
Duplicata →
Contrato Descontado →
Contrato Parcelado →
3
Envio do Lastro
Agente Integrador
Envia o lastro de cada ativo: os documentos que o comprovam (PDF, P7S ou XML em Base64). Duplicatas mercantis não exigem documentos. Não é aqui que entra o Termo de Cessão (etapa 7).
Lote: pending_assets_insertion
Ativo: pending_eligibility
POST /trade_receivables/.../asset/{asset_external_id}/document
Os documentos podem ser enviados logo após a inserção do ativo ou depois do webhook pending_documentation (etapa 5a).
Ver documentação completa →
4
Encerrar Inserção
Agente Integrador
Sinaliza que todos os ativos foram inseridos no lote. A análise de elegibilidade será iniciada automaticamente.
Lote: completed_assets_insertion
Ativo: pending_eligibility
PUT /trade_receivables/.../assignment/{assignment_external_id}
Envie {"assignment_status": "completed_assets_insertion"} . Não é necessário aguardar os webhooks de elegibilidade individual dos ativos.
Ver documentação completa →
5a
Elegibilidade dos Ativos
QI Tech
A QI Tech analisa cada ativo individualmente. Você recebe um webhook por ativo com o resultado.
Lote: completed_assets_insertion
Ativo: pending_documentation / pre_approved / denied
Webhook: asset_status_change
Ativo aprovado
pre_approved
O ativo foi aprovado na elegibilidade; se o produto exige documentos, passa por pending_documentation antes.
Ativo reprovado
denied
O ativo não segue adiante no fluxo.
Webhook trade_receivables.asset_status_change — enviado para cada ativo com o resultado da elegibilidade.
Ver documentação de webhooks do ativo →
5b
Elegibilidade do Lote
QI Tech
Quando todos os ativos forem analisados, a QI Tech avalia a elegibilidade do lote como um todo.
Lote: pending_consultant_approval / pending_manager_approval / denied
Webhook: assignment_status_change
Lote elegível
pending_manager_approval
O lote aguarda a aprovação da consultoria e/ou da gestora (passo 6). Se a configuração prevê aprovação automática, segue direto para o registro e a formalização dos ativos.
Lote reprovado
denied
O lote foi reprovado pelas regras de elegibilidade do fundo, ou todos os ativos foram reprovados. Fluxo encerrado.
Webhook trade_receivables.assignment_status_change — informa se o lote foi aprovado ou reprovado na elegibilidade.
Ver documentação de webhooks do lote →
6
Aprovação da Consultoria e/ou da Gestora
Consultoria / Gestora
Quando a configuração exige aprovação manual, a consultoria e/ou a gestora aprovam ou reprovam o lote (via API ou pelo portal). Aprovado, o lote segue para o registro e a formalização dos ativos e, depois, para o Termo de Cessão.
Lote: pending_assets_registry / waiting_assets_to_formalize
PUT /trade_receivables/.../assignment/{assignment_external_id}
Envie {"assignment_status": "approved"} ou "denied" . A aprovação final não gera webhook: use o status da resposta. O próximo webhook do lote chega com o Termo de Cessão ( pending_assignment_term_signature ).
Ver documentação completa →
7
Termo de Cessão do Lote
QI Tech
A QI Tech gera o Termo de Cessão do lote e o encaminha para assinatura. Todas as partes relacionadas precisam assinar o termo para que o fluxo prossiga. O integrador não envia o termo: só o consulta, a partir de pending_assignment_term_signature .
Lote: pending_payment
Webhook: assignment_status_change
GET /trade_receivables/.../assignment/{assignment_external_id}/assignment_term_link
GET /trade_receivables/fund_class/{fund_class_key}/assignment_terms
Consulte o Termo de Cessão (original e assinado) de um lote ou liste os termos da classe de fundo por data. Após todas as partes assinarem, você recebe o webhook com status pending_payment .
Ver documentação completa →
8
Pagamento ao Cedente
QI Tech
O pagamento é feito automaticamente ao cedente na conta de desembolso definida para o lote.
Lote: pending_assets_wallet_inclusion
Webhook: assignment_status_change
O valor total é a soma dos total_purchase_value dos ativos não reprovados; em lotes de substituição, descontado o valor dos ativos recomprados. Após o pagamento, você recebe o webhook com status pending_assets_wallet_inclusion .
9
Encarteiramento
QI Tech
Os ativos são incluídos na carteira do fundo. A cessão está concluída.
Lote: completed
Ativo: completed
Webhook: assignment_status_change
Você recebe o webhook final com status completed . A partir desse momento, os ativos se encontram na carteira do fundo.
Ver documentação de webhooks →
---
## Resumo de webhooks
A tabela abaixo consolida todos os webhooks que o integrador recebe ao longo do fluxo, na ordem cronológica:
| # | Tipo do webhook | Status | Momento no fluxo | Ação esperada |
|---|---|---|---|---|
| 1 | `asset_creation` | `pending_eligibility` | Após inserção de cada ativo (passo 2) | Nenhuma — confirmação de recebimento. |
| 2 | `asset_status_change` | `pending_documentation` / `pre_approved` | Ativo aprovado na elegibilidade (passo 5a) | Se `pending_documentation`, [enviar o lastro](/documentation/iaas/negociacao_recebiveis/asset/documents) que falta. |
| 3 | `asset_status_change` | `denied` | Ativo reprovado na elegibilidade (passo 5a) | Nenhuma — ativo não segue adiante. |
| 4 | `assignment_status_change` | `pending_consultant_approval` / `pending_manager_approval` | Lote aprovado na elegibilidade (passo 5b) | [Aprovar ou reprovar](/documentation/iaas/negociacao_recebiveis/assignment/aprovacao), se você é a consultoria ou a gestora. |
| 5 | `assignment_status_change` | `denied` | Lote reprovado na elegibilidade (passo 5b) | Nenhuma — fluxo encerrado. |
| 6 | `assignment_status_change` | `pending_assignment_term_signature` | Termo de Cessão enviado para assinatura (passo 7) | Opcional: [baixar o Termo de Cessão do lote](/documentation/iaas/negociacao_recebiveis/assignment/documento_da_cessao). |
| 7 | `assignment_status_change` | `pending_payment` | Termo assinado por todas as partes (passo 7) | Nenhuma — pagamento em processamento. |
| 8 | `assignment_status_change` | `pending_assets_wallet_inclusion` | Pagamento realizado (passo 8) | Nenhuma — encarteiramento em processamento. |
| 9 | `assignment_status_change` | `completed` | Ativos encarteirados (passo 9) | Cessão concluída com sucesso. |
| — | `assignment_status_change` | `discarded` | Fechamento contábil do fundo, para lotes ainda não pagos ou reprovados | Nenhuma — lote descartado. |
:::info Prefixo dos webhooks
Todos os tipos de webhook possuem o prefixo `trade_receivables.`. Por exemplo: `trade_receivables.asset_creation` e `trade_receivables.assignment_status_change`. Para detalhes sobre a estrutura completa dos webhooks, consulte [Webhooks do Ativo](/documentation/iaas/negociacao_recebiveis/asset/webhooks) e [Webhooks do Lote](/documentation/iaas/negociacao_recebiveis/assignment/webhooks). Lá também estão os status intermediários que não aparecem nesta tabela.
:::
---
# Cessão de Direitos Creditórios
URL: /documentation/iaas/negociacao_recebiveis/inicio
Esta seção documenta as APIs que viabilizam o processo de cessão de Direitos Creditórios para Fundos de Investimento administrados pela QI DTVM. O fluxo abrange desde a criação do lote de cessão até o encarteiramento dos ativos na carteira do fundo.
:::tip Manual completo
Para um entendimento aprofundado das regras de negócio e do produto, consulte o [Manual de Cessão de Direitos Creditórios](/documentation/iaas/negociacao_recebiveis/manual_api). Recomendamos a leitura em conjunto com as rotas aqui disponibilizadas.
:::
:::info Pré-requisitos
- Para ter acesso a esses serviços, entre em contato com [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br) para liberação dos ambientes de sandbox e produção.
- Você precisará da `fund_class_key` (chave do fundo) e da `assignment_configuration_key` (chave da configuração de cessão), obtidas na [Homologação de Cedente](/documentation/iaas/homologacao_cedente/contrato_de_cessao/pedido_de_contrato).
- Para consultar as configurações de cessão disponíveis, utilize o endpoint de [Listagem de Configurações de Cessão](/documentation/iaas/negociacao_recebiveis/listagem).
:::
## Como enviar a cessão
Existem dois caminhos, com o mesmo resultado final. Escolha um por lote — não é possível misturar os dois no mesmo lote.
| Caminho | Como funciona | Onde |
|---|---|---|
| **Pela API, ativo a ativo** | Criação do lote, uma requisição por ativo e encerramento da inserção. É o fluxo detalhado nesta seção | API de integração |
| **Por arquivo** | Um único arquivo com todos os ativos do lote: **CNAB 444** para duplicatas, CT-e, cheques e notas promissórias, ou **CSV** para CCB, honorários advocatícios e contratos parcelados | Portal do gestor/consultor; API da gestora |
:::tip Cessão de duplicatas por arquivo
Para duplicatas o formato é o **CNAB 444**; o CSV é aceito para operações de crédito (CCB), honorários advocatícios e contratos parcelados. Veja [Cessão por Arquivo](/documentation/iaas/negociacao_recebiveis/arquivo/inicio), o [Layout CNAB 444 — Cessão](/documentation/iaas/negociacao_recebiveis/arquivo/cnab444) e o [Layout CSV — Contratos Parcelados](/documentation/iaas/negociacao_recebiveis/arquivo/csv_contrato_parcelado), com exemplos prontos para download.
:::
## Fluxo de cessão
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.
:::tip Fluxo completo
Para todas as transições de status, os payloads dos webhooks e os caminhos de exceção, consulte o [Fluxo de cessão](/documentation/iaas/negociacao_recebiveis/fluxo_cessao).
:::
## Passo a passo
### 1. Criação do Lote
Crie um lote de cessão informando um identificador único (`external_id`). O lote será o contêiner para todos os ativos que serão cedidos ao fundo.
**[Acessar documentação da criação do lote](/documentation/iaas/negociacao_recebiveis/assignment/criacao)**
### 2. Inserção dos Ativos
Adicione os ativos (CCBs, duplicatas, contratos parcelados, etc.) ao lote criado. Cada ativo deve ser inserido individualmente com suas informações de operação, parcelas e dados do sacado.
Não sabe qual tipo enviar? Em [Qual ativo enviar](/documentation/iaas/negociacao_recebiveis/asset/qual_ativo_enviar) você encontra o tipo de cada recebível e o que muda entre eles depois da cessão, inclusive a diferença entre contrato descontado e contrato parcelado.
**[Acessar documentação da inserção de ativos](/documentation/iaas/negociacao_recebiveis/asset/qual_ativo_enviar)**
### 3. Envio do Lastro
Para cada ativo inserido, envie o lastro exigido pelo produto: os documentos que comprovam o ativo (CCB, contrato, nota fiscal etc.). O ativo só prossegue na esteira após todos os documentos exigidos serem enviados. Não confunda com o Termo de Cessão, que é do lote e gerado pela QI Tech no passo 6.
**[Acessar documentação do envio do lastro](/documentation/iaas/negociacao_recebiveis/asset/documents)**
### 4. Encerramento da Inserção
Sinalize que todos os ativos foram inseridos no lote. O sistema aguardará a análise individual de cada ativo antes de prosseguir com a elegibilidade do lote como um todo.
**[Acessar documentação do encerramento](/documentation/iaas/negociacao_recebiveis/assignment/fechamento)**
### 5. Aprovação
Após a elegibilidade do lote ser aprovada, o lote segue para aprovação. A depender da configuração de cessão, essa etapa é **manual** — o consultor e/ou o gestor do fundo analisam e aprovam ou reprovam o lote, e o lote fica em `pending_consultant_approval` / `pending_manager_approval` até a decisão — ou **automática**, sem nenhuma ação do integrador. Se aprovado, o Termo de Cessão será gerado automaticamente.
**[Acessar documentação da aprovação](/documentation/iaas/negociacao_recebiveis/assignment/aprovacao)**
### 6. Assinatura, Pagamento e Encarteiramento
Os passos finais são automatizados: o Termo de Cessão é assinado pelas partes, o pagamento é realizado ao cedente e os ativos são encarteirados na carteira do fundo. Acompanhe o progresso através dos [webhooks do lote](/documentation/iaas/negociacao_recebiveis/assignment/webhooks). Para baixar o termo, original ou assinado, ou abrir o link de assinatura, veja [Termo de Cessão do Lote](/documentation/iaas/negociacao_recebiveis/assignment/documento_da_cessao).
## Lotes de substituição
O fluxo de substituição segue as mesmas etapas do fluxo de cessão, com um passo a mais: inserir, no mesmo lote, os ativos que serão **recomprados** pelo cedente — [Inserção de Ativo para Recompra](/documentation/iaas/negociacao_recebiveis/asset/criacao_repurchased_asset). Recompras e novos ativos podem entrar em qualquer ordem enquanto o lote estiver aberto; para encerrar a inserção, o lote precisa de ao menos um ativo de recompra, e o valor dos novos ativos não pode ser menor que o dos recomprados.
---
# Listagem de Configurações de Cessão
URL: /documentation/iaas/negociacao_recebiveis/listagem
Endpoint de consulta paginada que retorna as configurações de cessão de uma classe de fundo. Cada configuração representa o acordo entre o fundo cessionário e um cedente: tipo de ativo aceito, regras de registro, aprovação, pagamento e documentos exigidos. A `assignment_configuration_key` de cada configuração compõe o caminho dos endpoints de cessão.
:::info Disponível em
| Perfil | Host | Permissão exigida |
| ----------- | ---------------- | --------------------------------------------------- |
| Gestora | `manager-api` | Leitura |
| Consultoria | `consultant-api` | Ler Cessões |
URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts).
:::
## Request
ENDPOINT /trade_receivables/fund_class/{fund_class_key}/assignment_configurations
MÉTODO GET
### Path params
| Parâmetro | Tipo | Descrição |
|---|---|---|
| `fund_class_key` | string | Chave única do fundo (UUID). |
### Query params
Todos os filtros são opcionais e podem ser combinados.
| Parâmetro | Tipo | Descrição |
|---|---|---|
| `assignment_contract_key` | string | Chave do contrato de cessão que originou a configuração (UUID). |
| `asset_type` | string | Tipo de ativo aceito (ex.: `ccb`, `duplicata_mercantil`, `duplicata_servicos`). |
| `assignor_document_number` | string | CPF/CNPJ do cedente, **com pontuação** (ex.: `11.222.333/0001-81` ou `969.698.790-03`). |
| `assignment_configuration_type` | string | `default_configuration` (cessão) ou `repurchase_configuration` (substituição com recompra). |
| `has_assignor_coobligation` | boolean | Configurações com ou sem coobrigação do cedente. |
| `has_bankslip` | boolean | Configurações com ou sem cobrança por boleto. |
| `page` | integer | Número da página (começa em 0). Padrão: `0`. |
| `limit` | integer | Registros por página. Padrão: `25`. Máximo: `155`. |
```text title="Exemplo de chamada"
GET /trade_receivables/fund_class/{fund_class_key}/assignment_configurations?asset_type=ccb&assignor_document_number=11.222.333/0001-81&page=0&limit=10
```
## Response
STATUS 200
**Response Body**
```json title="Response Body"
{
"data": [
{
"assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef",
"validation_configuration_key": "5f0e3a4c-2b7d-4c1e-9a8f-0d6b1c2e3f40",
"assignment_configuration_name": "Config CCB Fundo Alpha",
"assignment_contract_key": "8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
"registry_type": "internal_registry",
"asset_type": "ccb",
"fund_class": {
"fund_class_key": "f1a2b3c4-d5e6-4890-abcd-ef1234567890",
"name": "Fundo Alpha FIDC",
"document_number": "11.222.333/0001-81",
"accounting_date": "2024-04-01",
"manager": {
"manager_key": "e1f2a3b4-c5d6-4890-abcd-ef1234567890",
"document_number": "22.222.222/0001-91",
"manager_name": "Gestora Exemplo S.A."
}
},
"assignor": {
"assignor_key": "c1d2e3f4-a5b6-4890-abcd-ef1234567890",
"document_number": "33.333.333/0001-91",
"name": "Cedente Exemplo Ltda"
},
"assignment_reports": {
"send_reports": false
},
"assignment_configuration_type": "default_configuration",
"status": "active",
"consultant_decision_type": "manual_approval",
"manager_decision_type": "manual_approval",
"asset_fees": null,
"payment_type": "pix",
"custody_type": "internal",
"required_documents": ["ccb"],
"after_assignment_required_documents": [],
"certifier": "certifiqi",
"disbursement_account_policy": "all_assignor_accounts",
"consultant": {
"consultant_key": "a7b8c9d0-e1f2-4a3b-8c4d-5e6f7a8b9c0d",
"document_number": "44.444.444/0001-91",
"name": "Consultoria Exemplo Ltda"
},
"operation_type": "unsecured_credit",
"originator_bonds": [
{
"originator": {
"originator_key": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
"document_number": "33.333.333/0001-91",
"name": "Cedente Exemplo Ltda"
}
}
]
}
],
"limit": 10,
"page": 0,
"is_last_page": true
}
```
### Atributos da resposta
| Campo | Tipo | Descrição |
|---|---|---|
| `data` | array | Configurações de cessão encontradas. Veja tabela abaixo. |
| `page` | integer | Número da página atual. |
| `limit` | integer | Registros por página. |
| `is_last_page` | boolean | `true` na última página de resultados. |
#### Atributos de cada configuração (objetos dentro de `data`)
O mesmo objeto aparece em `assignment_configuration` na [Recuperação do Lote](/documentation/iaas/negociacao_recebiveis/assignment/recuperacao).
| Campo | Tipo | Descrição |
|---|---|---|
| `assignment_configuration_key` | string | Identificador único da configuração de cessão (UUID). |
| `assignment_configuration_name` | string | Nome da configuração. |
| `assignment_contract_key` | string | Contrato de cessão que originou a configuração (UUID). |
| `validation_configuration_key` | string \| null | Configuração de validação de documentos (UUID). |
| `status` | string | `created`, `active`, `inactive` ou `blocked`. Só configurações `active` aceitam novos lotes. |
| `asset_type` | string | Tipo de ativo aceito. Um lote só recebe ativos desse tipo. |
| `assignment_configuration_type` | string | `default_configuration` (cessão) ou `repurchase_configuration` (substituição com recompra). |
| `operation_type` | string | Tipo de operação (ex.: `unsecured_credit`, `fgts`, `duplicata_mercantil`). Ausente quando não definido. |
| `registry_type` | string | Registro dos ativos: `internal_registry`, `external_registry`, `registry_transfer`, `deferred_registry`, `unfit` ou `skip_registry` (sem registro). |
| `consultant_decision_type` | string | Aprovação da consultoria: `manual_approval`, `automatic_approval` ou `not_applicable`. |
| `manager_decision_type` | string | Aprovação da gestora: `manual_approval` ou `automatic_approval`. |
| `payment_type` | string | Forma de pagamento ao cedente: `pix` ou `wire_transfer`. |
| `custody_type` | string | Custódia: `internal`, `cetip`, `skip_custody` ou `wait_custody_approval`. |
| `certifier` | string | Certificadora da assinatura do Termo de Cessão: `certifiqi`, `qi_sign`, `id_trust` ou `qcertifica`. |
| `disbursement_account_policy` | string \| null | Escolha da conta de desembolso: `all_assignor_accounts` (qualquer conta do cedente), `locked_on_assignment_contract` (conta fixada no contrato) ou `locked_on_assignment_term`. |
| `disbursement_account_key` | string | Conta de desembolso fixada no contrato. Presente só quando há conta fixada. |
| `required_documents` | array | Tipos de documento exigidos **antes** da cessão, enviados pelo [Envio do Lastro do Ativo](/documentation/iaas/negociacao_recebiveis/asset/documents) enquanto o ativo está em `pending_documentation`. Lista vazia quando o produto não exige nenhum. |
| `after_assignment_required_documents` | array | Tipos de documento exigidos **depois** da cessão, enviados pelo mesmo endpoint enquanto o ativo está em `pending_after_assignment_documentation`. Lista vazia quando o produto não exige nenhum. |
| `asset_fees` | object \| null | Taxas dos ativos, quando configuradas. |
| `assignment_reports` | object | Envio de relatórios da cessão. |
| `assignor_discounts_configuration` | object | Presente só quando a configuração permite [descontos ao cedente](/documentation/iaas/negociacao_recebiveis/assignment/criacao). |
| `collection_configuration` | object | Configuração de cobrança, quando houver. |
| `fund_class` | object | Fundo cessionário: `fund_class_key`, `name`, `document_number` (CNPJ), `accounting_date` (data contábil vigente) e `manager` (`manager_key`, `document_number`, `manager_name`). |
| `assignor` | object | Cedente: `assignor_key`, `document_number` e `name`. |
| `consultant` | object | Consultoria vinculada: `consultant_key`, `document_number` e `name`. Ausente quando não há consultoria. |
| `originator_bonds` | array | Originadores vinculados, cada um em `originator` (`originator_key`, `document_number`, `name`). |
## Erros
| Status | Código | Quando acontece |
|---|---|---|
| 400 | — | `limit` acima de 155 ou `page` negativo (validação de parâmetro). |
Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros).