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

Índice:
- Criação de Ativo — CCB (/documentation/iaas/negociacao_recebiveis/asset/criacao_co)
- 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)

---

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

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

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

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

## 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 Duplicatas: quando enviar documentos?
Ativos do tipo **`duplicata_mercantil`** não exigem envio de documentos — a documentação é gerada automaticamente pelo sistema a partir dos dados da nota fiscal. Já ativos do tipo **`duplicata_servicos`** exigem o envio de documentos por este endpoint.
:::

:::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 |
|---|---|---|
| `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. Valores aceitos: `ccb` ou `duplicata_servicos`. |
| `document_b64` | string | obrigatório | Conteúdo do arquivo PDF codificado em Base64. |

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

## 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 diagrama abaixo ilustra as transições de status que geram webhooks ao longo do fluxo:

![Fluxo de status do ativo](/img/diagrams/iaas-negociacao-recebiveis-asset-webhooks.svg)

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

```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",
        "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",
        "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",
        "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",
        "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",
        "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",
        "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",
        "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",
        "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://manager-dash.qidtvm.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 diagrama abaixo ilustra as transições de status que geram webhooks ao longo do fluxo:

![Fluxo de status do lote de cessão](/img/diagrams/iaas-negociacao-recebiveis-assignment-webhooks.svg)

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

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

```json title="Webhook Body"
{
    "data": {
        "assignment_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
        "assignment_new_status": "pending_consultant_approval",
        "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://manager-dash.qidtvm.com.br/).

```json title="Webhook Body"
{
    "data": {
        "assignment_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
        "assignment_new_status": "pending_manager_approval",
        "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",
        "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",
        "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",
        "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",
        "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",
        "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",
        "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",
        "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",
        "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 ou contrato descontado). 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 →

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

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