# QI Tech — Investment-as-a-Service › Aditamento de contratos

Documentação da QI Tech em texto corrido, para colar em um LLM.
Fonte: https://docs.qitech.com.br
3 página(s).

Índice:
- Inserção de documentos (/documentation/iaas/aditamento_recebiveis/envio_documento)
- Introdução (/documentation/iaas/aditamento_recebiveis/inicio)
- Criação de pedido de aditamento (/documentation/iaas/aditamento_recebiveis/pedido_aditamento_contrato)

---

# Inserção de documentos

URL: /documentation/iaas/aditamento_recebiveis/envio_documento

Envia o termo de aditamento de um aditamento em `pending_document`. Com o documento recebido, o aditamento passa para `pending_approval`.

Só é aceito quando a esteira de aditamento exige documento (`amendment_configuration.requires_document: true`). Em esteira sem exigência de documento, a API devolve `AAM000038`.

:::info Disponível em

| Perfil      | Host             | Permissão exigida                                |
| ----------- | ---------------- | ------------------------------------------------ |
| Consultoria | `consultant-api` | Lotes   |
| Cedente     | `assignor-api`   | Escrita |

URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts).

:::

:::caution Gestora

A `manager-api` não expõe este endpoint. Veja o que fazer com um aditamento da gestora parado em `pending_document` em [Criação de pedido de aditamento](/documentation/iaas/aditamento_recebiveis/pedido_aditamento_contrato).

:::

## Request

ENDPOINT /asset_amendment/fund_class/FUND_CLASS_KEY/amendment_configuration/AMENDMENT_CONFIGURATION_KEY/asset_amendment/ASSET_AMENDMENT_KEY/document
MÉTODO POST

```json title='Request Body'
{
    "document_type": "amendment_term",
    "document_b64": "JVBERi0xLjQKJcOkw7zDtsOfCjIgMCBvYmoKPDwvTGVuZ3RoIDMgMCBSPj4Kc3RyZWFtCg=="
}
```

### Body Params

| Campo | Tipo | Descrição |
|-|-|-|
| `document_type` * | string | Tipo do documento. Único valor aceito: `amendment_term` |
| `document_b64` * | string | Arquivo PDF do termo de aditamento, codificado em Base64 |

## Response

STATUS 201

A resposta é o aditamento atualizado, no mesmo formato da [criação do pedido](/documentation/iaas/aditamento_recebiveis/pedido_aditamento_contrato#response).

```json title='Response Body'
{
    "asset_amendment_key": "a914aac6-93ff-45ee-8574-f4dbaf6c0642",
    "status": "pending_approval",
    "amendment_type": "all_contract",
    "amendment_configuration": {
        "amendment_configuration_key": "5f0d3a52-8c1e-4b8e-9a51-2f6a8f0c1d22",
        "fund_class": {
            "fund_class_key": "<fund_class_key>",
            "document_number": "11.222.333/0001-81",
            "name": "FUNDO EXEMPLO FIDC",
            "manager": {
                "manager_key": "<manager_key>",
                "document_number": "22.333.444/0001-81",
                "manager_name": "GESTORA EXEMPLO LTDA"
            },
            "accounting_date": "2024-04-01"
        },
        "requires_document": true
    },
    "asset_type": "ccb",
    "asset_key": "0b6f6c55-5d1b-4b6e-8f3a-6c1f0f7f2b10",
    "amendment_date": "2024-04-01",
    "asset_external_id": "931e9437-d025-41ab-bb53-6b94e10fd361",
    "source": "api_integration",
    "status_history": [
        {
            "status": "pending_document",
            "event_datetime": "2024-04-01T13:02:45Z"
        },
        {
            "status": "pending_approval",
            "event_datetime": "2024-04-01T13:10:02Z"
        }
    ]
}
```

## Erros

| Status | Código | Quando acontece |
|-|-|-|
| 400 | `AAM000038` | A esteira de aditamento não exige documento |
| 400 | `AAM000026` | `document_type` diferente de `amendment_term` |
| 400 | `AAM000025` | `document_b64` não é um Base64 válido |
| 404 | `AAM000009` | Aditamento não encontrado para esse fundo e essa esteira |

Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros).

---

# Introdução

URL: /documentation/iaas/aditamento_recebiveis/inicio

O sistema de Aditamento de Recebíveis é uma solução que permite a modificação e atualização de contratos e acordos existentes relacionados a recebíveis. Este módulo oferece funcionalidades essenciais para:

- Realizar alterações em contratos de recebíveis já existentes
- Gerenciar modificações em condições de pagamento

Esta documentação fornece uma visão detalhada sobre como utilizar o sistema de aditamento, incluindo seus principais recursos e fluxos. Aqui você encontrará informações sobre:

- Processos de aditamento
- Endpoints e payloads

Para começar a utilizar o sistema, navegue pelos tópicos disponíveis nesta documentação para entender melhor cada aspecto do módulo de aditamento.

---

# Criação de pedido de aditamento

URL: /documentation/iaas/aditamento_recebiveis/pedido_aditamento_contrato

Para realizar um pedido de aditamento é necessário realizar uma requisição usando a chave única que representa o fundo (`fund_class_key`, fornecida pela QI Tech) e a chave única que representa a configuração da esteira de aditamento (`amendment_configuration_key`, fornecida pela QI Tech).

Nos aditamentos realizados por este sistema é permitida a alteração do fluxo de pagamento, da taxa nominal do contrato ou de ambos. Também é possível definir que o aditamento será realizado juntamente com uma entrada paga pelo devedor.

:::info Disponível em

| Perfil      | Host             | Permissão exigida                                |
| ----------- | ---------------- | ------------------------------------------------ |
| Gestora     | `manager-api`    | Escrita                                          |
| Consultoria | `consultant-api` | Lotes   |
| Cedente     | `assignor-api`   | Escrita |

URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts).

:::

## Request

ENDPOINT /asset_amendment/fund_class/FUND_CLASS_KEY/amendment_configuration/AMENDMENT_CONFIGURATION_KEY/asset_amendment
MÉTODO POST

```json title='Request Body'
{
    "asset_external_id": "931e9437-d025-41ab-bb53-6b94e10fd361",
    "asset_type": "ccb",
    "amendment_date": "2024-04-01",
    "amendment_type": "all_contract",
    "down_payment_value": 400.23,
    "installments": [
        {
            "maturity_date": "2025-01-31",
            "face_value": 1000.31,
            "installment_number": 1
        },
        {
            "maturity_date": "2025-02-28",
            "face_value": 1000.31,
            "installment_number": 2
        }
    ],
    "pre_fixed": {
        "monthly_rate": 0.02,
        "calendar_base": "workdays"
    }
}
```

### Body Params

| Campo | Tipo | Descrição | Obrigatório |
|-|-|-|-|
| `asset_external_id` | string | Identificador do contrato que está sendo aditado, o mesmo com que ele foi encarteirado. Até 50 caracteres. | Um dos dois: `asset_external_id` ou `contract_number` |
| `contract_number` | string | Número do contrato a ser aditado, alternativa ao `asset_external_id`. Até 50 caracteres. | Um dos dois: `asset_external_id` ou `contract_number` |
| `asset_type` | string | Tipo do ativo aditado: `ccb` ou `structured_cci` | Sim |
| `amendment_date` | string | Data em que o aditamento está sendo realizado (formato: YYYY-MM-DD) | Sim |
| `amendment_type` | string | Tipo de aditamento a ser realizado. Ver [Enumerador Tipo de Aditamento](#enumerador-tipo-de-aditamento) | Sim |
| `down_payment_value` | number | Valor da entrada a ser paga pelo devedor no momento do aditamento (maior ou igual a 0) | Não |
| `installments` | array | Lista de parcelas do contrato após o aditamento | Depende do `amendment_type` |
| `installments[].maturity_date` | string | Data de vencimento da parcela (formato: YYYY-MM-DD) | Sim |
| `installments[].face_value` | number | Valor nominal da parcela (maior ou igual a 0) | Sim |
| `installments[].installment_number` | integer | Número sequencial da parcela, a partir de 1 | Sim |
| `installments[].external_id` | string | Identificador da parcela no seu sistema | Não |
| `pre_fixed` | object | Configurações da taxa pré-fixada | Depende do `amendment_type` |
| `pre_fixed.monthly_rate` | number | Taxa mensal a ser aplicada | Sim |
| `pre_fixed.calendar_base` | string | Base de calendário para cálculo. Único valor aceito: `workdays` | Sim |

:::info Identificação do contrato

Envie **exatamente um** entre `asset_external_id` e `contract_number`. Sem nenhum dos dois a API devolve `AAM000041`; com os dois, `AAM000042`.

:::

## Response

STATUS 201

```json title='Response Body'
{
    "asset_amendment_key": "a914aac6-93ff-45ee-8574-f4dbaf6c0642",
    "status": "pending_document",
    "amendment_type": "all_contract",
    "amendment_configuration": {
        "amendment_configuration_key": "5f0d3a52-8c1e-4b8e-9a51-2f6a8f0c1d22",
        "fund_class": {
            "fund_class_key": "<fund_class_key>",
            "document_number": "11.222.333/0001-81",
            "name": "FUNDO EXEMPLO FIDC",
            "manager": {
                "manager_key": "<manager_key>",
                "document_number": "22.333.444/0001-81",
                "manager_name": "GESTORA EXEMPLO LTDA"
            },
            "accounting_date": "2024-04-01"
        },
        "requires_document": true
    },
    "asset_type": "ccb",
    "asset_key": "0b6f6c55-5d1b-4b6e-8f3a-6c1f0f7f2b10",
    "amendment_date": "2024-04-01",
    "asset_external_id": "931e9437-d025-41ab-bb53-6b94e10fd361",
    "source": "api_integration",
    "status_history": [
        {
            "status": "pending_document",
            "event_datetime": "2024-04-01T13:02:45Z"
        }
    ]
}
```

O status inicial depende da configuração da esteira de aditamento, definida pela QI Tech:

- **`pending_document`** — a esteira exige o termo de aditamento (`amendment_configuration.requires_document: true`, o padrão). O aditamento só avança depois do [envio do documento](/documentation/iaas/aditamento_recebiveis/envio_documento).
- **`pending_processing`** — a esteira não exige documento (`requires_document: false`). O aditamento segue direto para processamento.

:::caution Gestora e esteira que exige documento

O envio do termo de aditamento não está disponível na `manager-api`. Se a gestora cria o aditamento numa esteira que exige documento, ele fica parado em `pending_document`. Para resolver, o termo precisa ser enviado pela consultoria ou pelo cedente vinculados à esteira, ou a gestora pode pedir à QI Tech, em [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br), uma esteira de aditamento sem exigência de documento.

:::

## Enumerador Tipo de Aditamento

| Enumerador   | Descrição     |
|--------------|---------------|
| **payment_flow**   | Aditamento apenas do fluxo de pagamento |
| **nominal_rate** | Aditamento apenas da taxa nominal do contrato |
| **all_contract** | Aditamento do fluxo de pagamento e da taxa nominal do contrato |

:::caution Atenção

Os campos `installments` e `pre_fixed` devem ou não ser enviados de acordo com o tipo de aditamento, conforme a tabela abaixo. Combinação diferente devolve `AAM000008`.

:::

| Tipo de aditamento | installments | pre_fixed |
|------------------- | ------------ | --------- |
| all_contract | Obrigatório | Obrigatório |
| nominal_rate | Não deve ser enviado | Obrigatório |
| payment_flow | Obrigatório | Não deve ser enviado |

## Status do aditamento

| Status | Significado |
|-|-|
| `pending_document` | Aguardando o termo de aditamento |
| `pending_approval` | Termo recebido, aguardando aprovação |
| `pending_processing` | Em processamento |
| `pending_conciliation` | Aguardando o crédito da entrada (`down_payment_value`) na conta do fundo |
| `pending_wallet_update` | Atualizando o contrato na carteira do fundo |
| `completed` | Aditamento aplicado ao contrato |
| `denied` | Aditamento negado; o motivo vem em `denial_reason` |

## Webhook

Quando o aditamento chega a `completed` ou `denied`, a QI Tech envia o webhook `asset_amendment.status_change` à gestora do fundo e ao cedente e à consultoria vinculados à esteira, para quem tiver o webhook configurado. A configuração é feita pela QI Tech: solicite em [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br). Para validar a assinatura, veja [Autenticação de webhooks](/documentation/iaas/introducao/autenticacao_webhooks).

```json title='Webhook Body'
{
    "webhook_type": "asset_amendment.status_change",
    "webhook_datetime": "2024-04-02T10:15:00Z",
    "data": {
        "asset_amendment_key": "a914aac6-93ff-45ee-8574-f4dbaf6c0642",
        "amendment_configuration_key": "5f0d3a52-8c1e-4b8e-9a51-2f6a8f0c1d22",
        "fund_class_key": "<fund_class_key>",
        "fund_class_document_number": "11.222.333/0001-81",
        "asset_key": "0b6f6c55-5d1b-4b6e-8f3a-6c1f0f7f2b10",
        "asset_external_id": "931e9437-d025-41ab-bb53-6b94e10fd361",
        "asset_type": "ccb",
        "amendment_type": "all_contract",
        "amendment_date": "2024-04-01",
        "status": "completed",
        "down_payment_value": 400.23
    }
}
```

`down_payment_value` só vem quando o aditamento tem entrada; `denial_reason` só vem quando o status é `denied`.

## Erros

| Status | Código | Quando acontece |
|-|-|-|
| 400 | `QIT000001` | Corpo fora do contrato: campo obrigatório ausente, campo desconhecido, data inválida, valor fora do enum |
| 400 | `AAM000041` | Nem `asset_external_id` nem `contract_number` foram enviados |
| 400 | `AAM000042` | `asset_external_id` e `contract_number` foram enviados juntos |
| 400 | `AAM000008` | `installments`/`pre_fixed` incompatíveis com o `amendment_type` |
| 404 | `AAM000003` | Não existe fundo com essa `fund_class_key` |
| 404 | `AAM000024` | `amendment_configuration_key` não encontrada para o fundo |
| 404 | `AAM000006` | `asset_type` não existe |
| 404 | `AAM000007` | Nenhum ativo ativo com esse `asset_external_id` e `asset_type` na carteira do fundo |
| 404 | `AAM000043` | Nenhum ativo ativo com esse `contract_number` e `asset_type` |
| 409 | `AAM000044` | Mais de um ativo ativo com o mesmo `contract_number`: use `asset_external_id` |
| 4xx | `WLT...` ou `AAM000030` | A carteira do fundo recusou o aditamento na validação. O código e a descrição vêm da carteira; sem código da carteira, volta `AAM000030` |

Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros).