# 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
24 página(s).

Índice:
- Layout CNAB 444 — Cessão (/documentation/iaas/negociacao_recebiveis/arquivo/cnab444)
- Layout CSV — Contratos Parcelados (/documentation/iaas/negociacao_recebiveis/arquivo/csv_contrato_parcelado)
- 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)
- Inserção de Documentos do Ativo (/documentation/iaas/negociacao_recebiveis/asset/documents)
- 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 Gestor (/documentation/iaas/negociacao_recebiveis/assignment/aprovacao)
- Criação do Lote de Cessão (/documentation/iaas/negociacao_recebiveis/assignment/criacao)
- Documentos da Cessão (/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)
- 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 444 — Cessão

URL: /documentation/iaas/negociacao_recebiveis/arquivo/cnab444

Layout do arquivo de **remessa de cessão** aceito pela QI CTVM. É 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. 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 CTVM 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 CTVM, 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](#ocorrências-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. **Três 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) |

:::caution Outros códigos passam na estrutura, mas não são processados
O layout CNAB 444 prevê dezenas de espécies — `02` nota promissória, `41` CCB digital, `51` cheque, `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).

| 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 CTVM. É 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. 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,Jove de Souza,593.607.530-33,1,2026-12-25,500.46
contract,CONTRATO_0001,1144927986/XXX,900.00,pre_fixed,Jove de Souza,593.607.530-33,2,2027-01-25,500.46
contract,CONTRATO_0002,2244927986/XXX,450.00,post_fixed,Empresa Souza LTDA,53.020.654/0001-43,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

---

# 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. 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 é um fluxo de tela
O envio de arquivo de cessão é feito **pelo portal**, não pela API de integração. Pela API, a cessão é feita pelo fluxo de [criação de lote + inserção de ativos](/documentation/iaas/negociacao_recebiveis/fluxo_cessao), ativo a ativo, sem arquivo.
:::

| | 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, contratos, CTe) e CSV (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 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 | Modelo |
|---|---|---|---|
| `duplicata_mercantil` | **CNAB 444**, espécie `01` | `.rem` · `.txt` | [Exemplo](/downloads/modelos_arquivo/exemplo_cessao_duplicata_mercantil_cnab444.rem) |
| `duplicata_servicos` | **CNAB 444**, espécie `14` | `.rem` · `.txt` | [Exemplo](/downloads/modelos_arquivo/exemplo_cessao_duplicata_servicos_cnab444.rem) |
| `cte` | **CNAB 444**, espécie `53` | `.rem` · `.txt` | [Exemplo](/downloads/modelos_arquivo/exemplo_cessao_cte_cnab444.rem) |
| `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) | **CSV** | `.csv` | [Modelo](/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
O CSV é aceito apenas para `ccb`, `structured_cci`, `legal_fees` e `contract`. Para **cessão de duplicatas e CT-e o formato é 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). O layout do CSV de contratos parcelados está em [Layout CSV — Contratos Parcelados](/documentation/iaas/negociacao_recebiveis/arquivo/csv_contrato_parcelado).

Demais tipos de ativo, como `discounted_contract`, são cedidos **pela API**, ativo a ativo — não há formato de arquivo para eles hoje.
:::

## Fluxo do envio

<FlowDiagram
  columns={3}
  labels={{ manager: 'Você, no portal' }}
  nodes={[
    { id: 'formulario', row: 1, col: 2, actor: 'manager', num: 1,
      title: 'Dados do lote',
      desc: 'Cedente, configuração de cessão, substituição e meio de pagamento ao cedente.' },

    { id: 'upload', row: 2, col: 2, actor: 'manager', num: 2,
      title: 'Upload do arquivo',
      desc: 'Arraste o arquivo .rem, .txt ou .csv para a área de upload e confirme o envio.' },

    { id: 'validacao', row: 3, col: 2, actor: 'qitech',
      title: 'Validação do arquivo',
      desc: 'Estrutura, posições, domínios e documentos são conferidos linha a linha.' },

    { id: 'descartado', row: 4, col: 1, actor: 'qitech', tone: 'end',
      title: 'Arquivo recusado',
      desc: 'Uma única linha inválida recusa o arquivo inteiro. O portal exibe as linhas e os motivos.' },

    { id: 'lote', row: 4, col: 2, actor: 'qitech', tone: 'ok',
      title: 'Lote criado com os ativos',
      desc: 'Cada linha vira um ativo e o lote entra no fluxo padrão de cessão.',
      href: '/documentation/iaas/negociacao_recebiveis/inicio' },

    { id: 'esteira', row: 5, col: 2, actor: 'qitech',
      title: 'Elegibilidade, aprovação, termo e pagamento',
      desc: 'A partir daqui o fluxo é idêntico ao da cessão via API.',
      href: '/documentation/iaas/negociacao_recebiveis/fluxo_cessao' },
  ]}
  edges={[
    { from: 'formulario', to: 'upload' },
    { from: 'upload', to: 'validacao' },
    { from: 'validacao', to: 'descartado', label: 'linha inválida', tone: 'end' },
    { from: 'validacao', to: 'lote', label: 'arquivo válido', tone: 'ok' },
    { from: 'lote', to: 'esteira' },
  ]}
/>

## 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. 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 CTVM 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.

:::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 os [documentos](/documentation/iaas/negociacao_recebiveis/asset/documents) exigidos e [encerre a inserção](/documentation/iaas/negociacao_recebiveis/assignment/fechamento).
:::

:::caution Atenção
O campo `external_id` da operação de crédito deve ser único para cada ativo 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": "QI CTVM",
        "document_number": "19.845.976/0001-93",
        "person_type": "legal_person",
        "email": "qidtvm@qitech.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": "75.723.105/0001-78",
      "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": "11.620.231/3105-71"
      },
      "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. Informação apenas para visualização posterior — não é utilizada em cálculos. |
| `credit_operation` | object | obrigatório | Dados da operação de crédito. Veja [Atributos de `credit_operation`](#atributos-de-credit_operation). |

#### Atributos de `premiums`

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `premium_type` | string | obrigatório | Tipo do ágio. |
| `total_value` | number | obrigatório | Valor total do ágio. Até 2 casas decimais. |

**Enumeradores de `premium_type`:**

| Valor | Descrição |
|---|---|
| `spread` | Spread vinculado à originação e emissão do crédito. |

#### 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 do originador/consultor que viabilizou a operação. |
| `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 | obrigatório | Dados do cálculo da parte pré-fixada. Veja [Atributos de `pre_fixed`](#atributos-de-pre_fixed). |
| `installments` | array | obrigatório | Lista de parcelas da operação. Veja [Atributos de `installments`](#atributos-de-installments). |
| `delay` | object | opcional | 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. |
| `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. |

**Enumeradores de `interest_rate_type`:**

| Valor | Descrição |
|---|---|
| `pre_fixed` | Para operações pré-fixadas. |
| `post_fixed` | Para operações pós-fixadas. |

#### 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 | obrigatório | 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, 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 | obrigatório | 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. |
| `postal_code` | string | obrigatório | CEP. 9 caracteres (com hífen). |
| `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. Até 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. |
| `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 | obrigatório | Código de atividade 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 | opcional | E-mail do representante. Máximo de 255 caracteres. |
| `phone` | object | opcional | Telefone. Mesma estrutura de [Atributos de `phone`](#atributos-de-phone). |
| `address` | object | opcional | Endereço. Mesma estrutura de [Atributos de `address`](#atributos-de-address). |
| `person_type` | string | obrigatório | 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. Para 1%, informar `0.01`. Até 8 casas decimais. |

**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 |
|---|---|---|---|
| `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 | opcional | 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. |

#### Atributos de `delay`

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `fine` | object | opcional | Dados da multa por atraso. Veja [Atributos de `fine`](#atributos-de-fine). |
| `interest` | object | opcional | Dados do juros de mora. Veja [Atributos de `interest`](#atributos-de-interest). |

#### 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. Mesma estrutura de [Atributos de `pre_fixed`](#atributos-de-pre_fixed). |

**Enumeradores de `method`:**

| Valor | Descrição |
|---|---|
| `compound` | Juros de mora composto. |
| `simple` | Juros de mora simples. |

#### Atributos de `consignee`

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `name` | string | obrigatório | 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-imóvel). |
| `vehicle` | Garantia de veículo. Incluir os campos de [Atributos de garantia veículo](#atributos-de-garantia-veículo). |

#### 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. |

## Possíveis erros

STATUS 404

**Lote não encontrado**

O `assignment_external_id` informado na URL não corresponde a nenhum lote existente nesta configuração de cessão. Verifique se o identificador está correto.

```json
{
  "title": "Assignment not found",
  "description": "Assignment not found",
  "translation": "Lote não encontrado",
  "code": "TRC000018"
}
```

STATUS 404

**Tipo de ativo não existe**

O valor informado no campo `asset_type` não é um tipo válido. Verifique se o tipo está correto (ex: `ccb`, `duplicata_mercantil`, `discounted_contract`).

```json
{
  "title": "Asset type does not exist",
  "description": "Asset type 'invalid_asset_type' does not exist",
  "translation": "Tipo do ativo 'invalid_asset_type' nao existe",
  "code": "TRC000015"
}
```

STATUS 400

**Tipo de ativo incompatível com o lote**

O lote foi configurado para receber um tipo de ativo diferente do informado. Cada configuração de cessão aceita apenas um tipo de ativo específico. Verifique a configuração de cessão utilizada.

```json
{
  "title": "Invalid asset type configuration",
  "description": "This assignment can not receive this asset type: ccb",
  "translation": "Esse lote não pode receber esse tipo de ativo: ccb",
  "code": "TRC000025"
}
```

STATUS 400

**Lote fechado para inserção**

O lote já foi encerrado para inserção de novos ativos. Após o encerramento, não é possível adicionar mais ativos. Caso precise, [reabra o lote](/documentation/iaas/negociacao_recebiveis/asset/remocao_ativos) antes de inserir novos ativos.

```json
{
  "title": "Assignment is closed",
  "description": "Assignment is closed to insert new assets",
  "translation": "Lote esta fechado para inserir novos ativos",
  "code": "TRC000022"
}
```

STATUS 400

**Número de documento inválido**

Um dos números de documento informados (CPF ou CNPJ) é inválido. Verifique os campos `document_number`, `originator_document_number` e demais campos de documento no request body.

```json
{
  "title": "Invalid Document number",
  "description": "Given '000.000.000-00' document number is invalid.",
  "translation": "O numero de document '000.000.000-00' fornecido não é valido.",
  "code": "TRC000009"
}
```

STATUS 400

**External ID duplicado**

Já existe um ativo cadastrado com o `external_id` informado. Cada ativo deve ter um identificador único. Gere um novo `external_id` e tente novamente.

```json
{
  "title": "Already Exist This External Id",
  "description": "Already exist an asset with this External Id",
  "translation": "Ja existe um ativo com esse External Id",
  "code": "TRC000054"
}
```

## Próximos passos

Após inserir o ativo, o fluxo continua com:

1. **[Envio dos documentos](/documentation/iaas/negociacao_recebiveis/asset/documents)** — envie a documentação exigida 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.

:::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 os [documentos](/documentation/iaas/negociacao_recebiveis/asset/documents) exigidos e [encerre a inserção](/documentation/iaas/negociacao_recebiveis/assignment/fechamento).
:::

:::info Um ativo, várias parcelas
Diferente do [Contrato Descontado](/documentation/iaas/negociacao_recebiveis/asset/criacao_discounted_contract) — em que cada parcela é um ativo independente — no contrato parcelado **o ativo é o contrato**, e as parcelas são o fluxo de pagamentos dele. O array `installments` precisa conter todas as parcelas do contrato que estão sendo cedidas.
:::

:::caution Atenção
O campo `external_id` do contrato deve ser único para cada ativo 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": "53.020.654/0001-43",
        "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": "Jove de Souza",
            "document_number": "593.607.530-33",
            "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
Os campos `premiums` e `deductions` **não são utilizados** em cessão de contrato parcelado. O valor de aquisição do ativo é sempre 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 formatado do originador/consultor que viabilizou a operação. Precisa estar cadastrado e vinculado à configuração de cessão. |
| `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. |

:::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.
:::

## Possíveis erros

STATUS 400

**Parcelas fora de sequência**

Ordenando as parcelas pela data de vencimento, os `installment_number` não formam a sequência `1, 2, 3, …`. Verifique se há número repetido, salto na numeração ou parcela com vencimento fora da ordem.

```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"
}
```

STATUS 400

**Tipo de ativo incompatível com o lote**

O lote foi configurado para receber um tipo de ativo diferente do informado. Cada configuração de cessão aceita apenas um tipo de ativo específico. Verifique a configuração de cessão utilizada.

```json
{
  "title": "Invalid asset type configuration",
  "description": "This assignment can not receive this asset type: contract",
  "translation": "Esse lote não pode receber esse tipo de ativo: contract",
  "code": "TRC000025"
}
```

STATUS 400

**Payload incompatível com o tipo de ativo**

O objeto `contract` só é aceito para o tipo de ativo `contract`. Outros tipos de contrato — como `financing_contract` e `debt_acknowledgment` — não são cedidos por este fluxo.

```json
{
  "title": "Invalid assignment date.",
  "description": "The provided asset_type does not match the specific information passed.",
  "translation": "o asset_type fornecido não coincide com as informações especificas passadas",
  "code": "TRC000084"
}
```

STATUS 404

**Lote não encontrado**

O `assignment_external_id` informado na URL não corresponde a nenhum lote existente nesta configuração de cessão. Verifique se o identificador está correto.

```json
{
  "title": "Assignment not found",
  "description": "Assignment not found",
  "translation": "Lote não encontrado",
  "code": "TRC000018"
}
```

STATUS 400

**Lote fechado para inserção**

O lote já foi encerrado para inserção de novos ativos. Após o encerramento, não é possível adicionar mais ativos. Caso precise, [reabra o lote](/documentation/iaas/negociacao_recebiveis/asset/remocao_ativos) antes de inserir novos ativos.

```json
{
  "title": "Assignment is closed",
  "description": "Assignment is closed to insert new assets",
  "translation": "Lote esta fechado para inserir novos ativos",
  "code": "TRC000022"
}
```

STATUS 400

**Número de documento inválido**

Um dos números de documento informados (CPF ou CNPJ) é inválido. Verifique os campos `originator_document_number` e `borrower.document_number`.

```json
{
  "title": "Invalid Document number",
  "description": "Given '000.000.000-00' document number is invalid.",
  "translation": "O numero de document '000.000.000-00' fornecido não é valido.",
  "code": "TRC000009"
}
```

STATUS 400

**External ID duplicado**

Já existe um ativo cadastrado com o `external_id` informado. Cada ativo deve ter um identificador único. Gere um novo `external_id` e tente novamente.

```json
{
  "title": "Already Exist This External Id",
  "description": "Already exist an asset with this External Id",
  "translation": "Ja existe um ativo com esse External Id",
  "code": "TRC000054"
}
```

## Próximos passos

Após inserir o ativo, o fluxo continua com:

1. **[Envio dos documentos](/documentation/iaas/negociacao_recebiveis/asset/documents)** — envie o contrato assinado, com `document_type` igual a `contract`.
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.

:::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 os [documentos](/documentation/iaas/negociacao_recebiveis/asset/documents) exigidos e [encerre a inserção](/documentation/iaas/negociacao_recebiveis/assignment/fechamento).
:::

:::caution Atenção
O campo `external_id` do direito creditório deve ser único para cada ativo 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": "46.282.154/0001-14",
        "maturity_date": "2023-12-10",
        "order_number": "18923619954796912",
        "face_value": 1023.01,
        "person_type": "legal_person",
        "borrower": {
            "name": "Transportadora Exemplo Ltda",
            "document_number": "46.282.154/0001-14",
            "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": "35231146282154000114570000000001189236199547",
            "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 do originador/consultor que viabilizou a operação. |
| `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. |
| `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`](#atributos-de-borrower). |
| `invoice` | object | obrigatório | Dados do CT-e. Veja [Atributos de `invoice`](#atributos-de-invoice). |
| `participant_control_number` | string | opcional | Número de controle do participante no sistema do parceiro. Máximo de 25 caracteres alfanuméricos. |
| `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. Os caracteres de posição 20 a 22 devem corresponder ao 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 `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 | obrigatório | 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, 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 | obrigatório | 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. |
| `postal_code` | string | obrigatório | CEP. 9 caracteres (com hífen). |
| `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. Até 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. |
| `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 | obrigatório | Código de atividade 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 | opcional | E-mail do representante. Máximo de 255 caracteres. |
| `phone` | object | opcional | Telefone. Mesma estrutura de [Atributos de `phone`](#atributos-de-phone). |
| `address` | object | opcional | Endereço. Mesma estrutura de [Atributos de `address`](#atributos-de-address). |
| `person_type` | string | obrigatório | Tipo de pessoa (`natural_person` ou `legal_person`). |
| `representative_type` | string | opcional | Tipo do representante. Máximo de 50 caracteres. |

#### 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 | opcional | Dados da multa por atraso. Veja [Atributos de `fine`](#atributos-de-fine). |
| `interest` | object | opcional | Dados do juros de mora. Veja [Atributos de `interest`](#atributos-de-interest). |

#### 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. Informar quando `method` for `pre_fixed`. Para 1%, informar `0.01`. Até 8 casas decimais. |
| `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. |

## Possíveis erros

STATUS 404

**Lote não encontrado**

O `assignment_external_id` informado na URL não corresponde a nenhum lote existente nesta configuração de cessão. Verifique se o identificador está correto.

```json
{
  "title": "Assignment not found",
  "description": "Assignment not found",
  "translation": "Lote não encontrado",
  "code": "TRC000018"
}
```

STATUS 404

**Tipo de ativo não existe**

O valor informado no campo `asset_type` não é um tipo válido. Verifique se o tipo está correto (ex: `cte`).

```json
{
  "title": "Asset type does not exist",
  "description": "Asset type 'invalid_asset_type' does not exist",
  "translation": "Tipo do ativo 'invalid_asset_type' nao existe",
  "code": "TRC000015"
}
```

STATUS 400

**Tipo de ativo incompatível com o lote**

O lote foi configurado para receber um tipo de ativo diferente do informado. Cada configuração de cessão aceita apenas um tipo de ativo específico. Verifique a configuração de cessão utilizada.

```json
{
  "title": "Invalid asset type configuration",
  "description": "This assignment can not receive this asset type: cte",
  "translation": "Esse lote não pode receber esse tipo de ativo: cte",
  "code": "TRC000025"
}
```

STATUS 400

**Lote fechado para inserção**

O lote já foi encerrado para inserção de novos ativos. Após o encerramento, não é possível adicionar mais ativos. Caso precise, [reabra o lote](/documentation/iaas/negociacao_recebiveis/asset/remocao_ativos) antes de inserir novos ativos.

```json
{
  "title": "Assignment is closed",
  "description": "Assignment is closed to insert new assets",
  "translation": "Lote esta fechado para inserir novos ativos",
  "code": "TRC000022"
}
```

STATUS 400

**Chave de acesso do CT-e ausente**

O campo `access_key` dentro de `invoice` é obrigatório para ativos do tipo `cte`. Inclua a chave de acesso do CT-e no request body.

```json
{
  "title": "Access Key Required",
  "description": "Access key is required for cte asset type",
  "translation": "Chave de acesso é obrigatória para o tipo de ativo cte",
  "code": "TRC000134"
}
```

STATUS 400

**Chave de acesso do CT-e inválida**

A `access_key` informada não corresponde a um CT-e válido. Os caracteres de posição 20 a 22 da chave de acesso devem ser `57` ou `67`, que identificam o modelo do documento fiscal CT-e.

```json
{
  "title": "Invalid CTE Access Key",
  "description": "Access key is not valid for a CTE document",
  "translation": "Chave de acesso não é válida para um documento CT-e",
  "code": "TRC000133"
}
```

STATUS 400

**External ID duplicado**

Já existe um ativo cadastrado com o `external_id` informado. Cada ativo deve ter um identificador único. Gere um novo `external_id` e tente novamente.

```json
{
  "title": "Already Exist This External Id",
  "description": "Already exist an asset with this External Id",
  "translation": "Ja existe um ativo com esse External Id",
  "code": "TRC000054"
}
```

## Próximos passos

Após inserir o ativo, o fluxo continua com:

1. **[Envio dos documentos](/documentation/iaas/negociacao_recebiveis/asset/documents)** — envie a documentação exigida 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.

:::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 os [documentos](/documentation/iaas/negociacao_recebiveis/asset/documents) exigidos e [encerre a inserção](/documentation/iaas/negociacao_recebiveis/assignment/fechamento).
:::

:::caution Atenção
O campo `external_id` do direito creditório deve ser único para cada ativo 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": "discounted_contract",
    "total_purchase_value": 1231.21,
    "discounted_credit_right": {
        "external_id": "mdf27za1-ra5f-46c0-a32f-fb909884dbb2",
        "originator_document_number": "46.282.154/0001-14",
        "face_value": 1231.21,
        "maturity_date": "2025-12-10",
        "installment_number": 1,
        "borrower": {
            "name": "Natália Nascimento",
            "document_number": "19.845.976/0001-93",
            "person_type": "natural_person",
            "email": "natália.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"
            }
        },
        "contract": {
            "number_of_installments": 5,
            "total_face_value": 1231.21,
            "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 do originador/consultor que viabilizou a operação. |
| `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 | opcional | Número da parcela. |
| `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). |

#### Atributos de `contract`

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `number_of_installments` | integer | obrigatório | Número total de parcelas do contrato. |
| `total_face_value` | number | obrigatório | Valor de face total do contrato. Até 2 casas decimais. |
| `number` | string | obrigatório | Número do contrato. Máximo de 50 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": "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. |

## Possíveis erros

STATUS 404

**Lote não encontrado**

O `assignment_external_id` informado na URL não corresponde a nenhum lote existente nesta configuração de cessão. Verifique se o identificador está correto.

```json
{
  "title": "Assignment not found",
  "description": "Assignment not found",
  "translation": "Lote não encontrado",
  "code": "TRC000018"
}
```

STATUS 404

**Tipo de ativo não existe**

O valor informado no campo `asset_type` não é um tipo válido. Verifique se o tipo está correto (ex: `discounted_contract`).

```json
{
  "title": "Asset type does not exist",
  "description": "Asset type 'invalid_asset_type' does not exist",
  "translation": "Tipo do ativo 'invalid_asset_type' nao existe",
  "code": "TRC000015"
}
```

STATUS 400

**Tipo de ativo incompatível com o lote**

O lote foi configurado para receber um tipo de ativo diferente do informado. Cada configuração de cessão aceita apenas um tipo de ativo específico. Verifique a configuração de cessão utilizada.

```json
{
  "title": "Invalid asset type configuration",
  "description": "This assignment can not receive this asset type: discounted_contract",
  "translation": "Esse lote não pode receber esse tipo de ativo: discounted_contract",
  "code": "TRC000025"
}
```

STATUS 400

**Lote fechado para inserção**

O lote já foi encerrado para inserção de novos ativos. Após o encerramento, não é possível adicionar mais ativos. Caso precise, [reabra o lote](/documentation/iaas/negociacao_recebiveis/asset/remocao_ativos) antes de inserir novos ativos.

```json
{
  "title": "Assignment is closed",
  "description": "Assignment is closed to insert new assets",
  "translation": "Lote esta fechado para inserir novos ativos",
  "code": "TRC000022"
}
```

STATUS 400

**External ID duplicado**

Já existe um ativo cadastrado com o `external_id` informado. Cada ativo deve ter um identificador único. Gere um novo `external_id` e tente novamente.

```json
{
  "title": "Already Exist This External Id",
  "description": "Already exist an asset with this External Id",
  "translation": "Ja existe um ativo com esse External Id",
  "code": "TRC000054"
}
```

## Próximos passos

Após inserir o ativo, o fluxo continua com:

1. **[Envio dos documentos](/documentation/iaas/negociacao_recebiveis/asset/documents)** — envie a documentação exigida 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 Diferença entre os tipos
Ambos os tipos utilizam a mesma estrutura de request body. A principal diferença é que a **duplicata mercantil** não exige envio de documentos após a elegibilidade, enquanto a **duplicata de serviços** exige. 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 os [documentos](/documentation/iaas/negociacao_recebiveis/asset/documents) exigidos e [encerre a inserção](/documentation/iaas/negociacao_recebiveis/assignment/fechamento).
:::

:::caution Atenção
O campo `external_id` do direito creditório deve ser único para cada ativo 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": "46.282.154/0001-14",
        "maturity_date": "2023-12-10",
        "order_number": "18923619954796912",
        "face_value": 1023.01,
        "person_type": "natural_person",
        "borrower": {
            "name": "Natália Nascimento",
            "document_number": "805.359.140-08",
            "person_type": "natural_person",
            "email": "natália.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": "69037229347091328617032722238810300308237163",
            "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 do originador/consultor que viabilizou a operação. |
| `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. |
| `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 50 caracteres alfanuméricos. |
| `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_co#atributos-de-delay) na página de Criação de Ativo — CCB. |
| `invoice` | object | obrigatório | Dados da nota fiscal. Veja [Atributos de `invoice`](#atributos-de-invoice). |

#### 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 | obrigatório | Chave de acesso da nota fiscal. 44 caracteres. |
| `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 50 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. |

## Possíveis erros

STATUS 404

**Lote não encontrado**

O `assignment_external_id` informado na URL não corresponde a nenhum lote existente nesta configuração de cessão. Verifique se o identificador está correto.

```json
{
  "title": "Assignment not found",
  "description": "Assignment not found",
  "translation": "Lote não encontrado",
  "code": "TRC000018"
}
```

STATUS 404

**Tipo de ativo não existe**

O valor informado no campo `asset_type` não é um tipo válido. Verifique se o tipo está correto (ex: `duplicata_mercantil`, `duplicata_servicos`).

```json
{
  "title": "Asset type does not exist",
  "description": "Asset type 'invalid_asset_type' does not exist",
  "translation": "Tipo do ativo 'invalid_asset_type' nao existe",
  "code": "TRC000015"
}
```

STATUS 400

**Tipo de ativo incompatível com o lote**

O lote foi configurado para receber um tipo de ativo diferente do informado. Cada configuração de cessão aceita apenas um tipo de ativo específico. Verifique a configuração de cessão utilizada.

```json
{
  "title": "Invalid asset type configuration",
  "description": "This assignment can not receive this asset type: duplicata_mercantil",
  "translation": "Esse lote não pode receber esse tipo de ativo: duplicata_mercantil",
  "code": "TRC000025"
}
```

STATUS 400

**Lote fechado para inserção**

O lote já foi encerrado para inserção de novos ativos. Após o encerramento, não é possível adicionar mais ativos. Caso precise, [reabra o lote](/documentation/iaas/negociacao_recebiveis/asset/remocao_ativos) antes de inserir novos ativos.

```json
{
  "title": "Assignment is closed",
  "description": "Assignment is closed to insert new assets",
  "translation": "Lote esta fechado para inserir novos ativos",
  "code": "TRC000022"
}
```

STATUS 400

**External ID duplicado**

Já existe um ativo cadastrado com o `external_id` informado. Cada ativo deve ter um identificador único. Gere um novo `external_id` e tente novamente.

```json
{
  "title": "Already Exist This External Id",
  "description": "Already exist an asset with this External Id",
  "translation": "Ja existe um ativo com esse External Id",
  "code": "TRC000054"
}
```

## Próximos passos

Após inserir o ativo, o fluxo continua com:

1. **[Envio dos documentos](/documentation/iaas/negociacao_recebiveis/asset/documents)** — envie a documentação exigida 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 um ativo que será **recomprado** pelo cedente em um lote de substituição. A recompra ocorre quando o cedente precisa retirar um ativo da carteira do fundo, substituindo-o por novos ativos.

:::info Lotes de substituição
Este endpoint é utilizado exclusivamente em **lotes de substituição**. O fluxo de substituição difere do fluxo de cessão padrão por incluir um passo adicional: a inserção dos ativos a serem recomprados, antes da inserção dos novos ativos.

Para mais detalhes, consulte o [Manual de Cessão de Direitos Creditórios](/documentation/iaas/negociacao_recebiveis/manual_api).
:::

:::tip Onde estou no fluxo?
Este é o **2º passo** do fluxo de substituição. Antes, você deve ter [criado o lote](/documentation/iaas/negociacao_recebiveis/assignment/criacao). Após inserir os ativos de recompra, insira 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": "66.642.277/0001-26",
    "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 | Identificador externo do ativo que será recomprado. Deve ser o mesmo `external_id` utilizado quando o ativo foi originalmente inserido. |
| `assignor_document_number` | string | obrigatório | CPF ou CNPJ do cedente que originalmente cedeu o ativo ao fundo. |
| `repurchase_value` | number | obrigatório | Valor de recompra do ativo. Até 2 casas decimais. |
| `settlement_type` | string | obrigatório | Modalidade de substituição [settlement_type](#settlement-type). |

### Settlement Type
| Enumerador | descrição |
|---|---|
| `asset_settlement` | Substituição total do ativo. |
| `asset_amortization` |  Substituição parcial do ativo. |

## Response

STATUS 201

```json title="Response Body"
{
    "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-7890-abcd-ef1234567890",
        "document_number": "66.642.277/0001-26",
        "name": "Cedente Exemplo Ltda"
    },
    "status": "pending_eligibility",
    "assignment": {
        "assignment_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3",
        "external_id": "931e9437-d025-41ab-bb53-6b94e10fd361",
        "name": "CESSÃO #12345",
        "assignment_number": "00012345",
        "assignment_date": "2024-04-01",
        "status": "pending_assets_insertion",
        "origin_type": "client"
    },
    "repurchase_value": 1000.00
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `repurchased_asset_key` | string | Identificador único do registro de recompra gerado pela QI Tech (UUID). |
| `asset_type` | string | Tipo do ativo recomprado. |
| `asset_key` | string | Identificador único do ativo original na carteira do fundo (UUID). |
| `external_id` | string | Identificador externo do ativo, conforme informado na requisição. |
| `assignor` | object | Dados do cedente que originalmente cedeu o ativo. |
| `status` | string | Status atual do ativo de recompra. |
| `assignment` | object | Dados do lote de substituição ao qual o ativo de recompra pertence. Consulte os [atributos do lote](/documentation/iaas/negociacao_recebiveis/assignment/recuperacao) na página de Recuperação do Lote. |
| `repurchase_value` | number | Valor de recompra do ativo, conforme informado na requisição. |

#### Atributos de `assignor`

| Campo | Tipo | Descrição |
|---|---|---|
| `assignor_key` | string | Identificador único do cedente (UUID). |
| `document_number` | string | CPF ou CNPJ do cedente. |
| `name` | string | Nome do cedente. |

## Possíveis erros

STATUS 404

**Lote não encontrado**

```json
{
  "title": "Assignment not found",
  "description": "Assignment not found",
  "translation": "Lote não encontrado",
  "code": "TRC000018"
}
```

STATUS 404

**Ativo não encontrado**

```json
{
  "title": "Asset not found",
  "description": "Asset not found",
  "translation": "Ativo não foi encontrado",
  "code": "TRC000020"
}
```

STATUS 400

**Lote fechado para inserção**

```json
{
  "title": "Assignment is closed",
  "description": "Assignment is closed to insert new assets",
  "translation": "Lote esta fechado para inserir novos ativos",
  "code": "TRC000022"
}
```

## Próximos passos

Após inserir os ativos de recompra, o fluxo continua com:

1. **[Inserção dos novos ativos](/documentation/iaas/negociacao_recebiveis/asset/criacao_co)** — adicione os ativos que substituirão os recomprados.
2. **[Envio dos documentos](/documentation/iaas/negociacao_recebiveis/asset/documents)** — envie a documentação exigida 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.

---

# Inserção de Documentos do Ativo

URL: /documentation/iaas/negociacao_recebiveis/asset/documents

Endpoint para enviar os documentos obrigatórios associados a um ativo do lote de cessão. Os documentos devem ser enviados em formato PDF codificado em Base64.

:::tip Onde estou no fluxo?
O envio de documentos ocorre após a inserção do ativo e após o ativo ter sido aprovado na elegibilidade individual. Você receberá um [webhook](/documentation/iaas/negociacao_recebiveis/asset/webhooks) com o status `pending_documentation` indicando que o ativo está aguardando documentação.
:::

:::info Quais ativos exigem documentos?
- **CCB** (`ccb`): o envio de documentos é sempre obrigatório.
- **Duplicata de serviços** (`duplicata_servicos`): o envio de documentos é obrigatório.
- **Duplicata mercantil** (`duplicata_mercantil`): o envio de documentos **não** é obrigatório — a documentação é gerada automaticamente pelo sistema a partir dos dados da nota fiscal.
- **Contrato descontado** (`discounted_contract`): consulte a configuração do produto no Contrato de Cessão.

O ativo só avança para o status `pre_approved` depois que todos os documentos exigidos forem enviados.
:::

:::info Formato do documento
O arquivo enviado deve ser um **PDF válido** codificado em Base64. Outros formatos serão rejeitados com erro.
:::

## 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 PDF codificado em Base64. |

**Enumeradores de `document_type`:**

| Valor | Descrição |
|---|---|
| `ccb` | Cédula de Crédito Bancário — usado em ativos do tipo CCB. |
| `duplicata_servicos` | Duplicata de serviços — usado em ativos de duplicata de serviços. |
| `contract` | Contrato parcelado — usado em ativos do tipo `contract`. |
| `vehicle_reservation_receipt` | Comprovante de reserva do veículo — usado em operações de crédito com garantia de veículo. É um documento **pós-cessão**. |

:::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`. **Este segundo momento não é notificado por webhook** — diferente do primeiro: acompanhe pela [recuperação do ativo](/documentation/iaas/negociacao_recebiveis/asset/recuperar_ativos) e trate o `completed` como confirmação.

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 existe no sistema mas não está configurado para aquela cessão devolve `TRC000032`; enviar um valor que o sistema não conhece devolve `TRC000033`.
:::

## 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). |

## Possíveis erros

STATUS 404

**Ativo não encontrado**

O `asset_external_id` informado na URL não corresponde a nenhum ativo do lote. Verifique se o identificador está correto e se o ativo pertence ao lote informado.

```json
{
  "title": "Asset not found",
  "description": "Asset not found",
  "translation": "Ativo não foi encontrado",
  "code": "TRC000020"
}
```

STATUS 400

**Tipo de documento inválido para esta configuração**

O valor informado em `document_type` não corresponde a nenhum tipo de documento configurado para esta cessão. Verifique quais tipos de documento são aceitos na configuração de cessão utilizada.

```json
{
  "title": "Invalid documents",
  "description": "Required documents type are invalid",
  "translation": "Tipo de Documentos requeridos sao inválidos",
  "code": "TRC000032"
}
```

STATUS 400

**Tipo de documento não reconhecido**

O tipo de documento informado não é reconhecido pelo sistema. Verifique se o valor de `document_type` está correto.

```json
{
  "title": "Invalid document type",
  "description": "Invalid document type",
  "translation": "Tipo de documento invalido",
  "code": "TRC000033"
}
```

STATUS 400

**Formato do documento inválido**

O arquivo enviado não está em formato PDF válido ou a codificação Base64 está incorreta. Verifique se o arquivo é um PDF válido e se a codificação Base64 foi feita corretamente.

```json
{
  "title": "Invalid document format",
  "description": "Invalid document format",
  "translation": "Formato do documento invalido",
  "code": "TRC000034"
}
```

STATUS 400

**Status do ativo inválido para envio de documento**

O ativo não está em um status que permita o envio de documentos. Normalmente isso significa que o ativo ainda não foi aprovado na elegibilidade ou já foi descartado.

```json
{
  "title": "Invalid operation",
  "description": "Asset is not in a valid status to receive documents",
  "translation": "Ativo não está em status válido para receber documentos",
  "code": "TRC000024"
}
```

## 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 e documentos foram inseridos para que o lote siga para a análise de elegibilidade.

---

# 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.

### 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. |
| `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. |

```python title="Exemplo — listagem simples"
GET /trade_receivables/fund_class/{fund_class_key}/assignment/{assignment_external_id}/assets?page=0&limit=10
```

```python 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
```

:::warning Status inválido
Se o valor enviado em `status` não corresponder a nenhum enumerador válido, a requisição retorna erro. 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`). |
| `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-reprovação-denied_by). |
| `denial_reason` | string | Descrição do motivo da reprovação. Presente apenas quando o ativo foi reprovado. |

:::info Objetos aninhados
Dependendo do tipo de ativo, a resposta incluirá o objeto `credit_operation` (para CCBs) ou `discounted_credit_right` (para duplicatas e contratos descontados) com todos os dados da operação de crédito.
:::

## 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`:

```python 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#pendente-aprovação-do-gestor) — 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.

### 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 do objeto completo da operação de crédito (`credit_operation` ou `discounted_credit_right`, dependendo do tipo de 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. |
| `completed` | Ativo encarteirado na carteira do fundo. |

---

# Remoção de Ativos do Lote

URL: /documentation/iaas/negociacao_recebiveis/asset/remocao_ativos

Processo para retirar ativos de um lote que está aguardando aprovação do gestor. A remoção envolve **3 passos sequenciais**: reabrir o lote, remover os ativos desejados e fechar o lote novamente.

:::info Pré-requisito
A remoção de ativos só é possível quando o lote está no status `pending_manager_approval` (aguardando aprovação do gestor). Com o lote nesse status, é necessário reabri-lo antes de realizar qualquer alteração nos ativos.
:::

## Passo 1 — Reabrir o lote

Altere o status do lote para `pending_assets_insertion` para permitir a remoção de ativos.

### 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"
{
    "assignment_status": "pending_assets_insertion"
}
```

#### Atributos do body

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `assignment_status` | string | obrigatório | Status para o qual o lote será atualizado. Para reabrir, envie `pending_assets_insertion`. |

### 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": 10,
    "assignment_total_value": 1234.99
}
```

#### 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: `pending_assets_insertion`. |
| `number_of_approved_assets` | integer | Quantidade de ativos aprovados no lote. |
| `assignment_total_value` | number | Valor total da cessão em reais. |

## Passo 2 — Remover ativos

Com o lote reaberto, remova cada ativo desejado alterando seu status para `denied`. Realize uma requisição para cada ativo a ser removido.

### 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 |
|---|---|---|
| `asset_external_id` | string | O `external_id` do ativo que será removido. |

```json title="Request Body"
{
    "asset_status": "denied"
}
```

#### Atributos do body

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `asset_status` | string | obrigatório | Status para o qual o ativo será atualizado. Para remover, envie `denied`. |

### Response

STATUS 200

```json title="Response Body"
{
    "external_id": "9eec85be-97c9-41e0-88b3-b17a39869b36",
    "status": "denied"
}
```

#### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `external_id` | string | Chave externa do ativo. |
| `status` | string | Novo status do ativo: `denied`. |

## Passo 3 — Fechar o lote novamente

Após remover os ativos desejados, feche o lote para que ele siga novamente para aprovação do gestor.

### 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"
{
    "assignment_status": "completed_assets_insertion"
}
```

#### Atributos do body

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `assignment_status` | string | obrigatório | Status para o qual o lote será atualizado. Para fechar, envie `completed_assets_insertion`. |

### Response

STATUS 200

```json title="Response Body"
{
    "assignment_key": "8e515a17-8b4d-49a3-aed6-47c9574e426a",
    "external_id": "9eec85be-97c9-41e0-88b3-b17a39869b36",
    "status": "completed_assets_insertion",
    "number_of_approved_assets": 10,
    "assignment_total_value": 1234.99
}
```

#### 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`. |
| `number_of_approved_assets` | integer | Quantidade de ativos aprovados remanescentes. |
| `assignment_total_value` | number | Valor total atualizado da cessão em reais. |

Após fechar o lote, ele seguirá novamente para aprovação do gestor e continuará o fluxo normalmente.

## Possíveis erros

STATUS 404

**Ativo não encontrado**

O `asset_external_id` informado na URL não corresponde a nenhum ativo do lote. Verifique se o identificador está correto e se o ativo pertence ao lote informado.

```json
{
  "title": "Asset not found",
  "description": "Asset not found",
  "translation": "Ativo não foi encontrado",
  "code": "TRC000020"
}
```

STATUS 400

**Ativo não pode ser removido**

O ativo informado não pode ser negado/removido no status atual. Isso pode ocorrer quando o ativo já foi descartado ou quando o lote não está aberto para modificação.

```json
{
  "title": "Cant deny this asset.",
  "description": "This asset cant be denied.",
  "translation": "Esse ativo não pode ser negado",
  "code": "TRC000086"
}
```

STATUS 400

**Status do lote inválido para esta operação**

O lote não está em um status que permita esta operação. Para remover ativos, o lote precisa estar no status `pending_assets_insertion`. Verifique o status atual do lote e, se necessário, reabra-o primeiro (Passo 1).

```json
{
  "title": "Invalid assignment status",
  "description": "Assignment is not in a valid status for this operation",
  "translation": "O lote não está em um status valido para essa operação",
  "code": "TRC000087"
}
```

---

# 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. Entre em contato com [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br) para configurar.
:::

## 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. Todos os nove status geram webhook — o caminho central leva ao encarteiramento, e as três saídas de recusa ou descarte são terminais.

![Fluxo de status do ativo, do pending_eligibility até completed, com as saídas para denied, registry_denied e discarded](/img/diagrams/iaas-negociacao-recebiveis-asset-webhooks.svg)

_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 evento no formato ISO 8601. |
| `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. |
| `asset_payload` | object | Presente apenas no webhook de criação (`asset_creation`). Contém todos os dados do ativo conforme enviados na criação. |

:::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"
    },
    "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",
        "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": "926.857.750-05"
                },
                "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": "40.940.511/0001-08"
            },
            "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 está aguardando o envio dos documentos obrigatórios. Utilize o endpoint de [Inserção de Documentos](/documentation/iaas/negociacao_recebiveis/asset/documents) para enviar a documentação exigida.

```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"
    },
    "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"
    },
    "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"
    },
    "webhook_type": "trade_receivables.asset_status_change",
    "webhook_datetime": "2024-04-23T15:08:30Z"
}
```

---

### Pendente Formalização

STATUS pending_formalization

Enviado quando o ativo pré-aprovado foi encaminhado para a etapa de formalização (registro no órgão competente). O ativo aguarda a conclusão do processo de registro para ser encarteirado.

```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_formalization",
        "assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef",
        "fund_class_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c"
    },
    "webhook_type": "trade_receivables.asset_status_change",
    "webhook_datetime": "2024-04-23T15:08:30Z"
}
```

---

### 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"
    },
    "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 análise de elegibilidade ou na validação de documentos. O ativo não seguirá adiante no fluxo.

```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"
    },
    "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. É um status **terminal**: o ativo não segue para a formalização nem para o encarteiramento. O motivo da recusa é registrado pela QI Tech e não vem no corpo do webhook — consulte a [recuperação do ativo](/documentation/iaas/negociacao_recebiveis/asset/recuperar_ativos) ou o time de integração para o detalhe.

```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"
    },
    "webhook_type": "trade_receivables.asset_status_change",
    "webhook_datetime": "2024-04-23T15:08:30Z"
}
```

---

### Ativo Descartado

STATUS discarded

Enviado quando o ativo é descartado do lote. Isso pode ocorrer por remoção manual ou por problemas durante o processamento.

```json title="Webhook Body"
{
    "data": {
        "assignment_external_id": "ac597f90-a13e-4f78-86f0-11c66f5fa6d6",
        "asset_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
        "asset_new_status": "discarded",
        "assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef",
        "fund_class_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c"
    },
    "webhook_type": "trade_receivables.asset_status_change",
    "webhook_datetime": "2024-04-23T15:08:30Z"
}
```

---

# Aprovação do Gestor

URL: /documentation/iaas/negociacao_recebiveis/assignment/aprovacao

Após a elegibilidade do lote ser aprovada, o gestor do fundo deve analisar e decidir pela aprovação ou reprovação do lote. Se aprovado, o sistema gera o Termo de Cessão e o encaminha para assinatura. Se reprovado, o lote é descartado e o processo se encerra.

:::info Rota exclusiva para Gestores
Este endpoint está disponível **somente para gestores** do fundo. Caso o gestor não seja integrado via API, essa ação pode ser realizada pelo [Portal do Gestor](https://portal-do-gestor.fundos.qitech.com.br/).
:::

:::tip Onde estou no fluxo?
Este passo ocorre após a **elegibilidade do lote** ter sido aprovada. Você receberá um [webhook](/documentation/iaas/negociacao_recebiveis/assignment/webhooks) com o status `pending_manager_approval` indicando que o lote está aguardando a decisão do gestor.
:::

## 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"
}
```

```json title="Request Body — Reprovação"
{
    "assignment_status": "denied"
}
```

### Atributos do body

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `assignment_status` | string | obrigatório | Decisão do gestor sobre o lote. Valores aceitos: `approved` ou `denied`. |
| `disbursement_account_key` | string | opcional | Chave única (UUID, 36 caracteres) da conta de desembolso cadastrada na homologação do cedente. Se não informada, será utilizada a conta padrão configurada no contrato de cessão. |

**Enumeradores de `assignment_status`:**

| Valor | Descrição |
|---|---|
| `approved` | Aprova o lote — o sistema gerará o Termo de Cessão |
| `denied` | Reprova o lote — o lote será descartado |

## Response

STATUS 200

```json title="Response Body — Aprovação"
{
    "assignment_key": "41d6ff41-1dac-4df7-9e50-d15210ec57f3",
    "external_id": "931e9437-d025-41ab-bb53-6b94e10fd361",
    "status": "approved",
    "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",
    "number_of_approved_assets": 0,
    "assignment_total_value": 0.00
}
```

### 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 após a decisão do gestor (`approved` ou `denied`). |
| `number_of_approved_assets` | integer | Quantidade de ativos aprovados na elegibilidade. Em caso de reprovação, o valor será `0`. |
| `assignment_total_value` | number | Valor total da cessão em reais. Em caso de reprovação, o valor será `0.00`. |

## Possíveis erros

STATUS 400

**Lote não encontrado**

O `external_id` informado na URL não corresponde a nenhum lote existente nesta configuração de cessão. Verifique se o identificador está correto e se você está usando a `fund_class_key` e `assignment_configuration_key` corretas.

```json
{
  "title": "Assignment not found",
  "description": "Assignment not found",
  "translation": "Cessão não foi encontrada",
  "code": "TRC000018"
}
```

STATUS 400

**Operação inválida para o status atual**

O lote não está em um status que permita aprovação ou reprovação. Isso geralmente ocorre quando o lote ainda não passou pela elegibilidade, ou quando já foi aprovado/reprovado anteriormente. Consulte o status atual do lote via [Recuperação do Lote](/documentation/iaas/negociacao_recebiveis/assignment/recuperacao) para entender em qual etapa ele se encontra.

```json
{
  "title": "Invalid operation",
  "description": "This assignment can not receive 'denied' status",
  "translation": "Esse lote não pode receber o status 'denied'",
  "code": "TRC000024"
}
```

## Próximos passos

Após a aprovação do gestor, o fluxo continua automaticamente:

1. **Assinatura do Termo de Cessão** — o sistema gera o Termo de Cessão e o envia para assinatura de todas as partes. Você receberá um [webhook](/documentation/iaas/negociacao_recebiveis/assignment/webhooks) com status `pending_assignment_term_signature`. O documento pode ser consultado via [Documentos da Cessão](/documentation/iaas/negociacao_recebiveis/assignment/documento_da_cessao).
2. **Pagamento** — após a assinatura, o sistema realiza o pagamento ao cedente. Um [webhook](/documentation/iaas/negociacao_recebiveis/assignment/webhooks) com status `pending_payment` será enviado.
3. **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 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).

Essas duas chaves compõem os endpoints utilizados em todos os endpoints desta API:

```
/trade_receivables/fund_class/{fund_class_key}/assignment_configuration/{assignment_configuration_key}
```

Para mais detalhes sobre o fluxo completo, consulte o [Manual de Cessão de Direitos Creditórios](/documentation/iaas/negociacao_recebiveis/manual_api).
:::

## 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 | Chave única de identificação deste lote no sistema do parceiro integrador. Deve ser única — o sistema não permitirá a criação de dois lotes com o mesmo identificador. Máximo de 50 caracteres. |
| `assignment_date` | string | opcional | Data da cessão no formato `YYYY-MM-DD`. Quando informada, deve corresponder à data contábil do fundo (*accounting_date*). Se não informada, será utilizada a data contábil vigente. |

## 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. Sempre retorna `pending_assets_insertion`, indicando que o lote está pronto para receber ativos. |

## Possíveis erros

STATUS 404

**Configuração de cessão não encontrada**

A combinação de `fund_class_key` e `assignment_configuration_key` informada não corresponde a nenhuma configuração de cessão. Verifique se as chaves estão corretas e se o contrato de cessão já foi homologado na etapa de [Homologação de Cedente](/documentation/iaas/homologacao_cedente/contrato_de_cessao/pedido_de_contrato).

```json
{
  "title": "AssignmentConfiguration was not found",
  "description": "AssignmentConfiguration was not found",
  "translation": "Configuração de cessão não foi encontrada",
  "code": "TRC000016"
}
```

STATUS 400

**Data de cessão inválida**

A data informada no campo `assignment_date` não corresponde à data contábil atual do fundo. Cada fundo possui uma data contábil vigente, e a data da cessão precisa ser igual a essa data. Verifique a data contábil vigente do fundo ou omita o campo `assignment_date` para que o sistema utilize a data automaticamente.

```json
{
  "title": "Invalid assignment date.",
  "description": "Given assignment date is different from fund accounting date.",
  "translation": "Data de cessão fornecida diferente da data do fundo.",
  "code": "TRC000083"
}
```

STATUS 400

**External ID duplicado**

Já existe um lote cadastrado com o `external_id` informado. Cada lote deve ter um identificador único no sistema. Gere um novo `external_id` e tente novamente.

```json
{
  "title": "Already Exists This External Id",
  "description": "Already Exists This External Id",
  "translation": "Já existe lote com esse external_id",
  "code": "TRC000041"
}
```

## Próximos passos

Após criar o lote, o fluxo continua com:

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 dos documentos](/documentation/iaas/negociacao_recebiveis/asset/documents)** — envie a documentação exigida para cada ativo aprovado na elegibilidade.
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.

---

# Documentos da Cessão

URL: /documentation/iaas/negociacao_recebiveis/assignment/documento_da_cessao

Recupera os links para download do Termo de Cessão — tanto a versão original quanto a versão assinada. Este endpoint fica disponível a partir do momento em que o Termo é gerado, ou seja, após o lote atingir o status `pending_assignment_term_signature`.

:::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 \| null | URL para o Termo de Cessão assinado. Retorna `null` enquanto o documento ainda não tiver sido assinado por todas as partes. |

:::info Observação
O campo `signed_assignment_term_url` será `null` enquanto o Termo de Cessão ainda não tiver sido assinado por todas as partes envolvidas. Após a conclusão da assinatura, o lote avançará para o status `pending_payment` e um [webhook](/documentation/iaas/negociacao_recebiveis/assignment/webhooks) será enviado.
:::

---

# 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. Este endpoint fica disponível a partir do momento em que o Termo é gerado, ou seja, após o lote atingir o status `pending_assignment_term_signature`.

## 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 no status `pending_assignment_term_signature`. Após a conclusão da assinatura por todas as partes, passa a apontar para o Termo de Cessão assinado.
:::

---

# 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, quando todos os ativos estiverem pré-aprovados (`pre_approved`) ou descartados (`discarded`), a elegibilidade do lote como um todo será avaliada automaticamente.

:::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 aguardará automaticamente até que todos estejam com análise finalizada 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 os documentos](/documentation/iaas/negociacao_recebiveis/asset/documents)
:::

## 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 | Status para o qual o lote será atualizado. Para encerrar a inserção de ativos, envie `completed_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": 0.00
}
```

### 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`. |
| `number_of_approved_assets` | integer | Quantidade de ativos aprovados no lote. Nesta etapa, o valor será `0` pois a elegibilidade ainda não foi processada. |
| `assignment_total_value` | number | Valor total da cessão em reais. Nesta etapa, o valor será `0.00` pois a precificação ainda não ocorreu. |

## Possíveis erros

STATUS 400

**Lote sem ativos inseridos**

Você tentou encerrar a inserção de ativos, mas o lote ainda não possui nenhum ativo. É necessário [inserir pelo menos um ativo](/documentation/iaas/negociacao_recebiveis/asset/criacao_co) antes de fechar o lote.

```json
{
  "title": "Cannot Close This Assignment",
  "description": "Cannot close this assignment because there is no asset.",
  "translation": "Não é possível fechar este lote porque não há nenhum ativo.",
  "code": "TRC000042"
}
```

## Próximos passos

Após encerrar a inserção, o fluxo segue automaticamente:

1. **Elegibilidade dos ativos** — cada ativo será analisado individualmente. Você receberá [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 será avaliada. O resultado será informado via [webhook do lote](/documentation/iaas/negociacao_recebiveis/assignment/webhooks).
3. **[Aprovação do gestor](/documentation/iaas/negociacao_recebiveis/assignment/aprovacao)** — caso o lote seja aprovado na elegibilidade, o gestor do fundo deverá aprová-lo.

---

# 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 determinada classe de fundo. Utilize os filtros disponíveis para buscar lotes por data, status ou combinações de status.

:::info Endpoint por classe de fundo
Diferente dos demais endpoints de lote, este utiliza apenas a `fund_class_key` na URL — não é necessário informar a `assignment_configuration_key`. Isso permite listar lotes de todas as configurações de cessão de um fundo de uma vez.
:::

## Request

ENDPOINT /trade_receivables/fund_class/{fund_class_key}/assignments
MÉTODO GET

### Query params

| Parâmetro | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `assignment_date` | string | opcional | Filtra por data da cessão no formato `YYYY-MM-DD`. |
| `assignment_status` | string | opcional | Filtra por um status específico do lote. |
| `in_status` | array | opcional | Lista de status para **incluir** na busca. Retorna apenas lotes que estejam em um dos status informados. |
| `not_in_status` | array | opcional | Lista de status para **excluir** da busca. Retorna apenas lotes que **não** estejam nos status informados. |
| `assignor_document_number` | string | opcional | Filtra por número de documento (CPF/CNPJ) do cedente. Deve ser enviado **com pontuação** (ex: `12.345.678/0001-90` ou `123.456.789-00`). |
| `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`. |

```python 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"
{
  "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",
        "validation_configuration_key": "v1w2x3y4-z5a6-7890-abcd-ef1234567890",
        "assignment_configuration_name": "Config CCB Fundo Alpha",
        "assignment_contract_key": "k1l2m3n4-o5p6-7890-abcd-ef1234567890",
        "registry_type": "internal_registry",
        "asset_type": "ccb",
        "assignment_configuration_type": "standard",
        "consultant_decision_type": "manual_approval",
        "asset_fees": null,
        "assignment_reports": null,
        "fund_class": {
          "fund_class_key": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
          "name": "Fundo Alpha FIDC",
          "document_number": "12.345.678/0001-90",
          "accounting_date": "2024-04-01",
          "manager": {
            "manager_key": "e1f2a3b4-c5d6-7890-abcd-ef1234567890",
            "document_number": "11.222.333/0001-44",
            "manager_name": "Gestora Exemplo S.A."
          }
        },
        "assignor": {
          "assignor_key": "c1d2e3f4-a5b6-7890-abcd-ef1234567890",
          "document_number": "98.765.432/0001-10",
          "name": "Cedente Exemplo Ltda"
        },
        "consultant": {
          "consultant_key": "g1h2i3j4-k5l6-7890-abcd-ef1234567890",
          "document_number": "55.666.777/0001-88",
          "name": "Consultoria Exemplo Ltda"
        },
        "originator_bonds": [
          {
            "originator": {
              "originator_key": "h1i2j3k4-l5m6-7890-abcd-ef1234567890",
              "document_number": "22.333.444/0001-55",
              "name": "Originadora Exemplo Ltda"
            }
          }
        ],
        "webhook_configuration_bonds": [
          {
            "webhook_configuration_bond": {
              "webhook_configuration_key": "w1x2y3z4-a5b6-7890-abcd-ef1234567890",
              "agent_type": "assignor",
              "agent_key": "c1d2e3f4-a5b6-7890-abcd-ef1234567890"
            },
            "signature_key": "s1t2u3v4-w5x6-7890-abcd-ef1234567890",
            "webhook_url": "https://partner.example.com/webhooks/trade_receivables"
          }
        ]
      },
      "assignment_number": "00012345",
      "assignment_date": "2024-04-01",
      "status": "completed",
      "assignment_term_key": "b1c2d3e4-f5a6-7890-abcd-ef1234567890",
      "disbursement": {
        "target_account": {
          "account_key": "d1e2f3a4-b5c6-7890-abcd-ef1234567890",
          "account_type": "checking_account",
          "account_branch": "001",
          "account_number": "12345",
          "account_digit": "4",
          "financial_institution_code": "341",
          "financial_institution_ispb": "60701190",
          "owner": {
            "document_number": "98.765.432/0001-10"
          }
        }
      },
      "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 | Lista de objetos de lote 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 lote (objetos dentro de `data`)

Cada objeto do array possui a mesma estrutura retornada pelo endpoint de [Recuperação do Lote](/documentation/iaas/negociacao_recebiveis/assignment/recuperacao), com exceção do campo `status_events` que **não é retornado** na listagem.

| 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_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 a [tabela de status](#enumeradores-de-status-do-lote) abaixo. |
| `origin_type` | string | Origem do lote (ex: `client`). |
| `assignment_term_key` | string | Chave do Termo de Cessão (UUID). Disponível após geração do termo. |
| `assignment_total_value` | number | Valor total da cessão em reais. Pode não estar presente se ainda não foi calculado. |
| `assignment_irr` | number | Taxa interna de retorno (TIR) do lote. Pode não estar presente se ainda não foi calculada. |
| `assignment_configuration` | object | Dados da configuração de cessão associada ao lote. Consulte os [atributos de `assignment_configuration`](/documentation/iaas/negociacao_recebiveis/assignment/recuperacao#atributos-de-assignment_configuration) na página de Recuperação. |
| `disbursement` | object \| null | Dados da conta de desembolso (quando aplicável). |
| `assignor_discounts` | array | Lista de descontos do cedente. Presente apenas quando existem descontos configurados. Consulte os [atributos de `assignor_discounts`](/documentation/iaas/negociacao_recebiveis/assignment/recuperacao#atributos-de-assignor_discounts) na página de Recuperação. |

## Enumeradores de status do lote

| Status | Descrição |
|---|---|
| `pending_assets_insertion` | Lote criado, aguardando inserção de ativos |
| `completed_assets_insertion` | Inserção de ativos encerrada, aguardando elegibilidade |
| `pending_eligibility` | Em análise de elegibilidade |
| `pending_consultant_approval` | Aguardando aprovação do consultor |
| `pending_manager_approval` | Aguardando aprovação do gestor |
| `pending_assets_registry` | Aguardando registro dos ativos |
| `pending_assignment_term` | Aguardando geração do Termo de Cessão |
| `pending_assignment_term_signature` | Aguardando assinatura do Termo de Cessão |
| `pending_custody` | Aguardando custódia |
| `pending_payment` | Aguardando pagamento ao cedente |
| `pending_assets_wallet_inclusion` | Aguardando encarteiramento dos ativos |
| `completed` | Cessão finalizada com sucesso |
| `denied` | Lote reprovado na elegibilidade |
| `discarded` | Lote descartado |

---

# 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 informações da configuração, status atual, histórico de eventos, dados de desembolso e valores financeiros.

:::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 o gestor já aprovou, ou se o pagamento foi realizado.
:::

## 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

```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": "v1w2x3y4-z5a6-7890-abcd-ef1234567890",
    "assignment_configuration_name": "Config CCB Fundo Alpha",
    "assignment_contract_key": "k1l2m3n4-o5p6-7890-abcd-ef1234567890",
    "registry_type": "internal_registry",
    "asset_type": "ccb",
    "assignment_configuration_type": "standard",
    "consultant_decision_type": "manual_approval",
    "asset_fees": null,
    "assignment_reports": null,
    "fund_class": {
      "fund_class_key": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
      "name": "Fundo Alpha FIDC",
      "document_number": "12.345.678/0001-90",
      "accounting_date": "2024-04-01",
      "manager": {
        "manager_key": "e1f2a3b4-c5d6-7890-abcd-ef1234567890",
        "document_number": "11.222.333/0001-44",
        "manager_name": "Gestora Exemplo S.A."
      }
    },
    "assignor": {
      "assignor_key": "c1d2e3f4-a5b6-7890-abcd-ef1234567890",
      "document_number": "98.765.432/0001-10",
      "name": "Cedente Exemplo Ltda"
    },
    "consultant": {
      "consultant_key": "g1h2i3j4-k5l6-7890-abcd-ef1234567890",
      "document_number": "55.666.777/0001-88",
      "name": "Consultoria Exemplo Ltda"
    },
    "originator_bonds": [
      {
        "originator": {
          "originator_key": "h1i2j3k4-l5m6-7890-abcd-ef1234567890",
          "document_number": "22.333.444/0001-55",
          "name": "Originadora Exemplo Ltda"
        }
      }
    ],
    "webhook_configuration_bonds": [
      {
        "webhook_configuration_bond": {
          "webhook_configuration_key": "w1x2y3z4-a5b6-7890-abcd-ef1234567890",
          "agent_type": "assignor",
          "agent_key": "c1d2e3f4-a5b6-7890-abcd-ef1234567890"
        },
        "signature_key": "s1t2u3v4-w5x6-7890-abcd-ef1234567890",
        "webhook_url": "https://partner.example.com/webhooks/trade_receivables"
      }
    ]
  },
  "assignment_number": "00012345",
  "assignment_date": "2024-04-01",
  "status": "completed",
  "origin_type": "client",
  "assignment_term_key": "b1c2d3e4-f5a6-7890-abcd-ef1234567890",
  "disbursement": {
    "target_account": {
      "account_key": "d1e2f3a4-b5c6-7890-abcd-ef1234567890",
      "account_type": "checking_account",
      "account_branch": "001",
      "account_number": "12345",
      "account_digit": "4",
      "financial_institution_code": "341",
      "financial_institution_ispb": "60701190",
      "owner": {
        "document_number": "98.765.432/0001-10"
      }
    }
  },
  "assignment_total_value": 150000.00,
  "assignment_irr": 0.0215,
  "assignor_discounts": [
    {
      "assignor_discount_key": "ad12e3f4-a5b6-7890-abcd-ef1234567890",
      "assignor_discount_type": "flat_rate",
      "status": "approved",
      "total_value": 500.00,
      "description": "Taxa de administração"
    }
  ],
  "status_events": [
    {
      "status": "pending_assets_insertion",
      "event_datetime": "2024-04-01 10:00:00"
    },
    {
      "status": "completed_assets_insertion",
      "event_datetime": "2024-04-01 11:30:00"
    },
    {
      "status": "pending_eligibility",
      "event_datetime": "2024-04-01 11:35:00"
    },
    {
      "status": "completed",
      "event_datetime": "2024-04-01 16:00:00",
      "selected_agent": {
        "AGENT-TYPE": "manager",
        "AGENT-KEY": "e1f2a3b4-c5d6-7890-abcd-ef1234567890",
        "AGENT-USER": "gestor@exemplo.com"
      }
    }
  ]
}
```

### 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 sequencial 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](/documentation/iaas/negociacao_recebiveis/assignment/listagem#enumeradores-de-status-do-lote) para todos os valores possíveis. |
| `assignment_term_key` | string | Chave do Termo de Cessão (UUID). Disponível após a geração do termo. |
| `assignment_total_value` | number | Valor total da cessão em reais. Disponível após a aprovação. Pode não estar presente se ainda não foi calculado. |
| `assignment_irr` | number | Taxa interna de retorno (TIR) do lote. Pode não estar presente se ainda não foi calculada. |
| `assignment_configuration` | object | Dados completos da configuração de cessão. Veja tabela abaixo. |
| `disbursement` | object \| null | Dados da conta de desembolso. `null` quando ainda não configurada. |
| `assignor_discounts` | array | Lista de descontos do cedente. Presente apenas quando existem descontos configurados. Veja tabela abaixo. |
| `status_events` | array | Histórico de transições de status do lote. Veja tabela abaixo. |

#### Atributos de `assignment_configuration`

| Campo | Tipo | Descrição |
|---|---|---|
| `assignment_configuration_key` | string | Chave da configuração (UUID). |
| `validation_configuration_key` | string | Chave da configuração de validação (UUID). |
| `assignment_configuration_name` | string | Nome da configuração de cessão. |
| `assignment_contract_key` | string | Chave do contrato de cessão (UUID). |
| `registry_type` | string | Tipo de registro dos ativos (ex: `internal_registry`, `external_registry`). |
| `asset_type` | string | Tipo de ativo aceito nesta configuração (ex: `ccb`, `duplicata_mercantil`, `duplicata_servico`). |
| `assignment_configuration_type` | string | Tipo da configuração de cessão (ex: `standard`). |
| `consultant_decision_type` | string | Tipo de decisão do consultor (ex: `manual_approval`, `auto_approval`). |
| `asset_fees` | object \| null | Configuração de taxas dos ativos, quando aplicável. |
| `assignment_reports` | object \| null | Configuração de relatórios da cessão, quando aplicável. |
| `fund_class` | object | Dados do fundo cessionário. Veja tabela abaixo. |
| `assignor` | object | Dados do cedente. Veja tabela abaixo. |
| `consultant` | object | Dados do consultor. Presente quando a configuração possui consultor vinculado. Veja tabela abaixo. |
| `originator_bonds` | array | Lista de originadores vinculados à configuração. Veja tabela abaixo. |
| `webhook_configuration_bonds` | array | Lista de configurações de webhook vinculadas. Veja tabela abaixo. |

#### Atributos de `fund_class`

| Campo | Tipo | Descrição |
|---|---|---|
| `fund_class_key` | string | Chave única do fundo (UUID). |
| `name` | string | Nome do fundo. |
| `document_number` | string | CNPJ do fundo. |
| `accounting_date` | string | Data contábil vigente do fundo no formato `YYYY-MM-DD`. |
| `manager` | object | Dados do gestor do fundo. Veja tabela abaixo. |

#### Atributos de `manager`

| Campo | Tipo | Descrição |
|---|---|---|
| `manager_key` | string | Chave única do gestor (UUID). |
| `document_number` | string | CNPJ do gestor. |
| `manager_name` | string | Nome do gestor. |

#### Atributos de `assignor`

| Campo | Tipo | Descrição |
|---|---|---|
| `assignor_key` | string | Chave única do cedente (UUID). |
| `document_number` | string | CPF/CNPJ do cedente. |
| `name` | string | Nome do cedente. |

#### Atributos de `consultant`

| Campo | Tipo | Descrição |
|---|---|---|
| `consultant_key` | string | Chave única do consultor (UUID). |
| `document_number` | string | CNPJ do consultor. |
| `name` | string | Nome do consultor. |

#### Atributos de `originator_bonds`

| Campo | Tipo | Descrição |
|---|---|---|
| `originator` | object | Dados do originador. |
| `originator.originator_key` | string | Chave única do originador (UUID). |
| `originator.document_number` | string | CNPJ do originador. |
| `originator.name` | string | Nome do originador. |

#### Atributos de `webhook_configuration_bonds`

| Campo | Tipo | Descrição |
|---|---|---|
| `webhook_configuration_bond` | object | Dados da configuração de webhook. |
| `webhook_configuration_bond.webhook_configuration_key` | string | Chave única da configuração de webhook (UUID). |
| `webhook_configuration_bond.agent_type` | string | Tipo do agente que receberá o webhook (ex: `assignor`, `manager`, `consultant`). |
| `webhook_configuration_bond.agent_key` | string | Chave do agente vinculado. |
| `signature_key` | string | Chave de assinatura para validação do webhook (UUID). |
| `webhook_url` | string | URL de destino do webhook. |

#### Atributos de `assignor_discounts`

| Campo | Tipo | Descrição |
|---|---|---|
| `assignor_discount_key` | string | Chave única do desconto (UUID). |
| `assignor_discount_type` | string | Tipo de desconto do cedente (ex: `flat_rate`). |
| `status` | string | Status do desconto (ex: `approved`, `pending`). |
| `total_value` | number | Valor total do desconto em reais. |
| `description` | string | Descrição do desconto. |

#### Atributos de `status_events`

| Campo | Tipo | Descrição |
|---|---|---|
| `status` | string | Status do evento. |
| `event_datetime` | string | Data e hora do evento no formato `YYYY-MM-DD HH:MM:SS`. |
| `selected_agent` | object | Dados do agente responsável pela transição. Presente apenas quando a transição foi feita por um agente identificado. |

---

# 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 dos Documentos

Para cada ativo aprovado na elegibilidade individual, envie os documentos exigidos pelo produto (contrato, nota fiscal, etc.). O ativo só prossegue na esteira após todos os documentos exigidos serem enviados.

**[Acessar documentação do envio de documentos](/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 do Gestor

Após a elegibilidade do lote ser aprovada, o gestor do fundo analisa e aprova ou reprova o lote. 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).

---

# 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 o parceiro integrador sobre mudanças de status do lote. Todos os webhooks possuem o tipo `trade_receivables.assignment_status_change` e identificam o lote pelo `assignment_external_id` fornecido na criação.

:::info Configuração de webhooks
Para receber webhooks, é necessário ter uma URL de callback configurada junto à QI Tech. Entre em contato com [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br) para configurar.
:::

## Fluxo de status do lote

O lote percorre treze status, e **todos** geram webhook. A coluna central é o caminho de sucesso, da criação do lote até o encarteiramento dos ativos; a coluna da direita concentra as saídas de recusa, que podem ocorrer na elegibilidade, na aprovação do consultor ou na aprovação do gestor.

![Fluxo de status do lote de cessão, do pending_assets_insertion até completed, com as saídas para denied e discarded](/img/diagrams/iaas-negociacao-recebiveis-assignment-webhooks.svg)

_Como ler o diagrama: **azul** = status intermediário · **verde** = cessão concluída · **vermelho** = status final de recusa ou descarte._

## Estrutura do webhook

Todos os webhooks do lote de cessão seguem a mesma estrutura:

| Campo | Tipo | Descrição |
|---|---|---|
| `webhook_type` | string | Sempre `trade_receivables.assignment_status_change`. |
| `webhook_datetime` | string | Data e hora do evento no formato ISO 8601. |
| `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 | 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. |
| `signed_term_url` | string | URL para download do Termo de Cessão assinado. Presente apenas no webhook `pending_payment` quando o termo foi assinado digitalmente. |

:::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 evento aconteceu. Assim você direciona o webhook para o fluxo certo sem precisar consultar a API para descobrir a origem do lote.
:::

```json title="Estrutura padrão do webhook"
{
    "data": {
        "assignment_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
        "assignment_new_status": "STATUS",
        "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

### Lote Criado — Aguardando Inserção de Ativos

STATUS pending_assets_insertion

Enviado quando um novo lote de cessão é criado com sucesso e está pronto para receber ativos. Este é o primeiro webhook do ciclo de vida do lote. O cedente pode inserir ativos enquanto o lote estiver neste status.

```json title="Webhook Body"
{
    "data": {
        "assignment_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
        "assignment_new_status": "pending_assets_insertion",
        "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"
}
```

---

### Inserção de Ativos Concluída

STATUS completed_assets_insertion

Enviado quando a inserção de ativos é **encerrada** pelo cedente. A partir desse momento não é mais possível adicionar ativos ao lote, que avança automaticamente para a análise de elegibilidade.

```json title="Webhook Body"
{
    "data": {
        "assignment_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
        "assignment_new_status": "completed_assets_insertion",
        "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"
}
```

---

### Em Análise de Elegibilidade

STATUS pending_eligibility

Enviado quando o lote inicia o processo de análise de elegibilidade. Todos os ativos são analisados individualmente, e o resultado agregado determina a aprovação ou reprovação do lote.

```json title="Webhook Body"
{
    "data": {
        "assignment_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
        "assignment_new_status": "pending_eligibility",
        "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"
}
```

---

### Pendente Aprovação do Consultor

STATUS pending_consultant_approval

Enviado quando o lote passa na análise de elegibilidade e está aguardando a decisão do **consultor** do fundo. Esse status ocorre quando o fluxo de aprovação configurado exige aprovação prévia do consultor antes do gestor. O consultor pode aprovar ou reprovar o lote via [Portal do Consultor](https://portal-do-consultor.fundos.qitech.com.br/).

```json title="Webhook Body"
{
    "data": {
        "assignment_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
        "assignment_new_status": "pending_consultant_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"
}
```

---

### Pendente Aprovação do Gestor

STATUS pending_manager_approval

Enviado quando o lote é **aprovado na elegibilidade** (e pelo consultor, quando aplicável) e está aguardando a decisão do gestor do fundo. O gestor deve aprovar ou reprovar o lote via [Aprovação do Gestor](/documentation/iaas/negociacao_recebiveis/assignment/aprovacao) ou pelo [Portal do Gestor](https://portal-do-gestor.fundos.qitech.com.br/).

```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"
}
```

---

### Aguardando Formalização dos Ativos

STATUS waiting_assets_to_formalize

Enviado quando o gestor **aprova** o lote e o sistema aguarda a conclusão da formalização (registro) de todos os ativos aprovados. O lote permanece neste status até que todos os ativos concluam o processo de registro.

```json title="Webhook Body"
{
    "data": {
        "assignment_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
        "assignment_new_status": "waiting_assets_to_formalize",
        "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"
}
```

---

### Aguardando Geração do Termo de Cessão

STATUS pending_assignment_term

Enviado quando todos os ativos foram formalizados e o sistema está **gerando o Termo de Cessão**. O lote aguarda a conclusão da geração do documento antes de encaminhá-lo para assinatura.

```json title="Webhook Body"
{
    "data": {
        "assignment_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
        "assignment_new_status": "pending_assignment_term",
        "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"
}
```

---

### Pendente Assinatura do Termo

STATUS pending_assignment_term_signature

Enviado após a aprovação do gestor, quando o Termo de Cessão foi gerado e encaminhado para assinatura de todas as partes envolvidas. Você pode consultar o documento via [Documentos da Cessão](/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_assignment_term_signature",
        "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"
}
```

---

### Pendente Pagamento

STATUS pending_payment

Enviado após o Termo de Cessão ter sido assinado por todas as partes. O sistema irá realizar o pagamento ao cedente na conta configurada. O valor total é a soma dos `total_purchase_value` de todos os ativos não descartados do lote.

```json title="Webhook Body"
{
    "data": {
        "assignment_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
        "assignment_new_status": "pending_payment",
        "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"
}
```

---

### Aguardando Encarteiramento dos Ativos

STATUS pending_assets_wallet_inclusion

Enviado após a confirmação do pagamento ao cedente, quando os ativos estão sendo **encarteirados** na carteira do fundo. O sistema processa a inclusão dos ativos no estoque do fundo.

```json title="Webhook Body"
{
    "data": {
        "assignment_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
        "assignment_new_status": "pending_assets_wallet_inclusion",
        "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"
}
```

---

### Cessão Completa

STATUS completed

Enviado quando todos os ativos do lote foram **encarteirados** na carteira do fundo. A partir desse momento, os ativos já se encontram dentro do estoque do fundo. Este é o status final de uma cessão bem-sucedida.

```json title="Webhook Body"
{
    "data": {
        "assignment_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
        "assignment_new_status": "completed",
        "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"
}
```

---

### Reprovado na Elegibilidade

STATUS denied

Enviado quando o lote é **reprovado** na análise de elegibilidade ou pelo gestor/consultor do fundo. O lote ainda pode ser manipulado, porém caso nada aconteça ele será descartado.

```json title="Webhook Body"
{
    "data": {
        "assignment_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
        "assignment_new_status": "denied",
        "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"
}
```

---

### Lote Descartado

STATUS discarded

Enviado quando o lote é descartado. Isso pode ocorrer por reprovação na elegibilidade, reprovação do gestor, ou por problemas no registro dos ativos. O lote não seguirá adiante no fluxo.

```json title="Webhook Body"
{
    "data": {
        "assignment_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
        "assignment_new_status": "discarded",
        "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"
}
```

---

# 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ê receberá.
:::

{`
.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)
Gestor do Fundo
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 de Documentos
Agente Integrador
Envia os documentos exigidos para cada ativo (PDF em Base64). Duplicatas mercantis não exigem documentos.
Lote: pending_assets_insertion
Ativo: pending_eligibility
POST /trade_receivables/.../asset/{asset_external_id}/document
Envie os documentos após receber o webhook pending_documentation para o ativo (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: pre_approved / denied
Webhook: asset_status_change
Ativo aprovado
pre_approved
O ativo foi pré-aprovado na elegibilidade.
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_manager_approval / denied

Webhook: assignment_status_change
Lote elegível
pending_manager_approval
O lote aguarda a aprovação do gestor do fundo (passo 6).
Lote reprovado
denied
O lote causa desenquadramento do fundo. 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 do Gestor
Gestor do Fundo
O gestor do fundo analisa e aprova ou reprova o lote (via API ou pelo Portal do Gestor). Se aprovado, o Termo de Cessão é gerado automaticamente.
Lote: pending_assignment_term_signature
Webhook: assignment_status_change
PUT /trade_receivables/.../assignment/{assignment_external_id}
Endpoint disponível somente para gestores. Envie {"assignment_status": "approved"} ou "denied" . Após aprovação, você recebe o webhook com status pending_assignment_term_signature .
Ver documentação completa →

7
Assinatura do Termo de Cessão
QI Tech
O Termo de Cessão é gerado e encaminhado para assinatura. Todas as partes relacionadas precisam assinar o termo para que o fluxo prossiga. O integrador pode consultar o documento a qualquer momento.
Lote: pending_payment
Webhook: assignment_status_change
GET /trade_receivables/.../assignment/{assignment_external_id}/assignment_term_link
Consulte o Termo de Cessão (original e assinado). 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 é realizado automaticamente ao cedente na conta configurada durante a homologação.
Lote: pending_assets_wallet_inclusion
Webhook: assignment_status_change
O valor total é a soma dos total_purchase_value de todos os ativos não descartados. 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` | `pre_approved` | Ativo aprovado na elegibilidade (passo 5a) | Nenhuma — ativo pré-aprovado. |
| 3 | `asset_status_change` | `denied` | Ativo reprovado na elegibilidade (passo 5a) | Nenhuma — ativo não segue adiante. |
| 4 | `assignment_status_change` | `pending_manager_approval` | Lote aprovado na elegibilidade (passo 5b) | Aguardar [aprovação do gestor](/documentation/iaas/negociacao_recebiveis/assignment/aprovacao). |
| 5 | `assignment_status_change` | `denied` | Lote reprovado na elegibilidade (passo 5b) | Nenhuma — fluxo encerrado. |
| 6 | `assignment_status_change` | `pending_assignment_term_signature` | Gestor aprovou o lote (passo 6) | Opcional: [consultar Termo de Cessão](/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` | Qualquer momento (reprovação/erro) | 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).
:::

---

# 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 CTVM. 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 Homologação (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, contratos descontados e CT-e, ou **CSV** para CCB, honorários advocatícios e contratos parcelados | Portal do gestor/consultor |

:::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.

<FlowDiagram
  columns={3}
  nodes={[
    { id: 'criacao', row: 1, col: 2, actor: 'you', num: 1,
      title: 'Criação do Lote',
      status: 'pending_assets_insertion',
      desc: 'Contêiner de todos os ativos que serão cedidos ao fundo, identificado por um external_id único.',
      endpoint: { method: 'POST', path: '/trade_receivables/fund_class/{fund_class_key}/assignment_configuration/{assignment_configuration_key}/assignment' },
      href: '/documentation/iaas/negociacao_recebiveis/assignment/criacao' },

    { id: 'ativos', row: 2, col: 2, actor: 'you', num: 2,
      title: 'Inserção dos Ativos',
      status: 'ativo: pending_eligibility',
      desc: 'Uma requisição por ativo, com as informações de operação, parcelas e dados do sacado.',
      endpoint: { method: 'POST', path: '.../assignment/{assignment_external_id}/asset' },
      href: '/documentation/iaas/negociacao_recebiveis/asset/criacao_co' },

    { id: 'documentos', row: 3, col: 2, actor: 'you', num: 3,
      title: 'Envio dos Documentos',
      desc: 'O ativo só prossegue na esteira depois que todos os documentos exigidos pelo produto são enviados.',
      endpoint: { method: 'POST', path: '.../asset/{asset_external_id}/document' },
      href: '/documentation/iaas/negociacao_recebiveis/asset/documents' },

    { id: 'fechamento', row: 4, col: 2, actor: 'you', num: 4,
      title: 'Encerramento da Inserção',
      status: 'completed_assets_insertion',
      desc: 'Sinaliza que todos os ativos foram inseridos e libera o lote para a análise de elegibilidade.',
      endpoint: { method: 'PUT', path: '.../assignment/{assignment_external_id}' },
      href: '/documentation/iaas/negociacao_recebiveis/assignment/fechamento' },

    { id: 'elegibilidade', row: 5, col: 2, actor: 'qitech',
      title: 'Elegibilidade dos ativos e do lote',
      desc: 'Cada ativo é analisado individualmente e, em seguida, o lote como um todo. Ativos reprovados não seguem no lote.',
      href: '/documentation/iaas/negociacao_recebiveis/asset/webhooks' },

    { id: 'reprovado', row: 6, col: 1, actor: 'qitech', tone: 'end',
      title: 'Reprovado',
      status: 'denied',
      desc: 'O ativo ou o lote não passou na elegibilidade, ou o gestor reprovou o lote. Fluxo encerrado.' },

    { id: 'aprovacao', row: 6, col: 2, actor: 'manager', tag: 'Condicional', num: 5,
      title: 'Aprovação do consultor e/ou gestor',
      status: 'pending_manager_approval',
      desc: 'Etapa manual apenas se a configuração de cessão exigir. Caso contrário a aprovação é automática e nenhuma ação é necessária.',
      endpoint: { method: 'PUT', path: '.../assignment/{assignment_external_id}' },
      href: '/documentation/iaas/negociacao_recebiveis/assignment/aprovacao' },

    { id: 'termo', row: 7, col: 2, actor: 'qitech',
      title: 'Termo de Cessão gerado e assinado',
      status: 'pending_assignment_term_signature',
      desc: 'Com o lote aprovado, o Termo de Cessão é gerado e assinado pelas partes.',
      href: '/documentation/iaas/negociacao_recebiveis/assignment/webhooks' },

    { id: 'pagamento', row: 8, col: 2, actor: 'qitech',
      title: 'Pagamento ao cedente',
      status: 'pending_payment',
      desc: 'O valor da cessão é repassado ao cedente.',
      href: '/documentation/iaas/negociacao_recebiveis/assignment/webhooks' },

    { id: 'encarteirado', row: 9, col: 2, actor: 'qitech', tone: 'ok',
      title: 'Ativos encarteirados no fundo',
      status: 'completed',
      desc: 'Os ativos entram na carteira do fundo e o ciclo do lote se encerra.',
      href: '/documentation/iaas/negociacao_recebiveis/assignment/webhooks' },
  ]}
  edges={[
    { from: 'criacao', to: 'ativos' },
    { from: 'ativos', to: 'documentos' },
    { from: 'documentos', to: 'fechamento' },
    { from: 'fechamento', to: 'elegibilidade' },
    { from: 'elegibilidade', to: 'reprovado', label: 'denied', tone: 'end' },
    { from: 'elegibilidade', to: 'aprovacao', label: 'pre_approved', tone: 'ok' },
    { from: 'elegibilidade', to: 'termo', label: 'automática', via: 'right', dashed: true },
    { from: 'aprovacao', to: 'reprovado', tone: 'end' },
    { from: 'aprovacao', to: 'termo', label: 'aprovou', tone: 'ok' },
    { from: 'termo', to: 'pagamento', label: 'webhook' },
    { from: 'pagamento', to: 'encarteirado', label: 'webhook' },
  ]}
/>

:::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.

**[Acessar documentação da inserção de ativos](/documentation/iaas/negociacao_recebiveis/asset/criacao_co)**

### 3. Envio dos Documentos

Para cada ativo inserido, envie os documentos exigidos pelo produto (contrato, nota fiscal, etc.). O ativo só prossegue na esteira após todos os documentos exigidos serem enviados.

**[Acessar documentação do envio de documentos](/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 do Gestor

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).

## Lotes de substituição

O fluxo de substituição segue as mesmas etapas do fluxo de cessão, com um passo adicional: antes de inserir os ativos que serão comprados, é necessário inserir os ativos que serão **recomprados** pelo cedente.

1. Criação do lote
2. **Inserção dos ativos de recompra** — [Acessar documentação](/documentation/iaas/negociacao_recebiveis/asset/criacao_repurchased_asset)
3. Inserção dos ativos que serão comprados
4. Encerramento da inserção

---

# 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 vinculadas a uma determinada classe de fundo. Cada configuração representa a relação entre um fundo cessionário e um cedente, incluindo regras de registro, tipo de ativo aceito e aprovação.

## 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

| Parâmetro | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `assignment_contract_key` | string | opcional | Filtra por chave do contrato que originou a configuração (UUID). |
| `asset_type` | string | opcional | Filtra por tipo de ativo aceito na configuração (ex: `ccb`, `duplicata_mercantil`, `duplicata_servicos`). |
| `assignor_document_number` | string | opcional | Filtra por CPF/CNPJ do cedente. Deve ser enviado **com pontuação** (ex: `12.345.678/0001-90` ou `123.456.789-00`). |
| `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: `10`. |

```python title="Exemplo de chamada"
GET /trade_receivables/fund_class/{fund_class_key}/assignment_configurations?asset_type=ccb&assignor_document_number=98.765.432/0001-10&page=0&limit=10
```

## Response

STATUS 200

```json title="Response Body"
{
  "data": [
    {
      "assignment_configuration_key": "3571e292-3a83-4011-904d-20ee963022ef",
      "assignment_configuration_name": "Config CCB Fundo Alpha",
      "assignment_contract_key": "k1l2m3n4-o5p6-7890-abcd-ef1234567890",
      "registry_type": "internal_registry",
      "asset_type": "ccb",
      "fund_class": {
        "fund_class_key": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
        "name": "Fundo Alpha FIDC",
        "document_number": "12.345.678/0001-90",
        "accounting_date": "2024-04-01",
        "manager": {
          "manager_key": "e1f2a3b4-c5d6-7890-abcd-ef1234567890",
          "document_number": "11.222.333/0001-44",
          "manager_name": "Gestora Exemplo S.A."
        }
      },
      "assignor": {
        "assignor_key": "c1d2e3f4-a5b6-7890-abcd-ef1234567890",
        "document_number": "98.765.432/0001-10",
        "name": "Cedente Exemplo Ltda"
      },
      "consultant_decision_type": "manual_approval",
      "consultant": {
        "consultant_key": "g1h2i3j4-k5l6-7890-abcd-ef1234567890",
        "document_number": "55.666.777/0001-88",
        "name": "Consultoria Exemplo Ltda"
      }
    }
  ],
  "limit": 10,
  "page": 0,
  "is_last_page": true
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `data` | array | Lista de objetos de configuração 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 configuração (objetos dentro de `data`)

| 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 de cessão. |
| `assignment_contract_key` | string | Chave do contrato de cessão que originou esta configuração (UUID). |
| `registry_type` | string | Tipo de registro dos ativos. Valores possíveis: `internal_registry`, `external_registry`. |
| `asset_type` | string | Tipo de ativo aceito nesta configuração. Valores possíveis: `ccb`, `duplicata_mercantil`, `duplicata_servico`. |
| `consultant_decision_type` | string | Tipo de decisão do consultor sobre a elegibilidade. Valores possíveis: `automatic_approval`, `manual_approval`. |
| `fund_class` | object | Dados do fundo cessionário. Consulte os [atributos de `fund_class`](/documentation/iaas/negociacao_recebiveis/assignment/recuperacao#atributos-de-fund_class) na página de Recuperação. |
| `assignor` | object | Dados do cedente. Consulte os [atributos de `assignor`](/documentation/iaas/negociacao_recebiveis/assignment/recuperacao#atributos-de-assignor) na página de Recuperação. |
| `consultant` | object | Dados do consultor vinculado à configuração. Consulte os [atributos de `consultant`](/documentation/iaas/negociacao_recebiveis/assignment/recuperacao#atributos-de-consultant) na página de Recuperação. |
| `required_documents` | array | Tipos de documento exigidos **antes** da cessão, enviados pelo [endpoint de documentos](/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. |