# QI Tech — Investment-as-a-Service › Despesas

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

Índice:
- Consulta de despesas consolidadas (/documentation/iaas/despesas/despesa_consolidada/consulta_despesas)
- Atualização do Contrato (/documentation/iaas/despesas/submissao_despesa/contrato/atualizacao)
- Cancelamento do Contrato (/documentation/iaas/despesas/submissao_despesa/contrato/cancelamento)
- Criação do Contrato (/documentation/iaas/despesas/submissao_despesa/contrato/criacao)
- Listagem de Contratos (/documentation/iaas/despesas/submissao_despesa/contrato/listagem)
- Consulta de Contrato (/documentation/iaas/despesas/submissao_despesa/contrato/recuperacao)
- Submissão do Contrato (/documentation/iaas/despesas/submissao_despesa/contrato/submissao)
- Atualização da Despesa (/documentation/iaas/despesas/submissao_despesa/despesa/atualizacao)
- Cancelamento da Despesa (/documentation/iaas/despesas/submissao_despesa/despesa/cancelamento)
- Criação da Despesa (/documentation/iaas/despesas/submissao_despesa/despesa/criacao)
- Listagem de Despesas (/documentation/iaas/despesas/submissao_despesa/despesa/listagem)
- Consulta de Despesa (/documentation/iaas/despesas/submissao_despesa/despesa/recuperacao)
- Submissão da Despesa (/documentation/iaas/despesas/submissao_despesa/despesa/submissao)
- Listagem de Documentos (/documentation/iaas/despesas/submissao_despesa/documentos/listagem)
- Upload de Documentos (/documentation/iaas/despesas/submissao_despesa/documentos/upload)
- Fluxo de submissão de despesas (/documentation/iaas/despesas/submissao_despesa/fluxo_despesas)
- Anotações da Análise (/documentation/iaas/despesas/submissao_despesa/fornecedor/anotacoes)
- Atualização de Dados da Análise (/documentation/iaas/despesas/submissao_despesa/fornecedor/atualizacao)
- Cancelamento da Análise (/documentation/iaas/despesas/submissao_despesa/fornecedor/cancelamento)
- Cadastro de Fornecedor (/documentation/iaas/despesas/submissao_despesa/fornecedor/criacao)
- Documentos da Análise (/documentation/iaas/despesas/submissao_despesa/fornecedor/documentos)
- Consulta de Fornecedores e Análises (/documentation/iaas/despesas/submissao_despesa/fornecedor/listagem)
- Submissão para Análise (/documentation/iaas/despesas/submissao_despesa/fornecedor/submissao)
- Submissão de Despesas (/documentation/iaas/despesas/submissao_despesa/inicio)

---

# Consulta de despesas consolidadas

URL: /documentation/iaas/despesas/despesa_consolidada/consulta_despesas

Endpoints para consultar as despesas de uma classe de fundo. Existem dois modos de consulta: a **listagem paginada** de todas as despesas de uma classe de fundo, e a **consulta individual** de uma despesa específica.

:::tip Quando utilizar
Utilize estes endpoints para acompanhar o status das despesas cadastradas, verificar valores provisionados e consolidados, e consultar os dados de pagamento de cada despesa.
:::

## Listagem de despesas

Retorna a lista paginada de todas as despesas de uma classe de fundo, com suporte a diversos filtros.

### Request

ENDPOINT /expense/fund_class/{fund_class_key}/expenses
MÉTODO GET

### Query params

| Parâmetro | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `page` | integer | opcional | Número da página (começa em 0). Padrão: `0`. |
| `limit` | integer | opcional | Quantidade de registros por página. Mínimo: `0`. Máximo: `100`. Padrão: `10`. |
| `reference_date` | string | opcional | Filtra despesas pela data de referência exata, no formato `YYYY-MM-DD`. |
| `from_end_deferral_date` | string | opcional | Filtra despesas com data de encerramento de diferimento maior ou igual à data informada, no formato `YYYY-MM-DD`. |
| `to_end_deferral_date` | string | opcional | Filtra despesas com data de encerramento de diferimento menor ou igual à data informada, no formato `YYYY-MM-DD`. |
| `status` | string | opcional | Filtra pelo status da despesa. Aceita múltiplos valores separados por vírgula (ex: `paid,consolidated`). Veja [enumeradores de `status`](#enumeradores-de-status). |
| `expense_type` | string | opcional | Filtra pelo tipo da despesa. Aceita múltiplos valores separados por vírgula (ex: `management_tax,custody_tax`). Veja [enumeradores de `type`](#enumeradores-de-type). |
| `expense_status_to_ignore` | string | opcional | Exclui da listagem despesas com o status informado. |
| `expense_type_to_ignore` | string | opcional | Exclui da listagem despesas com o tipo informado. |
| `ignore_paid_on_future` | boolean | opcional | Quando `true`, exclui despesas que já foram pagas mas com data de confirmação posterior à data de referência. |

```python title="Exemplo de chamada"
GET /expense/fund_class/{fund_class_key}/expenses?page=0&limit=10&status=consolidated,paid
```

### Response

STATUS 200

```json title="Response Body"
{
    "data": [
        {
            "expense_key": "3571e292-3a83-4011-904d-20ee963022ef",
            "fund_class": {
                "name": "Fundo de Investimento XYZ",
                "manager": {
                    "name": "Gestora ABC",
                    "manager_key": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
                    "document_number": "12.345.678/0001-90"
                },
                "fund_class_key": "c1d2e3f4-a5b6-7890-abcd-ef1234567890",
                "document_number": "98.765.432/0001-10",
                "accounting_date": "2025-06-10"
            },
            "status": "consolidated",
            "type": "management_tax",
            "reference_date": "2025-06-10",
            "start_deferral_date": "2025-06-01",
            "end_deferral_date": "2025-06-30",
            "consolidated_value": 1500.00,
            "provisioned_value": 1500.00,
            "recognized_value": 1500.00,
            "payment": null,
            "expense_datetime": "2025-06-01T00:00:00Z",
            "description": "Taxa de gestão referente ao mês de junho/2025",
            "payment_method": "transfer",
            "payment_date": "2025-06-30",
            "payment_confirmation": {
                "confirmation_date": "2025-06-30"
            }
        }
    ],
    "limit": 10,
    "page": 0,
    "is_last_page": true
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `data` | array | Lista de objetos de despesa. Veja [Atributos de cada despesa](#atributos-de-cada-despesa-objetos-dentro-de-data). |
| `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 despesa (objetos dentro de `data`)

| Campo | Tipo | Descrição |
|---|---|---|
| `expense_key` | string | Identificador único da despesa (UUID). |
| `fund_class` | object | Dados da classe de fundo à qual a despesa pertence. Veja [Atributos de `fund_class`](#atributos-de-fund_class). |
| `status` | string | Status atual da despesa. Veja [enumeradores de `status`](#enumeradores-de-status). |
| `type` | string | Tipo da despesa. Veja [enumeradores de `type`](#enumeradores-de-type). |
| `reference_date` | string | Data de referência da despesa no formato `YYYY-MM-DD`. |
| `start_deferral_date` | string | Data de início do diferimento no formato `YYYY-MM-DD`. |
| `end_deferral_date` | string | Data de encerramento do diferimento no formato `YYYY-MM-DD`. |
| `consolidated_value` | number | Valor consolidado da despesa. Pode ser `null` quando a despesa ainda não foi consolidada. |
| `provisioned_value` | number | Valor provisionado da despesa. Pode ser `null` quando ainda não há provisão. |
| `recognized_value` | number | Valor reconhecido da despesa. |
| `payment` | object | Dados do pagamento associado à despesa. Pode ser `null` quando não há pagamento vinculado. |
| `expense_datetime` | string | Data e hora de criação da despesa no formato ISO 8601 (ex: `2025-06-01T00:00:00Z`). |
| `description` | string | Descrição textual da despesa. |
| `payment_method` | string | Método de pagamento da despesa. Veja [enumeradores de `payment_method`](#enumeradores-de-payment_method). |
| `payment_date` | string | Data de pagamento no formato `YYYY-MM-DD`. Presente somente quando a despesa possui data de pagamento definida. |
| `payment_confirmation` | object | Dados de confirmação de pagamento. Presente somente quando o pagamento foi confirmado. Veja [Atributos de `payment_confirmation`](#atributos-de-payment_confirmation). |

#### Atributos de `fund_class`

| Campo | Tipo | Descrição |
|---|---|---|
| `name` | string | Nome da classe de fundo. |
| `fund_class_key` | string | Identificador único da classe de fundo (UUID). |
| `document_number` | string | CNPJ da classe de fundo. |
| `accounting_date` | string | Data de contabilização da classe de fundo no formato `YYYY-MM-DD`. |
| `manager` | object | Dados do gestor responsável. Veja [Atributos de `manager`](#atributos-de-manager). |

#### Atributos de `manager`

| Campo | Tipo | Descrição |
|---|---|---|
| `name` | string | Nome do gestor. |
| `manager_key` | string | Identificador único do gestor (UUID). |
| `document_number` | string | CNPJ do gestor. |

#### Atributos de `payment_confirmation`

| Campo | Tipo | Descrição |
|---|---|---|
| `confirmation_date` | string | Data de confirmação do pagamento no formato `YYYY-MM-DD`. |

---

## Consulta de despesa específica

Retorna os dados completos de uma despesa específica de uma classe de fundo.

### Request

ENDPOINT /expense/fund_class/{fund_class_key}/expense/{expense_key}
MÉTODO GET

### Path params

| Parâmetro | Tipo | Descrição |
|---|---|---|
| `fund_class_key` | string | Identificador único (UUID) da classe de fundo à qual a despesa pertence. |
| `expense_key` | string | Identificador único (UUID) da despesa a ser consultada. |

```python title="Exemplo de chamada"
GET /expense/fund_class/{fund_class_key}/expense/{expense_key}
```

### Response

STATUS 200

```json title="Response Body"
{
    "expense_key": "3571e292-3a83-4011-904d-20ee963022ef",
    "fund_class": {
        "name": "Fundo de Investimento XYZ",
        "manager": {
            "name": "Gestora ABC",
            "manager_key": "f1e2d3c4-b5a6-7890-abcd-ef1234567890",
            "document_number": "12.345.678/0001-90"
        },
        "fund_class_key": "c1d2e3f4-a5b6-7890-abcd-ef1234567890",
        "document_number": "98.765.432/0001-10",
        "accounting_date": "2025-06-10"
    },
    "status": "consolidated",
    "type": "management_tax",
    "reference_date": "2025-06-10",
    "start_deferral_date": "2025-06-01",
    "end_deferral_date": "2025-06-30",
    "consolidated_value": 1500.00,
    "provisioned_value": 1500.00,
    "recognized_value": 1500.00,
    "payment": null,
    "expense_datetime": "2025-06-01T00:00:00Z",
    "description": "Taxa de gestão referente ao mês de junho/2025",
    "payment_method": "transfer",
    "payment_date": "2025-06-30",
    "payment_confirmation": {
        "confirmation_date": "2025-06-30"
    }
}
```

### Atributos da resposta

A resposta possui a mesma estrutura de cada objeto do array `data` retornado pela [listagem de despesas](#atributos-de-cada-despesa-objetos-dentro-de-data).

---

## Possíveis erros

STATUS 404

**Despesa não encontrada**

O `expense_key` informado não corresponde a nenhuma despesa cadastrada para esta classe de fundo. Verifique se os identificadores estão corretos.

```json
{
  "title": "Expense not Found",
  "description": "The Expense with key {expense_key} was not found in Fund Class with key {fund_class_key}.",
  "translation": "A Despesa com a chave {expense_key} nao foi encontrada na classe de fundos com a chave {fund_class_key}.",
  "code": "EXP000010"
}
```

---

## Enumeradores de `status`

| Valor | Descrição |
|---|---|
| `created` | Despesa criada, ainda não iniciou o processo de provisionamento. |
| `in_provision` | Despesa em processo de provisionamento diário. |
| `on_demand_recognition` | Despesa com reconhecimento sob demanda (manual). |
| `consolidated` | Despesa consolidada — valor total reconhecido e pronto para pagamento. |
| `paid` | Despesa paga. |
| `canceled` | Despesa cancelada. |
| `completed` | Despesa encerrada. |

## Enumeradores de `type`

| Valor | Descrição |
|---|---|
| `administration_tax` | Taxa de administração. |
| `management_tax` | Taxa de gestão. |
| `performance_fee` | Taxa de performance. |
| `custody_tax` | Taxa de custódia. |
| `distribution_fee` | Taxa de distribuição. |
| `consulting_fee` | Taxa de consultoria. |
| `audit_tax` | Taxa de auditoria. |
| `cvm_tax` | Taxa CVM. |
| `cetip_tax` | Taxa CETIP. |
| `anbima_tax` | Taxa ANBIMA. |
| `selic_tax` | Taxa SELIC. |
| `notary` | Cartório. |
| `bank_account` | Conta bancária. |
| `bankslip_fee` | Taxa de boleto. |
| `sale_commission_tax` | Taxa de comissão de venda. |
| `certifier_fee` | Taxa de certificadora. |
| `rating_agency_fee` | Taxa de agência de rating. |
| `lawyer_fee` | Honorários advocatícios. |
| `bookkeeping_fee` | Taxa de escrituração. |
| `insurance_fee` | Taxa de seguro. |
| `collection_agent_fee` | Taxa de agente cobrador. |
| `servicing_fee` | Taxa de serviços. |
| `fund_structuring_fee` | Taxa de estruturação do fundo. |
| `credit_rights_registration_fee` | Taxa de registro de direitos creditórios. |
| `origination_fee` | Taxa de originação. |

## Enumeradores de `payment_method`

| Valor | Descrição |
|---|---|
| `transfer` | Transferência bancária. |
| `automatic_debit` | Débito automático. |
| `bank_slip` | Boleto bancário. |

---

# Atualização do Contrato

URL: /documentation/iaas/despesas/submissao_despesa/contrato/atualizacao

Edite os dados de um contrato enquanto ele ainda estiver no status `created`. Após a [submissão](/documentation/iaas/despesas/submissao_despesa/contrato/submissao), o contrato não pode mais ser alterado.

:::info
Somente contratos com status `created` podem ser atualizados.
:::

## Request

ENDPOINT /expense_submission/fund_class/{fund_class_key}/contract/{contract_key}
MÉTODO PUT

### Path params

| Parâmetro | Tipo | Descrição |
|---|---|---|
| `fund_class_key` | string | Chave única do fundo (UUID) |
| `contract_key` | string | Chave única do contrato |

```json title="Request Body"
{
    "name": "Contrato de Auditoria - Exercício 2026 (revisado)",
    "vendor_key": "3571e292-3a83-4011-904d-20ee963022ef",
    "expense_type": "audit_tax",
    "submission_nature": "manual_submission",
    "contract_value": 60000.00,
    "validity_date": "2026-12-31"
}
```

### Atributos do body

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `name` | string | opcional | Novo nome do contrato. Máximo de 255 caracteres. |
| `vendor_key` | string | opcional | Nova chave do fornecedor. |
| `expense_type` | string | opcional | Novo tipo de despesa. Ver [Tipos de despesa](/documentation/iaas/despesas/submissao_despesa/contrato/criacao#tipos-de-despesa). |
| `submission_nature` | string | opcional | Nova natureza de submissão: `manual_submission` ou `rebate`. |
| `contract_value` | number | opcional | Novo valor máximo do contrato. Mínimo: `0`. |
| `validity_date` | string | opcional | Nova data de validade no formato `YYYY-MM-DD`. |

## Response

STATUS 200

```json title="Response Body"
{
    "name": "Contrato de Auditoria - Exercício 2026 (revisado)",
    "contract_key": "contrato-auditoria-2026",
    "fund_class": {
        "name": "FUNDO DE INVESTIMENTO EM DIREITOS CREDITÓRIOS EXEMPLO",
        "manager": {
            "name": "EXEMPLO GESTORA LTDA",
            "manager_key": "a7498c6c-1893-42ec-a8f3-bc6ad0c6b52c",
            "document_number": "45.585.471/0001-47"
        },
        "fund_class_key": "4b8377d0-58ec-479f-8ee9-9f963d5c47ad",
        "document_number": "60.910.091/0001-24"
    },
    "vendor": {
        "vendor_key": "3571e292-3a83-4011-904d-20ee963022ef",
        "name": "AUDITORES EXEMPLO S.A.",
        "document_number": "12.345.678/0001-90",
        "requires_invoice": "True"
    },
    "expense_type": "audit_tax",
    "status": "created",
    "contract_value": 60000.00,
    "validity_date": "2026-12-31",
    "submission_nature": "manual_submission"
}
```

Os atributos da resposta seguem a mesma estrutura da [criação do contrato](/documentation/iaas/despesas/submissao_despesa/contrato/criacao#atributos-da-resposta).

## Possíveis erros

STATUS 404

**Contrato não encontrado**

O par `fund_class_key` + `contract_key` não corresponde a nenhum contrato cadastrado.

```json
{
  "title": "Contract Not Found",
  "description": "Contract with key {contract_key} and fund class {fund_class_key} was not found.",
  "translation": "O contrato com chave {contract_key} do fundo {fund_class_key} não foi encontrado.",
  "code": "ESB000011"
}
```

STATUS 400

**Contrato não pode ser editado neste status**

O contrato não está no status `created` e não pode ser editado.

```json
{
  "title": "Cannot Update Contract In This Status",
  "description": "Contract {contract_key} cannot be updated with status {current_status}.",
  "translation": "O contrato {contract_key} não pode ser atualizado com o status {current_status}.",
  "code": "ESB000022"
}
```

## Próximos passos

1. **[Submeter o contrato](/documentation/iaas/despesas/submissao_despesa/contrato/submissao)** — envie o contrato para análise quando estiver pronto.
2. **[Cancelar o contrato](/documentation/iaas/despesas/submissao_despesa/contrato/cancelamento)** — cancele o contrato caso não seja mais necessário.

---

# Cancelamento do Contrato

URL: /documentation/iaas/despesas/submissao_despesa/contrato/cancelamento

Cancele um contrato que não seja mais necessário. O cancelamento é uma operação irreversível.

:::caution Atenção
Um contrato cancelado não pode ser reativado. Despesas que estejam sob um contrato cancelado também são impactadas. Certifique-se de que o cancelamento é realmente necessário antes de prosseguir.
:::

## Request

ENDPOINT /expense_submission/fund_class/{fund_class_key}/contract/{contract_key}/cancel
MÉTODO PUT

### Path params

| Parâmetro | Tipo | Descrição |
|---|---|---|
| `fund_class_key` | string | Chave única do fundo (UUID) |
| `contract_key` | string | Chave única do contrato |

Este endpoint não requer body na requisição.

## Response

STATUS 200

```json title="Response Body"
{
    "name": "Contrato de Auditoria - Exercício 2026",
    "contract_key": "contrato-auditoria-2026",
    "fund_class": {
        "name": "FUNDO DE INVESTIMENTO EM DIREITOS CREDITÓRIOS EXEMPLO",
        "manager": {
            "name": "EXEMPLO GESTORA LTDA",
            "manager_key": "a7498c6c-1893-42ec-a8f3-bc6ad0c6b52c",
            "document_number": "45.585.471/0001-47"
        },
        "fund_class_key": "4b8377d0-58ec-479f-8ee9-9f963d5c47ad",
        "document_number": "60.910.091/0001-24"
    },
    "vendor": {
        "vendor_key": "3571e292-3a83-4011-904d-20ee963022ef",
        "name": "AUDITORES EXEMPLO S.A.",
        "document_number": "12.345.678/0001-90",
        "requires_invoice": "True"
    },
    "expense_type": "audit_tax",
    "status": "canceled",
    "contract_value": 50000.00,
    "validity_date": "2026-12-31",
    "submission_nature": "manual_submission"
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `status` | string | Novo status do contrato. Sempre retorna `canceled` após o cancelamento bem-sucedido. |

Os demais campos seguem a mesma estrutura da [criação do contrato](/documentation/iaas/despesas/submissao_despesa/contrato/criacao#atributos-da-resposta).

## Possíveis erros

STATUS 404

**Contrato não encontrado**

O par `fund_class_key` + `contract_key` não corresponde a nenhum contrato cadastrado.

```json
{
  "title": "Contract Not Found",
  "description": "Contract with key {contract_key} and fund class {fund_class_key} was not found.",
  "translation": "O contrato com chave {contract_key} do fundo {fund_class_key} não foi encontrado.",
  "code": "ESB000011"
}
```

STATUS 400

**Contrato já em status final**

O contrato já está em um status final (`approved` ou `rejected`) e não pode ser cancelado.

```json
{
  "title": "Already In Final Contract Status",
  "description": "The contract {contract_key} is already in a final status: {current_status}.",
  "translation": "O contrato {contract_key} já está em um status final: {current_status}.",
  "code": "ESB000020"
}
```

---

# Criação do Contrato

URL: /documentation/iaas/despesas/submissao_despesa/contrato/criacao

Este é o **primeiro passo** do fluxo de submissão de despesas pelo agente integrador. O contrato define a relação comercial entre o fundo e um fornecedor, estabelecendo o tipo de despesa e as condições de pagamento.

:::info Pré-requisitos
Antes de criar um contrato, você precisa ter em mãos:
- `fund_class_key` — chave única do fundo, fornecida pela QI Tech
- `vendor_key` — chave do fornecedor cadastrado. Consulte a [listagem de fornecedores](/documentation/iaas/despesas/submissao_despesa/fornecedor/listagem) para obtê-la

Para mais detalhes sobre o fluxo completo, consulte a [página de introdução](/documentation/iaas/despesas/submissao_despesa/inicio).
:::

:::caution Atenção
O campo `submission_nature = rebate` só pode ser utilizado em conjunto com `expense_type = distribution_fee`. Para todos os demais tipos de despesa, use `submission_nature = manual_submission`.
:::

## Request

ENDPOINT /expense_submission/fund_class/{fund_class_key}/contract
MÉTODO POST

### Path params

| Parâmetro | Tipo | Descrição |
|---|---|---|
| `fund_class_key` | string | Chave única do fundo (UUID) |

```json title="Request Body"
{
    "name": "Contrato de Auditoria - Exercício 2026",
    "vendor_key": "3571e292-3a83-4011-904d-20ee963022ef",
    "expense_type": "audit_tax",
    "submission_nature": "manual_submission",
    "contract_value": 50000.00,
    "validity_date": "2026-12-31",
    "contract_key": "contrato-auditoria-2026"
}
```

### Atributos do body

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `name` | string | obrigatório | Nome do contrato. Máximo de 255 caracteres. |
| `vendor_key` | string | obrigatório | Chave única do fornecedor (máximo 255 caracteres). |
| `expense_type` | string | obrigatório | Tipo de despesa. Ver [Tipos de despesa](#tipos-de-despesa). |
| `submission_nature` | string | obrigatório | Natureza de submissão: `manual_submission` ou `rebate`. |
| `contract_value` | number | opcional | Valor máximo do contrato. Quando informado, a soma das despesas não pode exceder este valor. Mínimo: `0`. |
| `validity_date` | string | opcional | Data de validade do contrato no formato `YYYY-MM-DD`. Após esta data, nenhuma nova despesa pode ser criada. |
| `contract_key` | string | opcional | Identificador personalizado do contrato no sistema do parceiro. Máximo de 255 caracteres. Quando não informado, um UUID é gerado automaticamente. |

### Tipos de despesa

| Valor | Descrição |
|---|---|
| `cvm_tax` | Taxa CVM |
| `cetip_tax` | Taxa CETIP |
| `anbima_tax` | Taxa ANBIMA |
| `notary` | Cartório |
| `audit_tax` | Taxa de auditoria |
| `administration_tax` | Taxa de administração |
| `management_tax` | Taxa de gestão |
| `bank_account` | Conta bancária |
| `selic_tax` | Taxa SELIC |
| `consulting_fee` | Honorários de consultoria |
| `custody_tax` | Taxa de custódia |
| `performance_fee` | Taxa de performance |
| `bankslip_fee` | Taxa de boleto |
| `sale_commission_tax` | Comissão de venda |
| `certifier_fee` | Honorários de certificador |
| `rating_agency_fee` | Taxa de agência de rating |
| `lawyer_fee` | Honorários advocatícios |
| `bookkeeping_fee` | Taxa de escrituração |
| `distribution_fee` | Taxa de distribuição |
| `insurance_fee` | Taxa de seguro |
| `collection_agent_fee` | Honorários de agente de cobrança |
| `servicing_fee` | Taxa de serviços |
| `fund_structuring_fee` | Taxa de estruturação do fundo |
| `credit_rights_registration_fee` | Taxa de registro de direitos creditórios |
| `origination_fee` | Taxa de originação |

## Response

STATUS 201

```json title="Response Body"
{
    "name": "Contrato de Auditoria - Exercício 2026",
    "contract_key": "contrato-auditoria-2026",
    "fund_class": {
        "name": "FUNDO DE INVESTIMENTO EM DIREITOS CREDITÓRIOS EXEMPLO",
        "manager": {
            "name": "EXEMPLO GESTORA LTDA",
            "manager_key": "a7498c6c-1893-42ec-a8f3-bc6ad0c6b52c",
            "document_number": "45.585.471/0001-47"
        },
        "fund_class_key": "4b8377d0-58ec-479f-8ee9-9f963d5c47ad",
        "document_number": "60.910.091/0001-24"
    },
    "vendor": {
        "vendor_key": "3571e292-3a83-4011-904d-20ee963022ef",
        "name": "AUDITORES EXEMPLO S.A.",
        "document_number": "12.345.678/0001-90",
        "requires_invoice": "True"
    },
    "expense_type": "audit_tax",
    "status": "created",
    "contract_value": 50000.00,
    "validity_date": "2026-12-31",
    "submission_nature": "manual_submission"
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `name` | string | Nome do contrato. |
| `contract_key` | string | Chave única do contrato. Guarde este valor para as próximas etapas. |
| `fund_class` | object | Dados do fundo associado. Veja [Atributos de `fund_class`](#atributos-de-fund_class). |
| `vendor` | object | Dados do fornecedor. Veja [Atributos de `vendor`](#atributos-de-vendor). |
| `expense_type` | string | Tipo de despesa do contrato. |
| `status` | string | Status inicial do contrato. Sempre retorna `created`. |
| `contract_value` | number | Valor máximo do contrato, ou `null` quando não informado. |
| `validity_date` | string | Data de validade no formato `YYYY-MM-DD`, ou `null` quando não informada. |
| `submission_nature` | string | Natureza de submissão do contrato. |

#### Atributos de `fund_class`

| Campo | Tipo | Descrição |
|---|---|---|
| `name` | string | Nome do fundo. |
| `manager` | object | Dados do gestor do fundo. |
| `manager.name` | string | Nome do gestor. |
| `manager.manager_key` | string | Chave única do gestor (UUID). |
| `manager.document_number` | string | CNPJ do gestor. |
| `fund_class_key` | string | Chave única do fundo (UUID). |
| `document_number` | string | CNPJ do fundo. |

#### Atributos de `vendor`

| Campo | Tipo | Descrição |
|---|---|---|
| `vendor_key` | string | Chave única do fornecedor. |
| `name` | string | Nome do fornecedor. |
| `document_number` | string | CPF ou CNPJ do fornecedor. |
| `requires_invoice` | string | Indica se o fornecedor exige nota fiscal (`"True"` ou `"False"`). |

## Possíveis erros

STATUS 404

**Fundo não encontrado**

A `fund_class_key` informada na URL não corresponde a nenhum fundo cadastrado.

```json
{
  "title": "Fund Class Not Found",
  "description": "Fund Class with key {fund_class_key} was not found.",
  "translation": "O Fundo com chave {fund_class_key} nao foi encontrado.",
  "code": "ESB000005"
}
```

**Fornecedor não encontrado**

A `vendor_key` informada no body não corresponde a nenhum fornecedor cadastrado.

```json
{
  "title": "Vendor Not Found",
  "description": "Vendor with key {vendor_key} was not found.",
  "translation": "O fornecedor com a chave {vendor_key} nao foi encontrado.",
  "code": "ESB000008"
}
```

STATUS 409

**Contract key duplicada**

Já existe um contrato com a `contract_key` informada neste fundo. Use um identificador diferente ou omita o campo para gerar um UUID automaticamente.

```json
{
  "title": "Contract Key Already Exists",
  "description": "A Contract with key {contract_key} already exists.",
  "translation": "Um contrato com a chave {contract_key} já existe.",
  "code": "ESB000012"
}
```

STATUS 400

**Tipo de despesa incompatível com a natureza de submissão**

O valor `rebate` em `submission_nature` só é válido quando `expense_type` é `distribution_fee`.

```json
{
  "title": "Invalid Expense Type",
  "description": "The expense type {expense_type} is not valid for submission nature {submission_nature}.",
  "translation": "O tipo de despesa {expense_type} não é válido para a natureza de submissão {submission_nature}.",
  "code": "ESB000031"
}
```

## Próximos passos

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

1. **[Submissão do contrato](/documentation/iaas/despesas/submissao_despesa/contrato/submissao)** — envie o contrato para análise e aprovação pela QI Tech.
2. **[Atualização do contrato](/documentation/iaas/despesas/submissao_despesa/contrato/atualizacao)** — edite os dados do contrato enquanto ele ainda estiver em status `created`.

---

# Listagem de Contratos

URL: /documentation/iaas/despesas/submissao_despesa/contrato/listagem

Liste os contratos de um fundo com filtros opcionais por tipo de despesa, status ou natureza de submissão.

## Request

ENDPOINT /expense_submission/fund_class/{fund_class_key}/contracts
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 |
|---|---|---|---|
| `expense_type` | string | opcional | Filtra por tipo de despesa. Ver [tipos de despesa](/documentation/iaas/despesas/submissao_despesa/contrato/criacao#tipos-de-despesa). |
| `status` | string | opcional | Filtra por status do contrato (`created`, `pending_adm_approval`, `approved`, `rejected`, `canceled`). |
| `submission_nature` | string | opcional | Filtra por natureza: `manual_submission` ou `rebate`. |
| `limit` | integer | opcional | Número de itens por página. Mínimo: `1`. Máximo: `1000`. Padrão: `10`. |
| `page` | integer | opcional | Número da página (base zero). Padrão: `0`. |

## Response

STATUS 200

```json title="Response Body"
{
    "data": [
        {
            "name": "Contrato de Auditoria - Exercício 2026",
            "contract_key": "contrato-auditoria-2026",
            "fund_class": {
                "name": "FUNDO DE INVESTIMENTO EM DIREITOS CREDITÓRIOS EXEMPLO",
                "manager": {
                    "name": "EXEMPLO GESTORA LTDA",
                    "manager_key": "a7498c6c-1893-42ec-a8f3-bc6ad0c6b52c",
                    "document_number": "45.585.471/0001-47"
                },
                "fund_class_key": "4b8377d0-58ec-479f-8ee9-9f963d5c47ad",
                "document_number": "60.910.091/0001-24"
            },
            "vendor": {
                "vendor_key": "3571e292-3a83-4011-904d-20ee963022ef",
                "name": "AUDITORES EXEMPLO S.A.",
                "document_number": "12.345.678/0001-90",
                "requires_invoice": "True"
            },
            "expense_type": "audit_tax",
            "status": "approved",
            "contract_value": 50000.00,
            "validity_date": "2026-12-31",
            "submission_nature": "manual_submission"
        }
    ],
    "limit": 10,
    "page": 0,
    "is_last_page": true
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `data` | array | Lista de contratos. Cada item segue a estrutura da [consulta individual](/documentation/iaas/despesas/submissao_despesa/contrato/recuperacao). |
| `limit` | integer | Número de itens por página utilizado na consulta. |
| `page` | integer | Número da página atual. |
| `is_last_page` | boolean | Indica se esta é a última página de resultados. |

## Possíveis erros

STATUS 404

**Fundo não encontrado**

A `fund_class_key` informada na URL não corresponde a nenhum fundo cadastrado.

```json
{
  "title": "Fund Class Not Found",
  "description": "Fund Class with key {fund_class_key} was not found.",
  "translation": "O Fundo com chave {fund_class_key} nao foi encontrado.",
  "code": "ESB000005"
}
```

---

# Consulta de Contrato

URL: /documentation/iaas/despesas/submissao_despesa/contrato/recuperacao

Recupere os dados e o status atual de um contrato específico.

## Request

ENDPOINT /expense_submission/fund_class/{fund_class_key}/contract/{contract_key}
MÉTODO GET

### Path params

| Parâmetro | Tipo | Descrição |
|---|---|---|
| `fund_class_key` | string | Chave única do fundo (UUID) |
| `contract_key` | string | Chave única do contrato |

## Response

STATUS 200

```json title="Response Body"
{
    "name": "Contrato de Auditoria - Exercício 2026",
    "contract_key": "contrato-auditoria-2026",
    "fund_class": {
        "name": "FUNDO DE INVESTIMENTO EM DIREITOS CREDITÓRIOS EXEMPLO",
        "manager": {
            "name": "EXEMPLO GESTORA LTDA",
            "manager_key": "a7498c6c-1893-42ec-a8f3-bc6ad0c6b52c",
            "document_number": "45.585.471/0001-47"
        },
        "fund_class_key": "4b8377d0-58ec-479f-8ee9-9f963d5c47ad",
        "document_number": "60.910.091/0001-24"
    },
    "vendor": {
        "vendor_key": "3571e292-3a83-4011-904d-20ee963022ef",
        "name": "AUDITORES EXEMPLO S.A.",
        "document_number": "12.345.678/0001-90",
        "requires_invoice": "True"
    },
    "expense_type": "audit_tax",
    "status": "approved",
    "contract_value": 50000.00,
    "validity_date": "2026-12-31",
    "submission_nature": "manual_submission"
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `name` | string | Nome do contrato. |
| `contract_key` | string | Chave única do contrato. |
| `fund_class` | object | Dados do fundo associado. |
| `vendor` | object | Dados do fornecedor. |
| `expense_type` | string | Tipo de despesa do contrato. |
| `status` | string | Status atual do contrato. Ver tabela de [status do contrato](/documentation/iaas/despesas/submissao_despesa/inicio#status-do-contrato). |
| `contract_value` | number | Valor máximo do contrato, ou `null` quando não informado. |
| `validity_date` | string | Data de validade no formato `YYYY-MM-DD`, ou `null` quando não informada. |
| `submission_nature` | string | Natureza de submissão do contrato. |

## Possíveis erros

STATUS 404

**Contrato não encontrado**

O par `fund_class_key` + `contract_key` não corresponde a nenhum contrato cadastrado.

```json
{
  "title": "Contract Not Found",
  "description": "Contract with key {contract_key} and fund class {fund_class_key} was not found.",
  "translation": "O contrato com chave {contract_key} do fundo {fund_class_key} não foi encontrado.",
  "code": "ESB000011"
}
```

---

# Submissão do Contrato

URL: /documentation/iaas/despesas/submissao_despesa/contrato/submissao

Após criar o contrato, submeta-o para análise da QI Tech. A submissão encaminha o contrato para revisão manual e muda seu status para `pending_adm_approval`.

:::caution Atenção
Após a submissão, o contrato não pode mais ser editado. Verifique todos os dados antes de prosseguir. Caso precise fazer alterações, utilize o endpoint de [atualização](/documentation/iaas/despesas/submissao_despesa/contrato/atualizacao) enquanto o status ainda for `created`.
:::

## Request

ENDPOINT /expense_submission/fund_class/{fund_class_key}/contract/{contract_key}/submit
MÉTODO PUT

### Path params

| Parâmetro | Tipo | Descrição |
|---|---|---|
| `fund_class_key` | string | Chave única do fundo (UUID) |
| `contract_key` | string | Chave única do contrato |

Este endpoint não requer body na requisição.

## Response

STATUS 200

```json title="Response Body"
{
    "name": "Contrato de Auditoria - Exercício 2026",
    "contract_key": "contrato-auditoria-2026",
    "fund_class": {
        "name": "FUNDO DE INVESTIMENTO EM DIREITOS CREDITÓRIOS EXEMPLO",
        "manager": {
            "name": "EXEMPLO GESTORA LTDA",
            "manager_key": "a7498c6c-1893-42ec-a8f3-bc6ad0c6b52c",
            "document_number": "45.585.471/0001-47"
        },
        "fund_class_key": "4b8377d0-58ec-479f-8ee9-9f963d5c47ad",
        "document_number": "60.910.091/0001-24"
    },
    "vendor": {
        "vendor_key": "3571e292-3a83-4011-904d-20ee963022ef",
        "name": "AUDITORES EXEMPLO S.A.",
        "document_number": "12.345.678/0001-90",
        "requires_invoice": "True"
    },
    "expense_type": "audit_tax",
    "status": "pending_adm_approval",
    "contract_value": 50000.00,
    "validity_date": "2026-12-31",
    "submission_nature": "manual_submission"
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `status` | string | Novo status do contrato. Sempre retorna `pending_adm_approval` após a submissão bem-sucedida. |

Os demais campos seguem a mesma estrutura da [criação do contrato](/documentation/iaas/despesas/submissao_despesa/contrato/criacao#atributos-da-resposta).

## Possíveis erros

STATUS 404

**Contrato não encontrado**

O par `fund_class_key` + `contract_key` não corresponde a nenhum contrato cadastrado.

```json
{
  "title": "Contract Not Found",
  "description": "Contract with key {contract_key} and fund class {fund_class_key} was not found.",
  "translation": "O contrato com chave {contract_key} do fundo {fund_class_key} não foi encontrado.",
  "code": "ESB000011"
}
```

STATUS 400

**Transição de status inválida**

O contrato não pode ser submetido a partir do status atual. A submissão só é permitida quando o contrato está no status `created`.

```json
{
  "title": "Invalid Contract Status Change",
  "description": "It is not possible to change the contract status from {current_status} to {new_status}.",
  "translation": "Não é possível alterar o status do contrato de {current_status} para {new_status}.",
  "code": "ESB000013"
}
```

## Próximos passos

Após submeter o contrato, aguarde a análise da QI Tech. Enquanto isso, você pode:

1. **[Consultar o contrato](/documentation/iaas/despesas/submissao_despesa/contrato/recuperacao)** — acompanhe o status do contrato.
2. **[Criar despesas](/documentation/iaas/despesas/submissao_despesa/despesa/criacao)** — despesas podem ser criadas mesmo enquanto o contrato aguarda aprovação (exceto contratos com status `rejected`).

---

# Atualização da Despesa

URL: /documentation/iaas/despesas/submissao_despesa/despesa/atualizacao

Edite os dados de uma despesa enquanto ela ainda estiver no status `created`. Após a submissão ou após a criação com documentos (status `pending_adm_approval`), a despesa não pode mais ser alterada.

:::info
Somente despesas com status `created` podem ser atualizadas.
:::

## Request

ENDPOINT /expense_submission/fund_class/{fund_class_key}/contract/{contract_key}/expense/{expense_key}
MÉTODO PUT

### Path params

| Parâmetro | Tipo | Descrição |
|---|---|---|
| `fund_class_key` | string | Chave única do fundo (UUID) |
| `contract_key` | string | Chave única do contrato |
| `expense_key` | string | Chave única da despesa (UUID) |

```json title="Request Body"
{
    "payment_method": "transfer",
    "start_deferral_date": "2026-06-02",
    "end_deferral_date": "2026-06-30",
    "description": "Honorários de auditoria - 1º semestre 2026 (corrigido)",
    "payment_value": 16000.00,
    "payment_date": "2026-07-01",
    "payment": {
        "target": {
            "name": "AUDITORES EXEMPLO S.A.",
            "document_number": "12.345.678/0001-90"
        },
        "target_account": {
            "account_number": "123456",
            "account_branch": "0001",
            "account_digit": "0",
            "financial_institution_code": "341"
        },
        "transfer_type": "wire_transfer",
        "source_account": {
            "account_key": "5e621ba2-b4ac-4ddd-9893-82d220e1577e"
        }
    }
}
```

### Atributos do body

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `payment_method` | string | opcional | Método de pagamento: `transfer`, `automatic_debit` ou `bank_slip`. |
| `start_deferral_date` | string | opcional | Data início da competência no formato `YYYY-MM-DD`. Deve ser dia útil. |
| `end_deferral_date` | string | opcional | Data fim da competência no formato `YYYY-MM-DD`. Deve ser dia útil. |
| `description` | string | opcional | Nova descrição da despesa. Máximo de 200 caracteres. |
| `payment_value` | number | opcional | Novo valor da despesa. Mínimo: `0`. |
| `payment_date` | string | opcional | Nova data de pagamento no formato `YYYY-MM-DD`. Deve ser dia útil. |
| `payment` | object | opcional | Novos dados do pagamento. Mesma estrutura da [criação da despesa](/documentation/iaas/despesas/submissao_despesa/despesa/criacao#atributos-de-payment). |

## Response

STATUS 200

A resposta segue a mesma estrutura da [criação da despesa](/documentation/iaas/despesas/submissao_despesa/despesa/criacao#atributos-da-resposta), com os campos atualizados.

## Possíveis erros

STATUS 404

**Despesa não encontrada**

O conjunto `fund_class_key` + `contract_key` + `expense_key` não corresponde a nenhuma despesa cadastrada.

```json
{
  "title": "Expense Not Found",
  "description": "Expense with key {expense_key} was not found.",
  "translation": "A despesa com chave {expense_key} não foi encontrada.",
  "code": "ESB000016"
}
```

STATUS 400

**Despesa não pode ser editada neste status**

A despesa não está no status `created` e não pode ser editada.

```json
{
  "title": "Cannot Update Expense In This Status",
  "description": "Expense {expense_key} cannot be updated with status {current_status}.",
  "translation": "A despesa {expense_key} não pode ser atualizada com o status {current_status}.",
  "code": "ESB000023"
}
```

## Próximos passos

1. **[Submeter a despesa](/documentation/iaas/despesas/submissao_despesa/despesa/submissao)** — encaminhe para análise quando estiver pronto.
2. **[Cancelar a despesa](/documentation/iaas/despesas/submissao_despesa/despesa/cancelamento)** — cancele caso não seja mais necessária.

---

# Cancelamento da Despesa

URL: /documentation/iaas/despesas/submissao_despesa/despesa/cancelamento

Cancele uma despesa que não seja mais necessária. O cancelamento é uma operação irreversível.

:::caution Atenção
Uma despesa cancelada não pode ser reativada. Certifique-se de que o cancelamento é realmente necessário antes de prosseguir. Despesas nos status `approved` ou `rejected` não podem ser canceladas.
:::

## Request

ENDPOINT /expense_submission/fund_class/{fund_class_key}/contract/{contract_key}/expense/{expense_key}/cancel
MÉTODO PUT

### Path params

| Parâmetro | Tipo | Descrição |
|---|---|---|
| `fund_class_key` | string | Chave única do fundo (UUID) |
| `contract_key` | string | Chave única do contrato |
| `expense_key` | string | Chave única da despesa (UUID) |

Este endpoint não requer body na requisição.

## Response

STATUS 200

```json title="Response Body"
{
    "expense_key": "7f3e9a1b-2c4d-5e6f-8901-abcdef234567",
    "contract_key": "contrato-auditoria-2026",
    "status": "canceled",
    "payment_method": "transfer",
    "start_deferral_date": "2026-06-02",
    "end_deferral_date": "2026-06-30",
    "description": "Honorários de auditoria referente ao 1º semestre de 2026",
    "payment": {
        "target": {
            "name": "AUDITORES EXEMPLO S.A.",
            "document_number": "12.345.678/0001-90"
        },
        "target_account": {
            "account_number": "123456",
            "account_branch": "0001",
            "account_digit": "0",
            "financial_institution_code": "341"
        }
    },
    "payment_value": 15000.00,
    "payment_date": "2026-07-01",
    "rebate_expense_key": null,
    "fund_class": {
        "name": "FUNDO DE INVESTIMENTO EM DIREITOS CREDITÓRIOS EXEMPLO",
        "manager": {
            "name": "EXEMPLO GESTORA LTDA",
            "manager_key": "a7498c6c-1893-42ec-a8f3-bc6ad0c6b52c",
            "document_number": "45.585.471/0001-47"
        },
        "fund_class_key": "4b8377d0-58ec-479f-8ee9-9f963d5c47ad",
        "document_number": "60.910.091/0001-24"
    }
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `status` | string | Novo status da despesa. Sempre retorna `canceled` após o cancelamento bem-sucedido. |

Os demais campos seguem a mesma estrutura da [criação da despesa](/documentation/iaas/despesas/submissao_despesa/despesa/criacao#atributos-da-resposta).

## Possíveis erros

STATUS 404

**Despesa não encontrada**

O conjunto `fund_class_key` + `contract_key` + `expense_key` não corresponde a nenhuma despesa cadastrada.

```json
{
  "title": "Expense Not Found",
  "description": "Expense with key {expense_key} was not found.",
  "translation": "A despesa com chave {expense_key} não foi encontrada.",
  "code": "ESB000016"
}
```

STATUS 400

**Despesa já em status final**

A despesa já está em um status final (`approved` ou `rejected`) e não pode ser cancelada.

```json
{
  "title": "Already In Final Expense Status",
  "description": "Expense {expense_key} is already in a final status: {current_status}.",
  "translation": "A despesa {expense_key} já está em um status final: {current_status}.",
  "code": "ESB000021"
}
```

---

# Criação da Despesa

URL: /documentation/iaas/despesas/submissao_despesa/despesa/criacao

Crie uma despesa individual sob um contrato existente. A despesa contém os dados de pagamento, o período de competência e os documentos comprobatórios.

:::info Pré-requisitos
- O contrato referenciado deve existir e não pode estar no status `rejected`.
- As datas (`payment_date`, `start_deferral_date`, `end_deferral_date`) devem ser **dias úteis** (sem fins de semana ou feriados nacionais).
- `start_deferral_date` não pode ser posterior a `end_deferral_date`.
- Quando o contrato possui `contract_value`, a soma dos valores de todas as despesas não pode ultrapassar esse limite.
:::

:::tip Atalho para submissão
Se os documentos comprobatórios forem incluídos no campo `documents` durante a criação, a despesa é **automaticamente encaminhada para revisão** (status `pending_adm_approval`), sem necessidade de chamar o endpoint de submissão separadamente.
:::

## Request

ENDPOINT /expense_submission/fund_class/{fund_class_key}/contract/{contract_key}/expense
MÉTODO POST

### Path params

| Parâmetro | Tipo | Descrição |
|---|---|---|
| `fund_class_key` | string | Chave única do fundo (UUID) |
| `contract_key` | string | Chave única do contrato |

```json title="Request Body — Pagamento por transferência (TED/PIX)"
{
    "payment_method": "transfer",
    "start_deferral_date": "2026-06-02",
    "end_deferral_date": "2026-06-30",
    "description": "Honorários de auditoria referente ao 1º semestre de 2026",
    "payment_value": 15000.00,
    "payment_date": "2026-07-01",
    "payment": {
        "target": {
            "name": "AUDITORES EXEMPLO S.A.",
            "document_number": "12.345.678/0001-90"
        },
        "target_account": {
            "account_number": "123456",
            "account_branch": "0001",
            "account_digit": "0",
            "financial_institution_code": "341"
        },
        "transfer_type": "wire_transfer",
        "source_account": {
            "account_key": "5e621ba2-b4ac-4ddd-9893-82d220e1577e"
        }
    },
    "documents": [
        {
            "name": "NF-e 001234",
            "document_type": "invoice",
            "document_b64": "JVBERi0xLjQKJcOkw7zDtsOfCjIgMCBvYmoK..."
        }
    ]
}
```

```json title="Request Body — Pagamento por boleto"
{
    "payment_method": "bank_slip",
    "start_deferral_date": "2026-06-02",
    "end_deferral_date": "2026-06-30",
    "description": "Taxa de custódia - junho/2026",
    "payment_value": 3500.00,
    "payment_date": "2026-07-01",
    "payment": {
        "target": {
            "name": "CUSTODIANTE EXEMPLO S.A.",
            "document_number": "98.765.432/0001-10"
        },
        "bank_slip": {
            "digitable_line": "34191.09008 63521.510047 91020.150008 1 10010000035000"
        },
        "source_account": {
            "account_key": "5e621ba2-b4ac-4ddd-9893-82d220e1577e"
        }
    }
}
```

### Atributos do body

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `payment_method` | string | obrigatório | Método de pagamento: `transfer`, `automatic_debit` ou `bank_slip`. |
| `start_deferral_date` | string | obrigatório | Data início da competência no formato `YYYY-MM-DD`. Deve ser dia útil. |
| `end_deferral_date` | string | obrigatório | Data fim da competência no formato `YYYY-MM-DD`. Deve ser dia útil e ≥ `start_deferral_date`. |
| `description` | string | obrigatório | Descrição da despesa. Máximo de 200 caracteres. |
| `payment_value` | number | obrigatório | Valor da despesa. Mínimo: `0`. |
| `payment_date` | string | obrigatório | Data de pagamento no formato `YYYY-MM-DD`. Deve ser dia útil. |
| `payment` | object | obrigatório | Dados do pagamento. Ver [Atributos de `payment`](#atributos-de-payment). |
| `documents` | array | opcional | Lista de documentos comprobatórios. Quando informado, a despesa é automaticamente encaminhada para revisão. Ver [Atributos de `documents`](#atributos-de-documents). |

#### Atributos de `payment`

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `target` | object | obrigatório | Dados do beneficiário. |
| `target.name` | string | obrigatório | Nome do beneficiário. |
| `target.document_number` | string | obrigatório | CPF (`###.###.###-##`) ou CNPJ (`##.###.###/####-##`) do beneficiário. |
| `target_account` | object | condicional | Dados da conta bancária de destino. Obrigatório para `payment_method = transfer`. |
| `target_account.account_number` | string | obrigatório | Número da conta (1-20 dígitos, não pode ser todos zeros). |
| `target_account.account_branch` | string | obrigatório | Agência (exatamente 4 dígitos, não pode ser todos zeros). |
| `target_account.account_digit` | string | obrigatório | Dígito verificador (1 dígito). |
| `target_account.financial_institution_code` | string | obrigatório | Código do banco (exatamente 3 dígitos, não pode ser todos zeros). |
| `target_account.financial_institution_ispb` | string | opcional | ISPB do banco (exatamente 8 dígitos). |
| `target_account.account_type` | string | opcional | Tipo da conta bancária. |
| `transfer_type` | string | condicional | Tipo de transferência: `pix` ou `wire_transfer`. Necessário para `payment_method = transfer`. |
| `target_pix_key` | string | condicional | Chave PIX do beneficiário (1-77 caracteres). Obrigatório quando `transfer_type = pix`. |
| `pix_qrcode` | string | opcional | QR Code PIX (1-255 caracteres). |
| `bank_slip` | object | condicional | Dados do boleto. Obrigatório para `payment_method = bank_slip`. |
| `bank_slip.digitable_line` | string | obrigatório | Linha digitável do boleto (47-48 caracteres). |
| `source_account` | object | opcional | Conta de débito de origem do pagamento. |
| `source_account.account_key` | string | obrigatório | Chave única da conta de origem (UUID). |
| `conciliation_metadata` | object | opcional | Metadados de conciliação. |
| `conciliation_metadata.fee_type` | string | opcional | Tipo de taxa para conciliação. |
| `conciliation_metadata.conciliation_value` | string | opcional | Valor de conciliação. |
| `conciliation_metadata.conciliation_field` | string | opcional | Campo de conciliação. |

#### Atributos de `documents`

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `name` | string | obrigatório | Nome do documento. Máximo de 255 caracteres. |
| `document_type` | string | obrigatório | Tipo do documento: `invoice` (NF), `calculation_memory` (memória de cálculo), `contract` (contrato) ou `bank_slip` (boleto). |
| `document_b64` | string | obrigatório | Conteúdo do documento codificado em Base64. |

## Response

STATUS 201

```json title="Response Body"
{
    "expense_key": "7f3e9a1b-2c4d-5e6f-8901-abcdef234567",
    "contract_key": "contrato-auditoria-2026",
    "status": "pending_adm_approval",
    "payment_method": "transfer",
    "start_deferral_date": "2026-06-02",
    "end_deferral_date": "2026-06-30",
    "description": "Honorários de auditoria referente ao 1º semestre de 2026",
    "payment": {
        "target": {
            "name": "AUDITORES EXEMPLO S.A.",
            "document_number": "12.345.678/0001-90"
        },
        "target_account": {
            "account_number": "123456",
            "account_branch": "0001",
            "account_digit": "0",
            "financial_institution_code": "341"
        },
        "transfer_type": "wire_transfer",
        "source_account": {
            "account_key": "5e621ba2-b4ac-4ddd-9893-82d220e1577e"
        }
    },
    "payment_value": 15000.00,
    "payment_date": "2026-07-01",
    "rebate_expense_key": null,
    "fund_class": {
        "name": "FUNDO DE INVESTIMENTO EM DIREITOS CREDITÓRIOS EXEMPLO",
        "manager": {
            "name": "EXEMPLO GESTORA LTDA",
            "manager_key": "a7498c6c-1893-42ec-a8f3-bc6ad0c6b52c",
            "document_number": "45.585.471/0001-47"
        },
        "fund_class_key": "4b8377d0-58ec-479f-8ee9-9f963d5c47ad",
        "document_number": "60.910.091/0001-24"
    }
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `expense_key` | string | Chave única da despesa (UUID). Guarde este valor para as próximas etapas. |
| `contract_key` | string | Chave do contrato ao qual a despesa pertence. |
| `status` | string | Status da despesa. Será `pending_adm_approval` se documentos foram incluídos na criação, ou `created` caso contrário. |
| `payment_method` | string | Método de pagamento da despesa. |
| `start_deferral_date` | string | Data início de competência no formato `YYYY-MM-DD`. |
| `end_deferral_date` | string | Data fim de competência no formato `YYYY-MM-DD`. |
| `description` | string | Descrição da despesa. |
| `payment` | object | Dados do pagamento conforme enviado na criação. |
| `payment_value` | number | Valor da despesa. |
| `payment_date` | string | Data de pagamento no formato `YYYY-MM-DD`. |
| `rebate_expense_key` | string | Chave da despesa original quando se tratar de um rebate, ou `null`. |
| `fund_class` | object | Dados do fundo associado. |

## Possíveis erros

STATUS 404

**Contrato não encontrado**

O par `fund_class_key` + `contract_key` não corresponde a nenhum contrato cadastrado.

```json
{
  "title": "Contract Not Found",
  "description": "Contract with key {contract_key} and fund class {fund_class_key} was not found.",
  "translation": "O contrato com chave {contract_key} do fundo {fund_class_key} não foi encontrado.",
  "code": "ESB000011"
}
```

STATUS 400

**Contrato rejeitado**

Não é possível criar despesas em um contrato com status `rejected`.

```json
{
  "title": "Cannot Create Expense On Rejected Contract",
  "description": "Cannot create expense on rejected contract {contract_key}.",
  "translation": "Não é possível criar despesa no contrato rejeitado {contract_key}.",
  "code": "ESB000035"
}
```

**Contrato vencido**

A data de validade do contrato já passou. Não é possível criar novas despesas.

```json
{
  "title": "Contract Expired",
  "description": "Contract {contract_key} has expired.",
  "translation": "O contrato {contract_key} está vencido.",
  "code": "ESB000029"
}
```

**Soma das despesas excede o valor do contrato**

A soma dos valores de todas as despesas ultrapassaria o `contract_value` definido no contrato.

```json
{
  "title": "Expense Value Sum Greater Than Contract",
  "description": "The sum of expense values exceeds the contract value for {contract_name}.",
  "translation": "A soma dos valores das despesas excede o valor do contrato {contract_name}.",
  "code": "ESB000030"
}
```

**Data inválida (não é dia útil)**

A data informada em `payment_date`, `start_deferral_date` ou `end_deferral_date` não é um dia útil.

```json
{
  "title": "Date Invalid For Expense Creation",
  "description": "The date {date} is not a valid workday for expense creation.",
  "translation": "A data {date} não é um dia útil válido para criação de despesa.",
  "code": "ESB000032"
}
```

**Data início posterior à data fim de competência**

O campo `start_deferral_date` é posterior ao `end_deferral_date`.

```json
{
  "title": "Start Deferral Date Greater Than End Deferral Date",
  "description": "The start deferral date {start_date} is greater than the end deferral date {end_date}.",
  "translation": "A data de início de competência {start_date} é maior que a data de fim de competência {end_date}.",
  "code": "ESB000033"
}
```

## Próximos passos

- Se os documentos foram incluídos na criação (status `pending_adm_approval`): aguarde a análise da QI Tech.
- Se os documentos **não** foram incluídos (status `created`):
  1. **[Upload de documentos](/documentation/iaas/despesas/submissao_despesa/documentos/upload)** — adicione ao menos um documento antes de submeter.
  2. **[Submeter a despesa](/documentation/iaas/despesas/submissao_despesa/despesa/submissao)** — encaminhe para análise da QI Tech.

---

# Listagem de Despesas

URL: /documentation/iaas/despesas/submissao_despesa/despesa/listagem

Liste as despesas submetidas de um contrato ou de um fundo com filtros opcionais.

## Listar por contrato

ENDPOINT /expense_submission/fund_class/{fund_class_key}/contract/{contract_key}/expenses
MÉTODO GET

### Path params

| Parâmetro | Tipo | Descrição |
|---|---|---|
| `fund_class_key` | string | Chave única do fundo (UUID) |
| `contract_key` | string | Chave única do contrato |

### Query params

| Parâmetro | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `payment_method` | string | opcional | Filtra por método de pagamento: `transfer`, `automatic_debit` ou `bank_slip`. |
| `payment_date` | string | opcional | Filtra pela data de pagamento no formato `YYYY-MM-DD`. |
| `start_deferral_date` | string | opcional | Filtra pela data início de competência no formato `YYYY-MM-DD`. |
| `end_deferral_date` | string | opcional | Filtra pela data fim de competência no formato `YYYY-MM-DD`. |
| `status` | string | opcional | Filtra por status (`created`, `pending_adm_approval`, `approved`, `rejected`, `canceled`). |
| `limit` | integer | opcional | Número de itens por página. Mínimo: `1`. Máximo: `1000`. Padrão: `10`. |
| `page` | integer | opcional | Número da página (base zero). Padrão: `0`. |

## Response

STATUS 200

```json title="Response Body"
{
    "data": [
        {
            "expense_key": "7f3e9a1b-2c4d-5e6f-8901-abcdef234567",
            "contract_key": "contrato-auditoria-2026",
            "status": "approved",
            "payment_method": "transfer",
            "start_deferral_date": "2026-06-02",
            "end_deferral_date": "2026-06-30",
            "description": "Honorários de auditoria referente ao 1º semestre de 2026",
            "payment": {
                "target": {
                    "name": "AUDITORES EXEMPLO S.A.",
                    "document_number": "12.345.678/0001-90"
                },
                "target_account": {
                    "account_number": "123456",
                    "account_branch": "0001",
                    "account_digit": "0",
                    "financial_institution_code": "341"
                }
            },
            "payment_value": 15000.00,
            "payment_date": "2026-07-01",
            "rebate_expense_key": null,
            "fund_class": {
                "name": "FUNDO DE INVESTIMENTO EM DIREITOS CREDITÓRIOS EXEMPLO",
                "manager": {
                    "name": "EXEMPLO GESTORA LTDA",
                    "manager_key": "a7498c6c-1893-42ec-a8f3-bc6ad0c6b52c",
                    "document_number": "45.585.471/0001-47"
                },
                "fund_class_key": "4b8377d0-58ec-479f-8ee9-9f963d5c47ad",
                "document_number": "60.910.091/0001-24"
            }
        }
    ],
    "limit": 10,
    "page": 0,
    "is_last_page": true
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `data` | array | Lista de despesas. Cada item segue a estrutura da [consulta individual](/documentation/iaas/despesas/submissao_despesa/despesa/recuperacao). |
| `limit` | integer | Número de itens por página utilizado na consulta. |
| `page` | integer | Número da página atual. |
| `is_last_page` | boolean | Indica se esta é a última página de resultados. |

---

## Listar por fundo

Para consultar todas as despesas de um fundo, independentemente do contrato:

ENDPOINT /expense_submission/fund_class/{fund_class_key}/expenses
MÉTODO GET

Aceita os mesmos query params da listagem por contrato, com os parâmetros adicionais:

| Parâmetro | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `rebate` | boolean | opcional | Filtra apenas despesas do tipo rebate (`true`) ou apenas despesas regulares (`false`). |
| `description` | string | opcional | Filtra pela descrição da despesa (busca parcial). |

## Possíveis erros

STATUS 404

**Fundo ou contrato não encontrado**

O `fund_class_key` ou `contract_key` informado não corresponde a nenhum registro cadastrado.

```json
{
  "title": "Contract Not Found",
  "description": "Contract with key {contract_key} and fund class {fund_class_key} was not found.",
  "translation": "O contrato com chave {contract_key} do fundo {fund_class_key} não foi encontrado.",
  "code": "ESB000011"
}
```

---

# Consulta de Despesa

URL: /documentation/iaas/despesas/submissao_despesa/despesa/recuperacao

Recupere os dados e o status atual de uma despesa no fluxo de submissão.

:::tip
Este endpoint retorna o status da despesa **dentro do processo de submissão** (ex: `created`, `pending_adm_approval`, `approved`). Para consultar despesas já consolidadas no ledger do fundo, utilize a [API de consulta de despesas](/documentation/iaas/despesas/despesa_consolidada/consulta_despesas).
:::

## Request

ENDPOINT /expense_submission/fund_class/{fund_class_key}/contract/{contract_key}/expense/{expense_key}
MÉTODO GET

### Path params

| Parâmetro | Tipo | Descrição |
|---|---|---|
| `fund_class_key` | string | Chave única do fundo (UUID) |
| `contract_key` | string | Chave única do contrato |
| `expense_key` | string | Chave única da despesa (UUID) |

## Response

STATUS 200

```json title="Response Body"
{
    "expense_key": "7f3e9a1b-2c4d-5e6f-8901-abcdef234567",
    "contract_key": "contrato-auditoria-2026",
    "status": "approved",
    "payment_method": "transfer",
    "start_deferral_date": "2026-06-02",
    "end_deferral_date": "2026-06-30",
    "description": "Honorários de auditoria referente ao 1º semestre de 2026",
    "payment": {
        "target": {
            "name": "AUDITORES EXEMPLO S.A.",
            "document_number": "12.345.678/0001-90"
        },
        "target_account": {
            "account_number": "123456",
            "account_branch": "0001",
            "account_digit": "0",
            "financial_institution_code": "341"
        },
        "transfer_type": "wire_transfer",
        "source_account": {
            "account_key": "5e621ba2-b4ac-4ddd-9893-82d220e1577e"
        }
    },
    "payment_value": 15000.00,
    "payment_date": "2026-07-01",
    "rebate_expense_key": null,
    "fund_class": {
        "name": "FUNDO DE INVESTIMENTO EM DIREITOS CREDITÓRIOS EXEMPLO",
        "manager": {
            "name": "EXEMPLO GESTORA LTDA",
            "manager_key": "a7498c6c-1893-42ec-a8f3-bc6ad0c6b52c",
            "document_number": "45.585.471/0001-47"
        },
        "fund_class_key": "4b8377d0-58ec-479f-8ee9-9f963d5c47ad",
        "document_number": "60.910.091/0001-24"
    }
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `expense_key` | string | Chave única da despesa (UUID). |
| `contract_key` | string | Chave do contrato ao qual a despesa pertence. |
| `status` | string | Status atual no fluxo de submissão. Ver tabela de [status da despesa](/documentation/iaas/despesas/submissao_despesa/inicio#status-da-despesa). |
| `payment_method` | string | Método de pagamento: `transfer`, `automatic_debit` ou `bank_slip`. |
| `start_deferral_date` | string | Data início de competência no formato `YYYY-MM-DD`. |
| `end_deferral_date` | string | Data fim de competência no formato `YYYY-MM-DD`. |
| `description` | string | Descrição da despesa. |
| `payment` | object | Dados do pagamento conforme cadastrados. |
| `payment_value` | number | Valor da despesa. |
| `payment_date` | string | Data de pagamento no formato `YYYY-MM-DD`. |
| `rebate_expense_key` | string | Chave da despesa original quando se tratar de um rebate, ou `null`. |
| `fund_class` | object | Dados do fundo associado. |

## Possíveis erros

STATUS 404

**Despesa não encontrada**

O conjunto `fund_class_key` + `contract_key` + `expense_key` não corresponde a nenhuma despesa cadastrada.

```json
{
  "title": "Expense Not Found",
  "description": "Expense with key {expense_key} was not found.",
  "translation": "A despesa com chave {expense_key} não foi encontrada.",
  "code": "ESB000016"
}
```

---

# Submissão da Despesa

URL: /documentation/iaas/despesas/submissao_despesa/despesa/submissao

Encaminhe uma despesa para análise da QI Tech. A submissão só é necessária quando a despesa foi criada **sem documentos** — caso contrário, a despesa já é automaticamente encaminhada durante a criação.

:::caution Atenção
- É obrigatório ter ao menos um documento anexado à despesa antes de submeter.
- Somente despesas no status `created` podem ser submetidas por este endpoint. Despesas que já passaram pela criação com documentos estarão no status `pending_adm_approval` e não precisam ser submetidas novamente.
:::

## Request

ENDPOINT /expense_submission/fund_class/{fund_class_key}/contract/{contract_key}/expense/{expense_key}/submit
MÉTODO PUT

### Path params

| Parâmetro | Tipo | Descrição |
|---|---|---|
| `fund_class_key` | string | Chave única do fundo (UUID) |
| `contract_key` | string | Chave única do contrato |
| `expense_key` | string | Chave única da despesa (UUID) |

Este endpoint não requer body na requisição.

## Response

STATUS 200

```json title="Response Body"
{
    "expense_key": "7f3e9a1b-2c4d-5e6f-8901-abcdef234567",
    "contract_key": "contrato-auditoria-2026",
    "status": "pending_adm_approval",
    "payment_method": "transfer",
    "start_deferral_date": "2026-06-02",
    "end_deferral_date": "2026-06-30",
    "description": "Honorários de auditoria referente ao 1º semestre de 2026",
    "payment": {
        "target": {
            "name": "AUDITORES EXEMPLO S.A.",
            "document_number": "12.345.678/0001-90"
        },
        "target_account": {
            "account_number": "123456",
            "account_branch": "0001",
            "account_digit": "0",
            "financial_institution_code": "341"
        },
        "transfer_type": "wire_transfer",
        "source_account": {
            "account_key": "5e621ba2-b4ac-4ddd-9893-82d220e1577e"
        }
    },
    "payment_value": 15000.00,
    "payment_date": "2026-07-01",
    "rebate_expense_key": null,
    "fund_class": {
        "name": "FUNDO DE INVESTIMENTO EM DIREITOS CREDITÓRIOS EXEMPLO",
        "manager": {
            "name": "EXEMPLO GESTORA LTDA",
            "manager_key": "a7498c6c-1893-42ec-a8f3-bc6ad0c6b52c",
            "document_number": "45.585.471/0001-47"
        },
        "fund_class_key": "4b8377d0-58ec-479f-8ee9-9f963d5c47ad",
        "document_number": "60.910.091/0001-24"
    }
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `status` | string | Novo status da despesa. Sempre retorna `pending_adm_approval` após a submissão bem-sucedida. |

Os demais campos seguem a mesma estrutura da [criação da despesa](/documentation/iaas/despesas/submissao_despesa/despesa/criacao#atributos-da-resposta).

## Possíveis erros

STATUS 404

**Despesa não encontrada**

O conjunto `fund_class_key` + `contract_key` + `expense_key` não corresponde a nenhuma despesa cadastrada.

```json
{
  "title": "Expense Not Found",
  "description": "Expense with key {expense_key} was not found.",
  "translation": "A despesa com chave {expense_key} não foi encontrada.",
  "code": "ESB000016"
}
```

STATUS 400

**Despesa sem documentos**

Não há documentos anexados à despesa. Faça o [upload de ao menos um documento](/documentation/iaas/despesas/submissao_despesa/documentos/upload) antes de submeter.

```json
{
  "title": "Submission Must Have At Least One Pending Analysis Document",
  "description": "Expense {expense_key} must have at least one document in pending_adm_approval or approved status.",
  "translation": "A despesa {expense_key} deve ter ao menos um documento em status pending_adm_approval ou approved.",
  "code": "ESB000025"
}
```

**Transição de status inválida**

A despesa não está no status `created` e não pode ser submetida por este endpoint.

```json
{
  "title": "Cannot Update Expense In This Status",
  "description": "Expense {expense_key} cannot be updated with status {current_status}.",
  "translation": "A despesa {expense_key} não pode ser atualizada com o status {current_status}.",
  "code": "ESB000023"
}
```

## Próximos passos

Após submeter a despesa, aguarde a análise da QI Tech. Você pode acompanhar o status via:

**[Consultar a despesa](/documentation/iaas/despesas/submissao_despesa/despesa/recuperacao)** — verifique o status atual da despesa.

---

# Listagem de Documentos

URL: /documentation/iaas/despesas/submissao_despesa/documentos/listagem

Liste todos os documentos vinculados a uma despesa ou a um contrato.

---

## Listar documentos de uma despesa

ENDPOINT /expense_submission/fund_class/{fund_class_key}/contract/{contract_key}/expense/{expense_key}/documents
MÉTODO GET

### Path params

| Parâmetro | Tipo | Descrição |
|---|---|---|
| `fund_class_key` | string | Chave única do fundo (UUID) |
| `contract_key` | string | Chave única do contrato |
| `expense_key` | string | Chave única da despesa (UUID) |

## Response

STATUS 200

```json title="Response Body"
{
    "data": [
        {
            "name": "NF-e 001234 - Auditoria jun/2026",
            "expense_document_key": "d4e5f6a7-b8c9-0123-def4-567890abcdef",
            "expense_key": "7f3e9a1b-2c4d-5e6f-8901-abcdef234567",
            "document_type": "invoice",
            "status": "approved"
        },
        {
            "name": "Memória de Cálculo - jun/2026",
            "expense_document_key": "e5f6a7b8-c9d0-1234-ef56-7890abcdef12",
            "expense_key": "7f3e9a1b-2c4d-5e6f-8901-abcdef234567",
            "document_type": "calculation_memory",
            "status": "pending_adm_approval"
        }
    ]
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `data` | array | Lista de documentos. |
| `data[].name` | string | Nome do documento. |
| `data[].expense_document_key` | string | Chave única do documento (UUID). |
| `data[].expense_key` | string | Chave da despesa à qual o documento pertence. |
| `data[].document_type` | string | Tipo do documento: `invoice`, `calculation_memory`, `contract` ou `bank_slip`. |
| `data[].status` | string | Status do documento: `pending_adm_approval`, `approved` ou `rejected`. |

---

## Listar documentos de um contrato

ENDPOINT /expense_submission/fund_class/{fund_class_key}/contract/{contract_key}/documents
MÉTODO GET

### Path params

| Parâmetro | Tipo | Descrição |
|---|---|---|
| `fund_class_key` | string | Chave única do fundo (UUID) |
| `contract_key` | string | Chave única do contrato |

## Response

STATUS 200

```json title="Response Body"
{
    "data": [
        {
            "name": "Contrato de Prestação de Serviços - Auditoria 2026",
            "contract_document_key": "f6a7b8c9-d0e1-2345-fa67-890abcdef123",
            "contract_key": "contrato-auditoria-2026",
            "document_type": "contract",
            "status": "approved"
        }
    ]
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `data` | array | Lista de documentos. |
| `data[].name` | string | Nome do documento. |
| `data[].contract_document_key` | string | Chave única do documento de contrato (UUID). |
| `data[].contract_key` | string | Chave do contrato ao qual o documento pertence. |
| `data[].document_type` | string | Tipo do documento. |
| `data[].status` | string | Status do documento: `pending_adm_approval`, `approved` ou `rejected`. |

## Possíveis erros

STATUS 404

**Despesa ou contrato não encontrado**

As chaves informadas na URL não correspondem a nenhum registro cadastrado.

```json
{
  "title": "Expense Not Found",
  "description": "Expense with key {expense_key} was not found.",
  "translation": "A despesa com chave {expense_key} não foi encontrada.",
  "code": "ESB000016"
}
```

---

# Upload de Documentos

URL: /documentation/iaas/despesas/submissao_despesa/documentos/upload

Adicione documentos comprobatórios a uma despesa ou contrato. Os documentos passam por análise da QI Tech e são obrigatórios para a submissão da despesa.

:::tip Atalho na criação
Você pode incluir documentos diretamente no body da [criação da despesa](/documentation/iaas/despesas/submissao_despesa/despesa/criacao) — nesse caso, a despesa já entra em `pending_adm_approval` sem precisar chamar este endpoint separadamente.
:::

:::info Tipos de documento aceitos
- `invoice` — Nota fiscal eletrônica (NF-e)
- `calculation_memory` — Memória de cálculo ou planilha de apuração
- `contract` — Contrato do serviço prestado
- `bank_slip` — Boleto bancário
:::

---

## Upload de documento em despesa

ENDPOINT /expense_submission/fund_class/{fund_class_key}/contract/{contract_key}/expense/{expense_key}/document
MÉTODO POST

### Path params

| Parâmetro | Tipo | Descrição |
|---|---|---|
| `fund_class_key` | string | Chave única do fundo (UUID) |
| `contract_key` | string | Chave única do contrato |
| `expense_key` | string | Chave única da despesa (UUID) |

```json title="Request Body"
{
    "name": "NF-e 001234 - Auditoria jun/2026",
    "document_type": "invoice",
    "document_b64": "JVBERi0xLjQKJcOkw7zDtsOfCjIgMCBvYmoKPDwKL0xlbmd0aCAzIDAgUgo..."
}
```

### Atributos do body

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `name` | string | obrigatório | Nome do documento. Máximo de 255 caracteres. |
| `document_type` | string | obrigatório | Tipo do documento: `invoice`, `calculation_memory`, `contract` ou `bank_slip`. |
| `document_b64` | string | obrigatório | Conteúdo do arquivo codificado em Base64. |

## Response

STATUS 201

```json title="Response Body"
{
    "name": "NF-e 001234 - Auditoria jun/2026",
    "expense_document_key": "d4e5f6a7-b8c9-0123-def4-567890abcdef",
    "expense_key": "7f3e9a1b-2c4d-5e6f-8901-abcdef234567",
    "document_type": "invoice",
    "status": "pending_adm_approval"
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `name` | string | Nome do documento. |
| `expense_document_key` | string | Chave única do documento (UUID). |
| `expense_key` | string | Chave da despesa à qual o documento pertence. |
| `document_type` | string | Tipo do documento. |
| `status` | string | Status inicial do documento. Sempre retorna `pending_adm_approval`. |

---

## Upload de documento em contrato

Documentos também podem ser vinculados diretamente ao contrato (ex: o contrato do serviço prestado).

ENDPOINT /expense_submission/fund_class/{fund_class_key}/contract/{contract_key}/document
MÉTODO POST

### Path params

| Parâmetro | Tipo | Descrição |
|---|---|---|
| `fund_class_key` | string | Chave única do fundo (UUID) |
| `contract_key` | string | Chave única do contrato |

O body e os atributos da resposta seguem a mesma estrutura do upload em despesa, com os campos `contract_document_key` e `contract_key` no lugar de `expense_document_key` e `expense_key`.

```json title="Response Body"
{
    "name": "Contrato de Prestação de Serviços - Auditoria 2026",
    "contract_document_key": "e5f6a7b8-c9d0-1234-ef56-7890abcdef12",
    "contract_key": "contrato-auditoria-2026",
    "document_type": "contract",
    "status": "pending_adm_approval"
}
```

---

## Consultar documento por chave

Recupere os dados de um documento e acesse o link para download do arquivo.

### Documento de despesa

ENDPOINT /expense_submission/fund_class/{fund_class_key}/contract/{contract_key}/expense/{expense_key}/document/{document_key}
MÉTODO GET

```json title="Response Body"
{
    "name": "NF-e 001234 - Auditoria jun/2026",
    "expense_document_key": "d4e5f6a7-b8c9-0123-def4-567890abcdef",
    "expense_key": "7f3e9a1b-2c4d-5e6f-8901-abcdef234567",
    "document_type": "invoice",
    "status": "approved",
    "document_url": "https://storage.example.com/documents/NF-001234.pdf?X-Amz-Expires=3600&..."
}
```

| Campo | Tipo | Descrição |
|---|---|---|
| `document_url` | string | URL pré-assinada para download do arquivo. Válida por tempo limitado. |
| `status` | string | Status do documento: `pending_adm_approval`, `approved` ou `rejected`. |

## Possíveis erros

STATUS 404

**Despesa não encontrada**

O conjunto de chaves na URL não corresponde a nenhuma despesa cadastrada.

```json
{
  "title": "Expense Not Found",
  "description": "Expense with key {expense_key} was not found.",
  "translation": "A despesa com chave {expense_key} não foi encontrada.",
  "code": "ESB000016"
}
```

**Documento não encontrado**

O `document_key` informado não corresponde a nenhum documento cadastrado para esta despesa.

```json
{
  "title": "Document Not Found",
  "description": "Document with key {document_key} was not found.",
  "translation": "O documento com chave {document_key} não foi encontrado.",
  "code": "ESB000015"
}
```

STATUS 400

**Formato do documento inválido**

O conteúdo em `document_b64` não é um Base64 válido ou o formato do arquivo não é suportado.

```json
{
  "title": "Invalid Document Format",
  "description": "The document format is invalid.",
  "translation": "Formato do documento invalido.",
  "code": "ESB000014"
}
```

## Próximos passos

Com ao menos um documento em `pending_adm_approval` ou `approved`, a despesa está pronta para ser submetida:

**[Submeter a despesa](/documentation/iaas/despesas/submissao_despesa/despesa/submissao)** — encaminhe para análise da QI Tech.

---

# Fluxo de submissão de despesas

URL: /documentation/iaas/despesas/submissao_despesa/fluxo_despesas

Esta página oferece uma visão holística do fluxo de submissão de despesas: desde a criação do contrato até a aprovação das despesas individuais pela QI Tech. Acompanhe a evolução dos **status do contrato**, dos **status de cada despesa** e as ações esperadas 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 trilhas coloridas mostram simultaneamente o que acontece com o contrato e com cada despesa.
:::

{`
.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-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-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-contrato{background:rgba(34,197,94,0.1);color:#16a34a;border-color:rgba(34,197,94,0.25)}
.cf-track-despesa{background:rgba(59,130,246,0.1);color:#2563eb;border-color:rgba(59,130,246,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-contrato{background:rgba(34,197,94,0.15);color:#4ade80;border-color:rgba(34,197,94,0.3)}
html[data-theme='dark'] .cf-track-despesa{background:rgba(59,130,246,0.15);color:#60a5fa;border-color:rgba(59,130,246,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}
`}

## Legenda

Agente Integrador
QI Tech (análise manual)
Status do Contrato
Status da Despesa

## Fluxograma

1
Criação do contrato
Agente Integrador
Cria um contrato vinculando o fundo a um fornecedor e definindo o tipo de despesa ( expense_type ) e a natureza de submissão ( submission_nature ).
Contrato: created
POST /expense_submission/fund_class/{fund_class_key}/contract
O contrato fica pronto para ser atualizado ou submetido para aprovação.
Ver documentação completa →

2
Submissão do contrato para aprovação
Agente Integrador
Sinaliza que o contrato está pronto para análise da QI Tech. Após a submissão, o contrato não pode mais ser editado.
Contrato: pending_adm_approval
PUT /expense_submission/fund_class/{fund_class_key}/contract/{contract_key}/submit
O contrato aguarda revisão manual pela equipe da QI Tech.
Ver documentação completa →

3
Análise e aprovação do contrato
QI Tech
A equipe da QI Tech analisa o contrato. Em caso de dúvidas, podem criar anotações que o agente integrador poderá responder.
Contrato aprovado
approved
Despesas podem ser criadas e submetidas.
Contrato rejeitado
rejected
Nenhuma despesa poderá ser criada neste contrato.
Use o endpoint de consulta para acompanhar o status do contrato.
GET /expense_submission/fund_class/{fund_class_key}/contract/{contract_key}
Ver documentação completa →

4
Criação da despesa
Agente Integrador
Cria uma despesa individual sob o contrato aprovado, informando dados de pagamento, período de competência e documentos comprobatórios. Ao incluir documentos na criação, a despesa é automaticamente encaminhada para revisão.
Contrato: approved
Despesa: created → pending_adm_approval*
POST /expense_submission/fund_class/{fund_class_key}/contract/{contract_key}/expense
*Se documentos forem incluídos no body da criação, a despesa vai diretamente para pending_adm_approval . Caso contrário, fica em created .
Ver documentação completa →

5
Upload de documentos (quando necessário)
Agente Integrador
Se os documentos não foram enviados na criação da despesa, faça o upload separadamente antes de submeter. Ao menos um documento é obrigatório para submissão.
Despesa: created
POST /expense_submission/fund_class/{fund_class_key}/contract/{contract_key}/expense/{expense_key}/document
Envie os documentos comprobatórios (NF, memória de cálculo, contrato ou boleto) em Base64.
Ver documentação completa →

6
Submissão da despesa para aprovação
Agente Integrador
Encaminha a despesa para análise da QI Tech. Obrigatório ter ao menos um documento anexado.
Despesa: pending_adm_approval
PUT /expense_submission/fund_class/{fund_class_key}/contract/{contract_key}/expense/{expense_key}/submit
Somente aplicável quando a despesa foi criada sem documentos ( status = created ). Caso contrário, a despesa já estará em pending_adm_approval .
Ver documentação completa →

7
Análise e aprovação da despesa
QI Tech
A QI Tech analisa os dados de pagamento e os documentos comprobatórios. Após aprovação, a despesa é processada internamente e registrada na carteira do fundo.
Despesa aprovada
approved
Despesa registrada. Fluxo encerrado com sucesso.
Despesa rejeitada
rejected
Verifique as anotações da QI Tech para entender o motivo da rejeição.
Use o endpoint de consulta para acompanhar o status da despesa.
GET /expense_submission/fund_class/{fund_class_key}/contract/{contract_key}/expense/{expense_key}
Ver documentação completa →

---

# Anotações da Análise

URL: /documentation/iaas/despesas/submissao_despesa/fornecedor/anotacoes

Durante a revisão, a equipe da QI Tech pode abrir **anotações** — solicitações de esclarecimento ou correção sobre os dados do fornecedor ou os documentos enviados. O agente integrador deve responder a essas anotações para que a análise prossiga.

:::info Status das anotações
| Status | Descrição |
|---|---|
| `created` | Anotação criada pela QI Tech |
| `opened` | Anotação aberta, aguardando resposta |
| `closed` | Anotação respondida ou encerrada |
:::

---

## Listar anotações de uma análise

ENDPOINT /vendor_registry/analysis/{analysis_key}/annotations
MÉTODO GET

### Path params

| Parâmetro | Tipo | Descrição |
|---|---|---|
| `analysis_key` | string | Chave única da análise (UUID) |

### Query params

| Parâmetro | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `status` | string (lista) | opcional | Filtra anotações pelo status. Valores: `created`, `opened`, `closed`. Aceita múltiplos valores. |
| `limit` | integer | opcional | Número de itens por página. Mínimo: `0`. Máximo: `1000`. Padrão: `10`. |
| `page` | integer | opcional | Número da página (base zero). Padrão: `0`. |

## Response

STATUS 200

```json title="Response Body"
{
    "data": [
        {
            "annotation_key": "f6a7b8c9-d0e1-2345-f678-90abcdef1234",
            "annotation_message": "Por favor, envie o contrato social atualizado com as últimas alterações societárias.",
            "annotation_response": null,
            "annotation_datetime": "2026-06-10 14:32:00",
            "analysis_key": "c3d4e5f6-a7b8-9012-cdef-345678901234",
            "status": "opened"
        }
    ],
    "limit": 10,
    "page": 0,
    "is_last_page": true
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `data` | array | Lista de anotações. |
| `limit` | integer | Número de itens por página utilizado na consulta. |
| `page` | integer | Número da página atual. |
| `is_last_page` | boolean | Indica se esta é a última página de resultados. |

#### Atributos de cada anotação em `data`

| Campo | Tipo | Descrição |
|---|---|---|
| `annotation_key` | string | Chave única da anotação (UUID). |
| `annotation_message` | string | Mensagem da anotação criada pela QI Tech. |
| `annotation_response` | string \| null | Resposta do agente integrador, ou `null` se ainda não respondida. |
| `annotation_datetime` | string | Data e hora em que a anotação foi criada. |
| `analysis_key` | string | Chave da análise à qual a anotação pertence. |
| `status` | string | Status da anotação: `created`, `opened` ou `closed`. |

---

## Consultar anotação por chave

ENDPOINT /vendor_registry/analysis/{analysis_key}/annotation/{annotation_key}
MÉTODO GET

### Path params

| Parâmetro | Tipo | Descrição |
|---|---|---|
| `analysis_key` | string | Chave única da análise (UUID) |
| `annotation_key` | string | Chave única da anotação (UUID) |

## Response

STATUS 200

```json title="Response Body"
{
    "annotation_key": "f6a7b8c9-d0e1-2345-f678-90abcdef1234",
    "annotation_message": "Por favor, envie o contrato social atualizado com as últimas alterações societárias.",
    "annotation_response": null,
    "annotation_datetime": "2026-06-10 14:32:00",
    "analysis_key": "c3d4e5f6-a7b8-9012-cdef-345678901234",
    "status": "opened"
}
```

---

## Responder a uma anotação

ENDPOINT /vendor_registry/analysis/{analysis_key}/annotation/{annotation_key}/respond
MÉTODO PUT

### Path params

| Parâmetro | Tipo | Descrição |
|---|---|---|
| `analysis_key` | string | Chave única da análise (UUID) |
| `annotation_key` | string | Chave única da anotação (UUID) |

```json title="Request Body"
{
    "annotation_response": "O contrato social atualizado foi enviado no documento 'Contrato Social - AUDITORES EXEMPLO S.A.'."
}
```

### Atributos do body

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `annotation_response` | string | obrigatório | Resposta à anotação. Máximo de 200 caracteres. |

## Response

STATUS 202

```json title="Response Body"
{
    "annotation_key": "f6a7b8c9-d0e1-2345-f678-90abcdef1234",
    "annotation_message": "Por favor, envie o contrato social atualizado com as últimas alterações societárias.",
    "annotation_response": "O contrato social atualizado foi enviado no documento 'Contrato Social - AUDITORES EXEMPLO S.A.'.",
    "annotation_datetime": "2026-06-10 14:32:00",
    "analysis_key": "c3d4e5f6-a7b8-9012-cdef-345678901234",
    "status": "closed"
}
```

---

## Possíveis erros

STATUS 404

**Anotação não encontrada**

A `annotation_key` informada na URL não corresponde a nenhuma anotação desta análise.

```json
{
  "title": "Annotation not found",
  "description": "Annotation with the key {annotation_key} was not found.",
  "translation": "A anotação com a chave {annotation_key} não foi encontrada.",
  "code": "VRG0000012"
}
```

STATUS 409

**Anotação já respondida**

A anotação informada já possui uma resposta registrada.

```json
{
  "title": "Annotation Already Responded",
  "description": "Annotation with key {annotation_key} is already responded.",
  "translation": "Anotação com chave {annotation_key} está respondida.",
  "code": "VRG0000013"
}
```

---

## Próximos passos

Após responder às anotações, aguarde a QI Tech retomar a análise. Acompanhe o status via:

**[Consultar análise por chave](/documentation/iaas/despesas/submissao_despesa/fornecedor/listagem#consultar-análise-por-chave)** — monitore o andamento da análise.

---

# Atualização de Dados da Análise

URL: /documentation/iaas/despesas/submissao_despesa/fornecedor/atualizacao

Enquanto a análise estiver no status `pending_submission`, é possível atualizar os dados de pagamento e a flag `requires_invoice`. Após submeter para `pending_adm_approval`, a edição não é mais permitida.

:::caution Restrição de status
Este endpoint só aceita atualizações quando a análise está no status `pending_submission`. Se a análise foi retornada pela QI Tech para este status, também é possível editar antes de reenviar.
:::

---

## Request

ENDPOINT /vendor_registry/analysis/{analysis_key}/update
MÉTODO PUT

### Path params

| Parâmetro | Tipo | Descrição |
|---|---|---|
| `analysis_key` | string | Chave única da análise (UUID) |

```json title="Request Body"
{
    "requires_invoice": false,
    "payment_method": "transfer",
    "payment": {
        "target": {
            "name": "AUDITORES EXEMPLO S.A.",
            "document_number": "12.345.678/0001-90"
        },
        "target_pix_key": "12345678000190",
        "transfer_type": "pix"
    }
}
```

### Atributos do body

Ao menos um campo deve ser informado.

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `requires_invoice` | boolean | opcional | Indica se esta análise exige nota fiscal. |
| `payment_method` | string | opcional | Método de pagamento padrão. Atualmente suporta apenas `transfer`. Obrigatório quando `payment` é informado. |
| `payment` | object | opcional | Dados bancários do fornecedor. Consulte os [atributos de `payment`](/documentation/iaas/despesas/submissao_despesa/fornecedor/criacao#atributos-de-payment). Obrigatório quando `payment_method` é informado. |

:::info Limpeza dos dados de pagamento
Se apenas um dos campos `payment` ou `payment_method` for informado (sem o outro), ambos serão removidos da análise.
:::

---

## Response

STATUS 200

```json title="Response Body"
{
    "analysis_key": "c3d4e5f6-a7b8-9012-cdef-345678901234",
    "status": "pending_submission",
    "requires_invoice": false,
    "manager": {
        "name": "EXEMPLO GESTORA LTDA",
        "manager_key": "a7498c6c-1893-42ec-a8f3-bc6ad0c6b52c",
        "document_number": "45.585.471/0001-47"
    },
    "vendor": {
        "vendor_key": "3571e292-3a83-4011-904d-20ee963022ef",
        "name": "AUDITORES EXEMPLO S.A.",
        "document_number": "12.345.678/0001-90",
        "requires_invoice": true,
        "status": "pending_analysis"
    },
    "payment_method": "transfer",
    "payment": {
        "target": {
            "name": "AUDITORES EXEMPLO S.A.",
            "document_number": "12.345.678/0001-90"
        },
        "target_pix_key": "12345678000190",
        "transfer_type": "pix"
    }
}
```

---

## Possíveis erros

STATUS 409

**Análise não editável**

A análise está em um status que não permite edição. Somente análises no status `pending_submission` podem ser editadas via este endpoint.

```json
{
  "title": "Analysis Not Editable",
  "description": "Analysis with key {analysis_key} is on status '{current_status}' and cannot be edited.",
  "translation": "A análise com chave {analysis_key} está no status '{current_status}' e não pode ser editada.",
  "code": "VRG000032"
}
```

STATUS 404

**Análise não encontrada**

A `analysis_key` informada na URL não corresponde a nenhuma análise cadastrada.

```json
{
  "title": "Analysis not found",
  "description": "Analysis with the key {analysis_key} was not found.",
  "translation": "A análise com a chave {analysis_key} não foi encontrada.",
  "code": "VRG000007"
}
```

---

## Próximos passos

Após atualizar os dados, prossiga para:

**[Submeter a análise](/documentation/iaas/despesas/submissao_despesa/fornecedor/submissao)** — encaminhe para revisão da QI Tech.

---

# Cancelamento da Análise

URL: /documentation/iaas/despesas/submissao_despesa/fornecedor/cancelamento

Cancele uma análise de cadastro de fornecedor que ainda esteja em andamento. Após o cancelamento, nenhuma alteração adicional pode ser feita nessa análise.

:::info Quando é possível cancelar
O cancelamento está disponível enquanto a análise estiver nos status `pending_submission` ou `pending_adm_approval`. Análises já `approved`, `rejected` ou `canceled` não podem ser canceladas.
:::

---

## Request

ENDPOINT /vendor_registry/analysis/{analysis_key}/cancel
MÉTODO PUT

### Path params

| Parâmetro | Tipo | Descrição |
|---|---|---|
| `analysis_key` | string | Chave única da análise (UUID) |

Este endpoint não requer body.

## Response

STATUS 202

```json title="Response Body"
{
    "analysis_key": "c3d4e5f6-a7b8-9012-cdef-345678901234",
    "status": "canceled"
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `analysis_key` | string | Chave única da análise. |
| `status` | string | Novo status da análise. Sempre retorna `canceled`. |

---

## Possíveis erros

STATUS 409

**Transição de status não permitida**

A análise está em um status que não permite cancelamento (por exemplo, já foi aprovada ou rejeitada).

```json
{
  "title": "Analysis Status Transition Denied",
  "description": "Analysis with key {analysis_key} is not allowed to switch status from {current_status} to canceled.",
  "translation": "Análise com chave {analysis_key} não pode trocar de status de {current_status} para canceled.",
  "code": "VRG000008"
}
```

STATUS 404

**Análise não encontrada**

A `analysis_key` informada na URL não corresponde a nenhuma análise cadastrada.

```json
{
  "title": "Analysis not found",
  "description": "Analysis with the key {analysis_key} was not found.",
  "translation": "A análise com a chave {analysis_key} não foi encontrada.",
  "code": "VRG000007"
}
```

---

## Próximos passos

Para cadastrar o fornecedor novamente, inicie um novo processo via:

**[Criação de análise](/documentation/iaas/despesas/submissao_despesa/fornecedor/criacao)** — submeta os dados do fornecedor novamente.

---

# Cadastro de Fornecedor

URL: /documentation/iaas/despesas/submissao_despesa/fornecedor/criacao

O cadastro de fornecedores é o **pré-requisito** para a criação de contratos de despesa. O processo é realizado pelo próprio agente integrador via API e passa por análise e aprovação da QI Tech antes de o fornecedor ser ativado na plataforma.

:::info Fluxo de cadastro
O cadastro de um fornecedor segue as seguintes etapas:

1. **Criação da análise** — envio dos dados do fornecedor (esta página)
2. **Upload de documentos** — anexar documentos comprobatórios
3. **Submissão para revisão** — encaminhar para análise da QI Tech
4. **Resposta a anotações** (se solicitado) — responder às solicitações da equipe de análise
5. **Aprovação** — o fornecedor é ativado e a `vendor_key` fica disponível para uso em contratos

Para detalhes sobre as etapas seguintes, consulte:
- [Upload de documentos](/documentation/iaas/despesas/submissao_despesa/fornecedor/documentos)
- [Submissão para análise](/documentation/iaas/despesas/submissao_despesa/fornecedor/submissao)
- [Anotações](/documentation/iaas/despesas/submissao_despesa/fornecedor/anotacoes)
:::

---

## Request

ENDPOINT /vendor_registry/analysis
MÉTODO POST

```json title="Request Body"
{
    "vendor_document_number": "12.345.678/0001-90",
    "vendor_name": "AUDITORES EXEMPLO S.A.",
    "requires_invoice": true,
    "payment_method": "transfer",
    "payment": {
        "target": {
            "name": "AUDITORES EXEMPLO S.A.",
            "document_number": "12.345.678/0001-90"
        },
        "target_account": {
            "account_number": "123456",
            "account_branch": "0001",
            "account_digit": "0",
            "financial_institution_code": "341"
        }
    }
}
```

### Atributos do body

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `vendor_document_number` | string | obrigatório | CPF ou CNPJ do fornecedor com pontuação. Mínimo 14, máximo 18 caracteres. |
| `vendor_name` | string | obrigatório | Nome completo do fornecedor. Máximo de 255 caracteres. |
| `requires_invoice` | boolean | opcional | Indica se o fornecedor exige nota fiscal para pagamento. Padrão: `false`. |
| `payment_method` | string | opcional | Método de pagamento padrão do fornecedor. Atualmente suporta apenas `transfer`. Obrigatório quando `payment` é informado. |
| `payment` | object | opcional | Dados bancários padrão do fornecedor. Ver [Atributos de `payment`](#atributos-de-payment). Obrigatório quando `payment_method` é informado. |

#### Atributos de `payment`

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `target` | object | obrigatório | Dados do beneficiário do pagamento. |
| `target.name` | string | obrigatório | Nome do beneficiário. |
| `target.document_number` | string | obrigatório | CPF ou CNPJ do beneficiário com pontuação. |
| `target_account` | object | opcional | Dados da conta bancária de destino (TED/DOC). Obrigatório quando `transfer_type` não é informado ou é `wire_transfer`. |
| `target_account.account_number` | string | obrigatório | Número da conta (1–20 dígitos, não pode ser zeros). |
| `target_account.account_branch` | string | obrigatório | Agência bancária (exatamente 4 dígitos, não pode ser zeros). |
| `target_account.account_digit` | string | obrigatório | Dígito verificador da conta (1 dígito). |
| `target_account.financial_institution_code` | string | obrigatório | Código do banco (exatamente 3 dígitos, não pode ser zeros). |
| `target_account.financial_institution_ispb` | string | opcional | ISPB do banco (exatamente 8 dígitos). Quando não informado, é preenchido automaticamente com base no `financial_institution_code`. |
| `target_account.account_type` | string | opcional | Tipo da conta bancária. |
| `transfer_type` | string | opcional | Tipo de transferência. Informe `pix` para pagamento via Pix. Quando omitido, o pagamento é via TED/DOC. |
| `target_pix_key` | string | opcional | Chave Pix do destinatário (máx. 77 caracteres). Obrigatório quando `transfer_type` é `pix` e `target_account` não é informado. A chave Pix deve pertencer ao CPF/CNPJ de `target.document_number`. |

---

## Response

STATUS 201

```json title="Response Body"
{
    "analysis_key": "c3d4e5f6-a7b8-9012-cdef-345678901234",
    "status": "pending_submission",
    "requires_invoice": true,
    "manager": {
        "name": "EXEMPLO GESTORA LTDA",
        "manager_key": "a7498c6c-1893-42ec-a8f3-bc6ad0c6b52c",
        "document_number": "45.585.471/0001-47"
    },
    "vendor": {
        "vendor_key": "3571e292-3a83-4011-904d-20ee963022ef",
        "name": "AUDITORES EXEMPLO S.A.",
        "document_number": "12.345.678/0001-90",
        "requires_invoice": true,
        "status": "pending_analysis"
    },
    "payment_method": "transfer",
    "payment": {
        "target": {
            "name": "AUDITORES EXEMPLO S.A.",
            "document_number": "12.345.678/0001-90"
        },
        "target_account": {
            "account_number": "123456",
            "account_branch": "0001",
            "account_digit": "0",
            "financial_institution_code": "341",
            "financial_institution_ispb": "60701190"
        }
    }
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `analysis_key` | string | Chave única da análise (UUID). Guarde este valor para as próximas etapas. |
| `status` | string | Status inicial da análise. Sempre retorna `pending_submission`. |
| `requires_invoice` | boolean | Indica se esta análise exige nota fiscal. |
| `manager` | object | Dados do gestor autenticado. |
| `manager.name` | string | Nome do gestor. |
| `manager.manager_key` | string | Chave única do gestor (UUID). |
| `manager.document_number` | string | CNPJ do gestor. |
| `vendor` | object | Dados do fornecedor. |
| `vendor.vendor_key` | string | Chave única do fornecedor. Disponível após aprovação para uso em contratos. |
| `vendor.name` | string | Nome do fornecedor. |
| `vendor.document_number` | string | CPF ou CNPJ do fornecedor. |
| `vendor.requires_invoice` | boolean | Indica se o fornecedor exige nota fiscal. |
| `vendor.status` | string | Status do fornecedor: `pending_analysis` enquanto a análise estiver em curso. |
| `payment_method` | string | Método de pagamento, quando informado. |
| `payment` | object | Dados bancários, quando informados. |

---

## Possíveis erros

STATUS 409

**Fornecedor já ativo**

Já existe um fornecedor ativo (`status = active`) com o CNPJ/CPF informado. Utilize a [listagem de fornecedores](/documentation/iaas/despesas/submissao_despesa/fornecedor/listagem) para obter a `vendor_key`.

```json
{
  "title": "Vendor already exists",
  "description": "Already exists an active vendor with the document number {vendor_document_number}.",
  "translation": "Já existe um fornecedor ativo com o cnpj {vendor_document_number}.",
  "code": "VRG000015"
}
```

STATUS 404

**Gestor não encontrado**

O `manager_key` do agente autenticado não corresponde a nenhum gestor cadastrado na plataforma.

```json
{
  "title": "Manager not found",
  "description": "Manager with the key {manager_key} was not found.",
  "translation": "O gestor com a chave {manager_key} não foi encontrado.",
  "code": "VRG000001"
}
```

STATUS 400

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

O CPF ou CNPJ informado em `vendor_document_number` não é válido.

```json
{
  "title": "Invalid document number",
  "description": "The document number {vendor_document_number} is invalid.",
  "translation": "O documento {vendor_document_number} é inválido.",
  "code": "VRG000002"
}
```

---

## Próximos passos

Com a análise criada (status `pending_submission`), as próximas etapas são:

1. **[Upload de documentos](/documentation/iaas/despesas/submissao_despesa/fornecedor/documentos)** — anexe o contrato social e documentos dos representantes.
2. **[Submissão para análise](/documentation/iaas/despesas/submissao_despesa/fornecedor/submissao)** — encaminhe a análise para revisão da QI Tech.

---

# Documentos da Análise

URL: /documentation/iaas/despesas/submissao_despesa/fornecedor/documentos

Após [criar a análise](/documentation/iaas/despesas/submissao_despesa/fornecedor/criacao), faça o upload dos documentos comprobatórios do fornecedor. É obrigatório ter ao menos um documento antes de [submeter a análise para revisão](/documentation/iaas/despesas/submissao_despesa/fornecedor/submissao).

:::info Tipos de documento aceitos
- `vendor_bylaws` — Contrato social do fornecedor
- `representative_document` — Documento de identificação do representante legal
:::

:::info Status inicial
Documentos enviados via API entram automaticamente com status `pending_adm_approval`, aguardando revisão da QI Tech.
:::

---

## Upload de documento

ENDPOINT /vendor_registry/analysis/{analysis_key}/document
MÉTODO POST

### Path params

| Parâmetro | Tipo | Descrição |
|---|---|---|
| `analysis_key` | string | Chave única da análise (UUID) |

```json title="Request Body"
{
    "name": "Contrato Social - AUDITORES EXEMPLO S.A.",
    "document_type": "vendor_bylaws",
    "document_b64": "JVBERi0xLjQKJcOkw7zDtsOfCjIgMCBvYmoKPDwKL0xlbmd0aCAzIDAgUgo..."
}
```

### Atributos do body

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `name` | string | obrigatório | Nome do documento. Máximo de 255 caracteres. |
| `document_type` | string | obrigatório | Tipo do documento: `vendor_bylaws` ou `representative_document`. |
| `document_b64` | string | obrigatório | Conteúdo do arquivo codificado em Base64. |

## Response

STATUS 201

```json title="Response Body"
{
    "document_name": "Contrato Social - AUDITORES EXEMPLO S.A.",
    "document_key": "d4e5f6a7-b8c9-0123-def4-567890abcdef",
    "document_type": "vendor_bylaws",
    "analysis_key": "c3d4e5f6-a7b8-9012-cdef-345678901234",
    "status": "pending_adm_approval"
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `document_name` | string | Nome do documento. |
| `document_key` | string | Chave única do documento (UUID). |
| `document_type` | string | Tipo do documento: `vendor_bylaws` ou `representative_document`. |
| `analysis_key` | string | Chave da análise à qual o documento pertence. |
| `status` | string | Status do documento. Sempre retorna `pending_adm_approval`. |

---

## Listar documentos de uma análise

ENDPOINT /vendor_registry/analysis/{analysis_key}/documents
MÉTODO GET

### Path params

| Parâmetro | Tipo | Descrição |
|---|---|---|
| `analysis_key` | string | Chave única da análise (UUID) |

## Response

STATUS 200

```json title="Response Body"
{
    "data": [
        {
            "document_name": "Contrato Social - AUDITORES EXEMPLO S.A.",
            "document_key": "d4e5f6a7-b8c9-0123-def4-567890abcdef",
            "document_type": "vendor_bylaws",
            "analysis_key": "c3d4e5f6-a7b8-9012-cdef-345678901234",
            "status": "pending_adm_approval"
        },
        {
            "document_name": "RG - João da Silva",
            "document_key": "e5f6a7b8-c9d0-1234-ef56-7890abcdef12",
            "document_type": "representative_document",
            "analysis_key": "c3d4e5f6-a7b8-9012-cdef-345678901234",
            "status": "approved"
        }
    ]
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `data` | array | Lista de documentos da análise. |
| `data[].document_name` | string | Nome do documento. |
| `data[].document_key` | string | Chave única do documento (UUID). |
| `data[].document_type` | string | Tipo do documento. |
| `data[].analysis_key` | string | Chave da análise. |
| `data[].status` | string | Status do documento: `pending_adm_approval`, `approved` ou `rejected`. |

---

## Consultar documento por chave

Recupere os dados de um documento específico, incluindo URL de download.

ENDPOINT /vendor_registry/analysis/{analysis_key}/documents/{document_key}
MÉTODO GET

### Path params

| Parâmetro | Tipo | Descrição |
|---|---|---|
| `analysis_key` | string | Chave única da análise (UUID) |
| `document_key` | string | Chave única do documento (UUID) |

## Response

STATUS 200

```json title="Response Body"
{
    "document_name": "Contrato Social - AUDITORES EXEMPLO S.A.",
    "document_key": "d4e5f6a7-b8c9-0123-def4-567890abcdef",
    "document_type": "vendor_bylaws",
    "analysis_key": "c3d4e5f6-a7b8-9012-cdef-345678901234",
    "status": "approved",
    "document_url": "https://storage.example.com/documents/d4e5f6a7-b8c9-0123-def4-567890abcdef?X-Amz-Expires=86400&..."
}
```

### Atributos adicionais

| Campo | Tipo | Descrição |
|---|---|---|
| `document_url` | string | URL pré-assinada para download do arquivo. Válida por 24 horas. |

---

## Possíveis erros

STATUS 404

**Análise não encontrada**

A `analysis_key` informada na URL não corresponde a nenhuma análise cadastrada.

```json
{
  "title": "Analysis not found",
  "description": "Analysis with the key {analysis_key} was not found.",
  "translation": "A análise com a chave {analysis_key} não foi encontrada.",
  "code": "VRG000007"
}
```

**Documento não encontrado**

A `document_key` informada na URL não corresponde a nenhum documento desta análise.

```json
{
  "title": "Document not found",
  "description": "Document with the key {document_key} was not found.",
  "translation": "O documento com a chave {document_key} não foi encontrada.",
  "code": "VRG000003"
}
```

STATUS 400

**Formato do documento inválido**

O conteúdo em `document_b64` não é um Base64 válido.

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

---

## Próximos passos

Com ao menos um documento enviado, prossiga para:

**[Submeter a análise](/documentation/iaas/despesas/submissao_despesa/fornecedor/submissao)** — encaminhe para revisão da QI Tech.

---

# Consulta de Fornecedores e Análises

URL: /documentation/iaas/despesas/submissao_despesa/fornecedor/listagem

Recupere os fornecedores ativos e acompanhe o andamento das análises de cadastro em curso.

---

## Listar fornecedores

ENDPOINT /vendor_registry/vendors
MÉTODO GET

### Query params

| Parâmetro | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `name` | string | opcional | Filtra fornecedores cujo nome contenha o valor informado (busca parcial, sem distinção de maiúsculas/minúsculas). |
| `document_number` | string | opcional | Filtra pelo CPF ou CNPJ exato do fornecedor. |
| `status` | string (lista) | opcional | Filtra pelo status do fornecedor. Valores: `pending_analysis`, `active`, `inactive`. Aceita múltiplos valores. |
| `limit` | integer | opcional | Número de itens por página. Mínimo: `0`. Máximo: `1000`. Padrão: `10`. |
| `page` | integer | opcional | Número da página (base zero). Padrão: `0`. |

## Response

STATUS 200

```json title="Response Body"
{
    "data": [
        {
            "vendor_key": "3571e292-3a83-4011-904d-20ee963022ef",
            "name": "AUDITORES EXEMPLO S.A.",
            "document_number": "12.345.678/0001-90",
            "requires_invoice": true,
            "status": "active",
            "payment_method": "transfer"
        },
        {
            "vendor_key": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
            "name": "CVM",
            "document_number": "29.507.878/0001-08",
            "requires_invoice": true,
            "status": "active"
        }
    ],
    "limit": 10,
    "page": 0,
    "is_last_page": true
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `data` | array | Lista de fornecedores. |
| `limit` | integer | Número de itens por página utilizado na consulta. |
| `page` | integer | Número da página atual. |
| `is_last_page` | boolean | Indica se esta é a última página de resultados. |

#### Atributos de cada fornecedor em `data`

| Campo | Tipo | Descrição |
|---|---|---|
| `vendor_key` | string | Chave única do fornecedor. Use este valor na criação de contratos. |
| `name` | string | Nome do fornecedor. |
| `document_number` | string | CPF ou CNPJ do fornecedor. |
| `requires_invoice` | boolean | Indica se o fornecedor exige nota fiscal. |
| `status` | string | Status do fornecedor: `pending_analysis`, `active` ou `inactive`. |
| `payment_method` | string | Método de pagamento padrão, quando cadastrado. |
| `payment` | object | Dados bancários padrão, quando cadastrados. |

#### Status do fornecedor

| Status | Descrição |
|---|---|
| `pending_analysis` | Fornecedor com análise de cadastro em andamento |
| `active` | Fornecedor aprovado e disponível para uso em contratos |
| `inactive` | Fornecedor inativo |

---

## Consultar fornecedor por chave

ENDPOINT /vendor_registry/vendor/{vendor_key}
MÉTODO GET

### Path params

| Parâmetro | Tipo | Descrição |
|---|---|---|
| `vendor_key` | string | Chave única do fornecedor (UUID, 36 caracteres) |

## Response

STATUS 200

```json title="Response Body"
{
    "vendor_key": "3571e292-3a83-4011-904d-20ee963022ef",
    "name": "AUDITORES EXEMPLO S.A.",
    "document_number": "12.345.678/0001-90",
    "requires_invoice": true,
    "status": "active",
    "payment_method": "transfer",
    "payment": {
        "target": {
            "name": "AUDITORES EXEMPLO S.A.",
            "document_number": "12.345.678/0001-90"
        },
        "target_account": {
            "account_number": "123456",
            "account_branch": "0001",
            "account_digit": "0",
            "financial_institution_code": "341",
            "financial_institution_ispb": "60701190"
        }
    }
}
```

## Possíveis erros

STATUS 404

**Fornecedor não encontrado**

A `vendor_key` informada não corresponde a nenhum fornecedor cadastrado.

```json
{
  "title": "Vendor not found",
  "description": "Vendor with the key {vendor_key} was not found.",
  "translation": "O fornecedor com a chave {vendor_key} não foi encontrada.",
  "code": "VRG000014"
}
```

---

## Listar análises

ENDPOINT /vendor_registry/analyses
MÉTODO GET

### Query params

| Parâmetro | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `status` | string (lista) | opcional | Filtra pelo status da análise. Valores: `pending_submission`, `pending_adm_approval`, `approved`, `rejected`, `canceled`, `other_analysis_approved`. Aceita múltiplos valores. |
| `manager_key` | string | opcional | Filtra as análises de um gestor específico. |
| `vendor_key` | string | opcional | Filtra as análises de um fornecedor específico. |
| `limit` | integer | opcional | Número de itens por página. Mínimo: `0`. Máximo: `1000`. Padrão: `10`. |
| `page` | integer | opcional | Número da página (base zero). Padrão: `0`. |

## Response

STATUS 200

```json title="Response Body"
{
    "data": [
        {
            "analysis_key": "c3d4e5f6-a7b8-9012-cdef-345678901234",
            "status": "pending_adm_approval",
            "requires_invoice": true,
            "manager": {
                "name": "EXEMPLO GESTORA LTDA",
                "manager_key": "a7498c6c-1893-42ec-a8f3-bc6ad0c6b52c",
                "document_number": "45.585.471/0001-47"
            },
            "vendor": {
                "vendor_key": "3571e292-3a83-4011-904d-20ee963022ef",
                "name": "AUDITORES EXEMPLO S.A.",
                "document_number": "12.345.678/0001-90",
                "requires_invoice": true,
                "status": "pending_analysis"
            }
        }
    ],
    "limit": 10,
    "page": 0,
    "is_last_page": true
}
```

---

## Consultar análise por chave

ENDPOINT /vendor_registry/analysis/{analysis_key}
MÉTODO GET

### Path params

| Parâmetro | Tipo | Descrição |
|---|---|---|
| `analysis_key` | string | Chave única da análise (UUID) |

## Response

STATUS 200

```json title="Response Body"
{
    "analysis_key": "c3d4e5f6-a7b8-9012-cdef-345678901234",
    "status": "pending_adm_approval",
    "requires_invoice": true,
    "manager": {
        "name": "EXEMPLO GESTORA LTDA",
        "manager_key": "a7498c6c-1893-42ec-a8f3-bc6ad0c6b52c",
        "document_number": "45.585.471/0001-47"
    },
    "vendor": {
        "vendor_key": "3571e292-3a83-4011-904d-20ee963022ef",
        "name": "AUDITORES EXEMPLO S.A.",
        "document_number": "12.345.678/0001-90",
        "requires_invoice": true,
        "status": "pending_analysis"
    },
    "payment_method": "transfer",
    "payment": {
        "target": {
            "name": "AUDITORES EXEMPLO S.A.",
            "document_number": "12.345.678/0001-90"
        },
        "target_account": {
            "account_number": "123456",
            "account_branch": "0001",
            "account_digit": "0",
            "financial_institution_code": "341",
            "financial_institution_ispb": "60701190"
        }
    }
}
```

## Possíveis erros

STATUS 404

**Análise não encontrada**

A `analysis_key` informada não corresponde a nenhuma análise cadastrada.

```json
{
  "title": "Analysis not found",
  "description": "Analysis with the key {analysis_key} was not found.",
  "translation": "A análise com a chave {analysis_key} não foi encontrada.",
  "code": "VRG000007"
}
```

---

## Próximos passos

Com a `vendor_key` de um fornecedor `active` em mãos, prossiga para:

**[Criar contrato](/documentation/iaas/despesas/submissao_despesa/contrato/criacao)** — vincule o fornecedor ao fundo e defina o tipo de despesa.

---

# Submissão para Análise

URL: /documentation/iaas/despesas/submissao_despesa/fornecedor/submissao

Após [criar a análise](/documentation/iaas/despesas/submissao_despesa/fornecedor/criacao) e [fazer upload dos documentos](/documentation/iaas/despesas/submissao_despesa/fornecedor/documentos), submeta a análise para revisão da QI Tech alterando o status para `pending_adm_approval`.

:::caution Pré-requisito
É obrigatório ter ao menos um documento com status `pending_adm_approval` ou `approved` antes de submeter a análise. Caso contrário, a requisição será rejeitada com erro `VGR000030`.
:::

---

## Submeter a análise

ENDPOINT /vendor_registry/analysis/{analysis_key}
MÉTODO PUT

### Path params

| Parâmetro | Tipo | Descrição |
|---|---|---|
| `analysis_key` | string | Chave única da análise (UUID) |

```json title="Request Body"
{
    "status": "pending_adm_approval"
}
```

### Atributos do body

| Campo | Tipo | Obrigatoriedade | Valores aceitos | Descrição |
|---|---|---|---|---|
| `status` | string | obrigatório | `pending_adm_approval`, `pending_submission` | Novo status da análise. Use `pending_adm_approval` para submeter para revisão, ou `pending_submission` para retornar ao rascunho. |

## Response

STATUS 202

```json title="Response Body"
{
    "analysis_key": "c3d4e5f6-a7b8-9012-cdef-345678901234",
    "status": "pending_adm_approval"
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `analysis_key` | string | Chave única da análise. |
| `status` | string | Novo status da análise. |

---

## Ciclo de vida da análise

A tabela abaixo descreve todas as transições de status possíveis e quem as executa:

| Status | Descrição | Quem transita |
|---|---|---|
| `pending_submission` | Análise criada, aguardando submissão | Estado inicial; agente retorna para edição |
| `pending_adm_approval` | Submetida, aguardando revisão da QI Tech | Agente integrador |
| `approved` | Aprovada pela QI Tech; fornecedor ativado | QI Tech (interno) |
| `rejected` | Rejeitada pela QI Tech | QI Tech (interno) |
| `canceled` | Cancelada pelo agente integrador | Agente integrador via [endpoint de cancelamento](/documentation/iaas/despesas/submissao_despesa/fornecedor/cancelamento) |
| `other_analysis_approved` | Outra análise do mesmo fornecedor foi aprovada primeiro | Automático |

### Transições permitidas pelo agente integrador

```
pending_submission ──→ pending_adm_approval  (submissão para revisão)
pending_submission ──→ canceled              (cancelamento)
pending_adm_approval ──→ pending_submission  (retorno para edição)
pending_adm_approval ──→ canceled            (cancelamento)
```

:::info Edição após retorno
Quando a QI Tech retorna a análise para `pending_submission`, é possível atualizar os dados de pagamento e a flag `requires_invoice` antes de submeter novamente. Consulte a página de [atualização de dados](/documentation/iaas/despesas/submissao_despesa/fornecedor/atualizacao).
:::

---

## Possíveis erros

STATUS 400

**Análise sem documentos**

A análise não possui nenhum documento com status `pending_adm_approval` ou `approved`. Faça o [upload de ao menos um documento](/documentation/iaas/despesas/submissao_despesa/fornecedor/documentos) antes de submeter.

```json
{
  "title": "Analysis Submission Must Have At Least One Pending Analysis Document",
  "description": "Analysis with key {analysis_key} must have at least one pending analysis document to be submitted.",
  "translation": "A análise com a chave {analysis_key} deve ter pelo menos um documento de análise pendente para ser enviada.",
  "code": "VGR000030"
}
```

STATUS 409

**Transição de status não permitida**

A transição de status solicitada não é permitida para o status atual da análise.

```json
{
  "title": "Analysis Status Transition Denied",
  "description": "Analysis with key {analysis_key} is not allowed to switch status from {current_status} to {new_status}.",
  "translation": "Análise com chave {analysis_key} não pode trocar de status de {current_status} para {new_status}.",
  "code": "VRG000008"
}
```

**Análise já rejeitada**

Análises rejeitadas não podem ter o status alterado.

```json
{
  "title": "Canceled Analysis",
  "description": "Analysis with key {analysis_key} is already rejected, it can't be updated.",
  "translation": "Análise com chave {analysis_key} está rejeitada, não pode ser atualizada.",
  "code": "VRG0000009"
}
```

**Análise já aprovada**

Análises aprovadas não podem ter o status alterado.

```json
{
  "title": "Completed Analysis",
  "description": "Analysis with key {analysis_key} is already completed, it can't be updated.",
  "translation": "Análise com chave {analysis_key} está finalizada, não pode ser atualizada.",
  "code": "VRG0000010"
}
```

STATUS 404

**Análise não encontrada**

A `analysis_key` informada na URL não corresponde a nenhuma análise cadastrada.

```json
{
  "title": "Analysis not found",
  "description": "Analysis with the key {analysis_key} was not found.",
  "translation": "A análise com a chave {analysis_key} não foi encontrada.",
  "code": "VRG000007"
}
```

---

## Próximos passos

Após submeter a análise, o processo de revisão da QI Tech se inicia. Durante este período:

- **[Acompanhar o status](/documentation/iaas/despesas/submissao_despesa/fornecedor/listagem#consultar-análise-por-chave)** — verifique o progresso da análise.
- **[Responder anotações](/documentation/iaas/despesas/submissao_despesa/fornecedor/anotacoes)** — responda eventuais solicitações da equipe de análise.

Após aprovação, a `vendor_key` do fornecedor estará disponível para uso em contratos de despesa.

---

# Submissão de Despesas

URL: /documentation/iaas/despesas/submissao_despesa/inicio

Esta seção documenta as APIs que viabilizam o processo de Submissão de Despesas para Fundos de Investimento administrados pela QI CTVM. Por meio dessas APIs, é possível registrar contratos com fornecedores, submeter despesas individuais e acompanhar o ciclo de aprovação de cada lançamento.

## Fluxo de submissão

O diagrama abaixo ilustra as etapas do fluxo:

![Etapas do fluxo de submissão de despesas](/img/diagrams/iaas-despesas-inicio.svg)

## Passo a passo

### 0. Cadastro do Fornecedor (pré-requisito)

Antes de criar um contrato, o fornecedor que prestará serviços ao fundo deve estar cadastrado na plataforma. Esse cadastro é realizado pela equipe de operações da QI Tech. Após o cadastro, a `vendor_key` é disponibilizada para uso nos contratos.

**[Acessar documentação do cadastro de fornecedor](/documentation/iaas/despesas/submissao_despesa/fornecedor/criacao)** | **[Consultar fornecedores cadastrados](/documentation/iaas/despesas/submissao_despesa/fornecedor/listagem)**

### 1. Criação do Contrato

Crie um contrato vinculando o fundo a um fornecedor e definindo o tipo de despesa. O contrato é o contêiner que agrupa todas as despesas de uma mesma relação comercial.

**[Acessar documentação da criação do contrato](/documentation/iaas/despesas/submissao_despesa/contrato/criacao)**

### 2. Submissão do Contrato para Aprovação

Após criar e revisar o contrato, submeta-o para análise da QI Tech. O contrato passará para o status `pending_adm_approval` até ser aprovado ou rejeitado.

**[Acessar documentação da submissão do contrato](/documentation/iaas/despesas/submissao_despesa/contrato/submissao)**

### 3. Criação da Despesa

Com o contrato aprovado, crie as despesas individuais informando os dados de pagamento, período de competência e documentos comprobatórios. Ao incluir documentos na criação, a despesa é automaticamente encaminhada para revisão.

**[Acessar documentação da criação da despesa](/documentation/iaas/despesas/submissao_despesa/despesa/criacao)**

### 4. Upload de Documentos (quando não incluídos na criação)

Caso os documentos não tenham sido incluídos na criação da despesa, faça o upload separadamente antes de submeter.

**[Acessar documentação de upload de documentos](/documentation/iaas/despesas/submissao_despesa/documentos/upload)**

### 5. Submissão da Despesa para Aprovação

Submeta a despesa para análise da QI Tech. É obrigatório que ao menos um documento esteja anexado antes da submissão.

**[Acessar documentação da submissão da despesa](/documentation/iaas/despesas/submissao_despesa/despesa/submissao)**

:::info Processamento interno
Após a aprovação da despesa pela QI Tech, o lançamento é processado internamente e registrado na carteira do fundo de forma automática.
:::

## Status do contrato

| Status | Descrição |
|---|---|
| `created` | Contrato criado, aguardando submissão |
| `pending_adm_approval` | Submetido, aguardando análise da QI Tech |
| `approved` | Aprovado pela QI Tech |
| `rejected` | Rejeitado pela QI Tech |
| `canceled` | Cancelado pelo agente integrador |

## Status da despesa

| Status | Descrição |
|---|---|
| `created` | Despesa criada, aguardando documentos ou submissão |
| `pending_adm_approval` | Submetida (ou criada com documentos), aguardando análise da QI Tech |
| `approved` | Aprovada pela QI Tech |
| `rejected` | Rejeitada pela QI Tech |
| `canceled` | Cancelada pelo agente integrador |