# QI Tech — Investment-as-a-Service › Liquidação de Ativos

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

Índice:
- Layout CNAB 444 — Baixa (/documentation/iaas/liquidacao_ativos/arquivo/cnab444_baixa)
- Baixa por Arquivo (/documentation/iaas/liquidacao_ativos/arquivo/inicio)
- Inserção de Liquidações (/documentation/iaas/liquidacao_ativos/ativos/)
- Remoção de Liquidações (/documentation/iaas/liquidacao_ativos/ativos/remocao_liquidacoes)
- Webhooks de Liquidação (/documentation/iaas/liquidacao_ativos/ativos/webhook)
- Fluxo de liquidação de ativos (/documentation/iaas/liquidacao_ativos/fluxo_liquidacao)
- Liquidação de Ativos (/documentation/iaas/liquidacao_ativos/inicio)
- Criação do Lote de Pagamento (/documentation/iaas/liquidacao_ativos/lote_pagamento/criacao)
- Encerrar Inserção no Lote de Pagamento (/documentation/iaas/liquidacao_ativos/lote_pagamento/fechamento)
- Listagem de Lotes de Pagamento (/documentation/iaas/liquidacao_ativos/lote_pagamento/listagem)
- Webhooks do Lote de Pagamento (/documentation/iaas/liquidacao_ativos/lote_pagamento/webhook)

---

# Layout CNAB 444 — Baixa

URL: /documentation/iaas/liquidacao_ativos/arquivo/cnab444_baixa

Layout do arquivo de **remessa de baixa** (liquidação) aceito pela QI CTVM. A estrutura é a mesma do [arquivo de cessão](/documentation/iaas/negociacao_recebiveis/arquivo/cnab444): 444 posições, header `0`, detalhes `1` e trailer `9`. O que muda é o **código de ocorrência**, o **valor pago** e a **data da liquidação**.

:::tip Reaproveite a linha da cessão
A forma mais segura de montar o arquivo de baixa é partir da linha enviada na cessão e alterar apenas três campos: ocorrência (109–110), valor pago (083–092) e data da liquidação (095–100). O identificador do ativo — nº de controle do participante — **precisa ser exatamente o mesmo** usado na cessão.
:::

## O que muda em relação ao arquivo de cessão

| Posição | Campo | Na cessão | Na baixa |
|---|---|---|---|
| 083–092 | Valor pago | Zeros | **Valor efetivamente pago**, 2 decimais |
| 095–100 | Data da liquidação | Zeros | **Data do pagamento**, `DDMMAA` |
| 109–110 | Identificação da ocorrência | `01` | `04`, `14`, `75` ou `77` |
| 150–150 | Identificação | Livre | Branco ou `0` |
| 157–158 | 1ª instrução | Livre | `00` |
| 159–159 | 2ª instrução | Livre | `0` |
| 381–394 | CNPJ do cedente | Conferido o nome | **CNPJ conferido com dígito verificador** |

Todos os demais campos seguem as mesmas regras de preenchimento, domínios e obrigatoriedades da [tabela do registro de detalhe da cessão](/documentation/iaas/negociacao_recebiveis/arquivo/cnab444#registro-detalhe).

## Ocorrências aceitas

| Código | Significado | Efeito na carteira | Origem do recurso |
|---|---|---|---|
| `77` | **Baixa por depósito do sacado** | Liquidação integral do ativo (`asset_settlement`) | Sacado |
| `14` | **Pagamento parcial** | Amortização do ativo (`asset_amortization`) | Sacado |
| `75` | **Baixa por depósito do cedente** | Liquidação integral do ativo (`asset_settlement`) | Cedente |
| `04` | **Pagamento a menor** | Liquidação do ativo (`asset_settlement`) | Sacado |

:::caution Só essas quatro
Qualquer outro código de ocorrência recusa o arquivo com a mensagem *"This field only allows one of this values: ['04', '14', '75', '77']"*. Ocorrências de aquisição (`01`, `80`, `81`, `84`) pertencem ao [arquivo de cessão](/documentation/iaas/negociacao_recebiveis/arquivo/cnab444).
:::

## Como o ativo é identificado

| Tipo de ativo | Campo usado como identificador | Complemento |
|---|---|---|
| Duplicatas, CT-e e contratos | **Nº de controle do participante** (038–062) | — |
| CCB e demais operações de crédito | **Nº do documento** (111–120), que corresponde ao número do contrato | A parcela é identificada pela **data de vencimento** (121–126) |

:::caution O identificador precisa bater com o da cessão
Se o número de controle do participante não corresponder a um ativo encarteirado no fundo, aquela liquidação falha individualmente no processamento — o lote continua, mas termina como `processed_with_failures`.
:::

## Exemplo comentado

Baixa de dois títulos cedidos no exemplo de cessão: o primeiro liquidado integralmente pelo sacado, o segundo com pagamento parcial.

```text title="CB101001.REM"
01REMESSA01COBRANCA       00000011222333000181INDUSTRIA EXEMPLO S/A         ...MX...000001
1...0CTRL000001...0000151000  101025        77000100001101025...COMERCIO EXEMPLO ALFA LTDA...000002
1...0CTRL000002...0000050000  101025        14000200002101025...COMERCIO EXEMPLO BETA LTDA...000003
9                                                                              ...000004
```

| Linha | Leitura |
|---|---|
| Detalhe 1 | Ativo `CTRL000001` liquidado em 10/10/2025 — ocorrência `77`, valor pago R$ 1.510,00 (integral) |
| Detalhe 2 | Ativo `CTRL000002` amortizado em 10/10/2025 — ocorrência `14`, valor pago R$ 500,00 (parcial) |

### Arquivos de exemplo

| Arquivo | Espécie | O que traz |
|---|---|---|
| [Baixa de duplicatas](/downloads/modelos_arquivo/exemplo_baixa_duplicatas_cnab444.rem) | `01` | Uma liquidação integral (`77`) e um pagamento parcial (`14`), identificados pelo nº de controle do participante |
| [Baixa de CCB](/downloads/modelos_arquivo/exemplo_baixa_ccb_cnab444.rem) | `41` | Duas parcelas identificadas pelo número do contrato e pela data de vencimento |

## Checklist antes de enviar

- [ ] Todas as linhas com exatamente 444 caracteres
- [ ] Ocorrência `04`, `14`, `75` ou `77` nas posições 109–110
- [ ] Valor pago preenchido nas posições 083–092, com 2 decimais e sem vírgula
- [ ] Data da liquidação preenchida nas posições 095–100, no formato `DDMMAA`
- [ ] Nº de controle do participante idêntico ao enviado na cessão
- [ ] CNPJ do cedente (381–394) e CPF/CNPJ do sacado (221–234) com dígito verificador válido
- [ ] 1ª instrução `00`, 2ª instrução `0` e identificação (150) em branco
- [ ] Sem acentos, `Ç` ou caracteres especiais
- [ ] Trailer fechando o arquivo com o sequencial da última linha

---

# Baixa por Arquivo

URL: /documentation/iaas/liquidacao_ativos/arquivo/inicio

A baixa (liquidação) de ativos já encarteirados no fundo pode ser feita de duas formas: **enviando um arquivo** com todas as liquidações do dia, pelo portal do gestor/consultor, ou **inserindo liquidação a liquidação pela API**. As duas produzem o mesmo lote de pagamento e passam pela mesma conciliação.

| | Envio por arquivo | Inserção pela API |
|---|---|---|
| **Como funciona** | Um arquivo com todas as liquidações | Uma requisição por liquidação |
| **Formatos** | CNAB 444 e CSV | JSON |
| **Disponível em** | Portal do gestor e do consultor | [API de Liquidação de Ativos](/documentation/iaas/liquidacao_ativos/inicio) |
| **Indicado para** | Rotina diária de baixas em volume, a partir do retorno bancário | Baixas pontuais e integrações em tempo real |

:::info Baixa por arquivo é um fluxo de tela
Hoje o envio de arquivo de baixa está disponível no **portal**. Pela API de integração, a baixa é feita pelo fluxo de [lote de pagamento + liquidações](/documentation/iaas/liquidacao_ativos/lote_pagamento/criacao), sem arquivo.
:::

## Formatos aceitos

| Formato | Extensão | Indicado para | Modelo |
|---|---|---|---|
| **CNAB 444** — duplicatas e CT-e | `.rem` · `.txt` | Quem já recebe retorno CNAB do banco cobrador. Layout em [Layout CNAB 444 — Baixa](/documentation/iaas/liquidacao_ativos/arquivo/cnab444_baixa) | [Exemplo](/downloads/modelos_arquivo/exemplo_baixa_duplicatas_cnab444.rem) |
| **CNAB 444** — CCB e operações de crédito | `.rem` · `.txt` | Mesmo layout, com o ativo identificado pelo número do contrato | [Exemplo](/downloads/modelos_arquivo/exemplo_baixa_ccb_cnab444.rem) |
| **CSV** | `.csv` | Planilha simples, com uma linha por liquidação, para qualquer tipo de ativo. Layout na seção [CSV de baixa](#csv-de-baixa) | [Exemplo](/downloads/modelos_arquivo/exemplo_baixa_liquidacoes.csv) |

## Passo a passo pela tela

1. Acesse **Ativos › Liquidações** e clique em **Novo lote por arquivo**.
2. Informe uma **descrição** para identificar o lote.
3. Selecione a **conta do fundo** que receberá o crédito das liquidações.
4. Arraste o arquivo (`.rem`, `.txt` ou `.csv`) e confirme.

O portal cria o lote de pagamento, envia o arquivo e dispara a validação. A tela passa a mostrar o lote com o progresso — total de liquidações, processadas e falhas.

## O que acontece depois do envio

| Etapa do lote | O que significa |
|---|---|
| Aguardando arquivo | Lote criado, arquivo ainda não enviado |
| Validação em andamento | Arquivo recebido, sendo conferido linha a linha |
| Criando o lote | Arquivo válido, lote de pagamento sendo criado |
| Inserindo as liquidações | Cada linha está virando uma liquidação |
| Concluído | Todas as liquidações processadas |
| Concluído com falhas | Lote processado, mas com liquidações que falharam individualmente |
| Recusado | Arquivo recusado na validação — nada foi processado |

:::caution Validação é tudo ou nada
Uma linha inválida recusa o arquivo inteiro. O portal informa o número da linha e a descrição do erro. Corrija e envie um lote novo, com um novo identificador.
:::

Depois que o lote é encerrado e o pagamento confirmado, cada liquidação é conciliada individualmente na carteira do fundo — o mesmo comportamento descrito no [Fluxo de liquidação](/documentation/iaas/liquidacao_ativos/fluxo_liquidacao). Uma liquidação pode falhar sozinha (por exemplo, ativo não encontrado na carteira) sem derrubar as demais.

## CSV de baixa

Arquivo com cabeçalho na primeira linha, separado por `;` ou `,`. Limite de 850.000 linhas.

```csv title="exemplo_baixa_liquidacoes.csv"
asset_type;total_value;settlement_type;external_id;installment_number;collection_origin_type
duplicata_mercantil;1510.00;asset_settlement;CTRL000001;;borrower
duplicata_mercantil;500.00;asset_amortization;CTRL000002;;borrower
ccb;350.75;installment_settlement;CONTRATO-0001;3;borrower
```

### Colunas

| Coluna | Obrigatoriedade | Descrição |
|---|---|---|
| `asset_type` | obrigatória | Tipo do ativo. Ver [valores aceitos](#tipos-de-ativo-aceitos) |
| `total_value` | obrigatória | Valor da liquidação. Aceita `.` ou `,` como separador decimal |
| `settlement_type` | obrigatória | Tipo de liquidação. Ver [tipos de liquidação](#tipos-de-liquidação) |
| `installment_number` | obrigatória (coluna) | Número da parcela. Preencha para ativos com parcelas (CCB); deixe vazio para duplicatas e contratos |
| `external_id` **ou** `contract_number` | obrigatória | Identificador do ativo. Use `external_id` para duplicatas/contratos (o mesmo número de controle enviado na cessão) e `contract_number` para CCBs |
| `collection_origin_type` | opcional | Quem pagou: `borrower` (sacado), `assignor` (cedente) ou `collection_agent` (agente de cobrança) |
| `remaining_face_value` | opcional | Saldo remanescente do valor de face. Aceito **somente** com `settlement_type: installment_amortization` |

:::caution A coluna de identificação define o lote inteiro
Um mesmo arquivo usa `external_id` **ou** `contract_number` — não os dois. Se nenhuma das duas colunas existir, o arquivo é recusado.
:::

### Tipos de liquidação

| Valor | Significado |
|---|---|
| `asset_settlement` | Liquidação integral do ativo |
| `asset_amortization` | Pagamento parcial do ativo |
| `installment_settlement` | Liquidação integral de uma parcela |
| `installment_amortization` | Pagamento parcial de uma parcela |
| `installment_partial_refund` / `asset_partial_refund` | Devolução parcial |
| `installment_refund` / `asset_refund` | Devolução integral |
| `fine_payment` / `installment_fine_payment` | Pagamento de multa |
| `gloss` | Glosa |
| `canceled` | Cancelamento |
| `rco_revenue` | Receita de RCO |

### Tipos de ativo aceitos

`ccb` · `cce` · `structured_ccb` · `structured_cce` · `structured_nce` · `structured_cci` · `duplicata_mercantil` · `duplicata_servicos` · `discounted_contract` · `cte`

**[📄 Baixar CSV de exemplo](/downloads/modelos_arquivo/exemplo_baixa_liquidacoes.csv)**

## Erros mais comuns

| Erro | Causa |
|---|---|
| `missing_fields: [...]` | Faltou uma coluna obrigatória no cabeçalho do CSV |
| `invalid asset_type: ...` | Tipo de ativo fora da lista aceita |
| `invalid settlement_type: ...` | Tipo de liquidação fora da lista aceita |
| `invalid total_value: ...` | Valor com caractere inesperado ou vazio |
| `invalid external_id` / `contract_number` | Identificador em branco |
| `remaining_face_value is only allowed for settlement_type installment_amortization` | Saldo remanescente informado no tipo errado |
| `unmapped cnab layout` | Arquivo CNAB com linhas fora de 444 ou 500 posições |

---

# Inserção de Liquidações

URL: /documentation/iaas/liquidacao_ativos/ativos/

Endpoint para inserir liquidações individuais em um lote de pagamento previamente criado. Cada liquidação representa um pagamento (total ou parcial) referente a um ativo da carteira do fundo — como liquidação de parcela, amortização, recompra ou pagamento de juros.

:::info Liquidação vs Recompra
Tanto a liquidação quanto a recompra de ativos são realizadas através deste endpoint. O campo `collection_origin_type` diferencia as duas operações:
- `borrower` — para **liquidações** (pagamento realizado pelo sacado/devedor).
- `assignor` — para **recompras** (pagamento realizado pelo cedente).
:::

:::tip Onde estou no fluxo?
Este é o **2º passo** do fluxo de liquidação. Antes deste passo, você deve ter [criado o lote de pagamento](/documentation/iaas/liquidacao_ativos/lote_pagamento/criacao).
:::

## Request

ENDPOINT /settlement/fund_class/{fund_class_key}/payment_batch/{external_id}/settlement
MÉTODO POST

### Path params

| Parâmetro | Tipo | Descrição |
|---|---|---|
| `external_id` | string | O `external_id` do lote de pagamento onde a liquidação será inserida. |

```json title="Request Body"
{
    "asset_type": "ccb",
    "total_value": 130.50,
    "external_id": "931e9437-d025-41ab-bb53-6b94e10fd361",
    "settlement_type": "installment_settlement",
    "contract_number": "0123456789/ABC",
    "installment_number": 1,
    "collection_date": "2025-01-01",
    "collection_origin_type": "borrower"
}
```

### Atributos do body

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `asset_type` | string | obrigatório | Tipo de ativo. Veja [enumeradores de `asset_type`](#enumeradores-de-asset_type). Máximo de 255 caracteres. |
| `total_value` | number | obrigatório | Valor total do pagamento (com duas casas decimais). |
| `external_id` | string | obrigatório | Chave única de identificação desta liquidação no sistema do parceiro integrador. Máximo de 50 caracteres. |
| `settlement_type` | string | obrigatório | Tipo de liquidação. Veja [enumeradores de `settlement_type`](#enumeradores-de-settlement_type). Máximo de 50 caracteres. |
| `collection_origin_type` | string | obrigatório | Determina se a operação é uma liquidação (`borrower`) ou uma recompra (`assignor`). Veja [enumeradores de `collection_origin_type`](#enumeradores-de-collection_origin_type). |
| `contract_number` | string | opcional | Número do contrato referente ao ativo. Máximo de 50 caracteres. |
| `asset_external_id` | string | opcional | Chave única de identificação do ativo no sistema, fornecida na cessão. Máximo de 50 caracteres. |
| `asset_key` | string | opcional | Chave interna do ativo na QI Tech (UUID, 36 caracteres). |
| `if_code` | string | opcional | Código de instrumento financeiro (B3). Máximo de 36 caracteres. |
| `participant_control_number` | string | opcional | Número de controle do participante fornecido na cessão. Máximo de 50 caracteres. |
| `installment_number` | integer | opcional | Número da parcela a ser paga. Obrigatório para tipos de liquidação por parcela. |
| `installment_maturity_date` | string | opcional | Data de vencimento da parcela no formato `YYYY-MM-DD`. |
| `installment_external_id` | string | opcional | Identificador externo da parcela. Máximo de 50 caracteres. |
| `collection_date` | string | opcional | Data de pagamento no formato `YYYY-MM-DD`. Campo destinado para controle do integrador. |

:::caution Atenção
Os campos `asset_external_id`, `contract_number` e `asset_key` são formas alternativas de identificar o ativo no sistema. Informe **apenas um** deles — não envie múltiplos simultaneamente.
:::

:::info Diferença entre external_id
O campo `external_id` no corpo da requisição se refere ao identificador da **liquidação**. O campo `external_id` na URL se refere ao identificador do **lote de pagamento**.
:::

#### Enumeradores de `asset_type`

| Valor | Descrição |
|---|---|
| `ccb` | Cédula de Crédito Bancário |
| `cce` | Cédula de Crédito à Exportação |
| `structured_ccb` | Cédula de Crédito Bancário Estruturada |
| `structured_cce` | Cédula de Crédito à Exportação Estruturada |
| `structured_nce` | Nota de Crédito à Exportação Estruturada |
| `structured_cci` | Cédula de Crédito Imobiliário Estruturada |
| `duplicata_mercantil` | Duplicata Mercantil |
| `duplicata_servicos` | Duplicata de Serviços |
| `discounted_contract` | Contrato |

#### Enumeradores de `settlement_type`

| Valor | Descrição |
|---|---|
| `asset_settlement` | Liquidação total do ativo. |
| `asset_amortization` | Amortização do ativo (carência). |
| `fine_payment` | Pagamento de juros ou mora do ativo. |
| `installment_settlement` | Liquidação de parcela. Obrigatório informar `installment_number`. |
| `installment_amortization` | Amortização de parcela. Obrigatório informar `installment_number`. |
| `installment_fine_payment` | Pagamento de juros ou mora de parcela. Obrigatório informar `installment_number`. |
| `gloss` | Glosa de parcela. Obrigatório informar `installment_number`. |

#### Enumeradores de `collection_origin_type`

| Valor | Descrição |
|---|---|
| `borrower` | Liquidação — pagamento realizado pelo sacado/devedor. |
| `assignor` | Recompra — pagamento realizado pelo cedente. |

## Response

STATUS 201

```json title="Response Body"
{
    "status": "validated",
    "total_value": 130.50,
    "external_id": "931e9437-d025-41ab-bb53-6b94e10fd361",
    "type": "installment_settlement",
    "settlement_key": "b2c3d4e5-f6a7-8901-abcd-ef1234567890",
    "installment_number": 1,
    "settlement_result": 0.0,
    "total_number_of_units": 1,
    "collection_origin_type": "borrower",
    "assets": [
        {
            "asset_key": "f34e9437-d025-41ab-bb53-6b94e10fd361",
            "number_of_units": 1,
            "present_value": 1250.00,
            "installment_face_value": 130.50
        }
    ]
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `status` | string | Status da liquidação. Após inserção bem-sucedida, retorna `validated`. |
| `total_value` | number | Valor total do pagamento. |
| `external_id` | string | Chave externa da liquidação fornecida pelo parceiro. |
| `type` | string | Tipo de liquidação. |
| `settlement_key` | string | Identificador único da liquidação gerado pela QI Tech (UUID). |
| `installment_number` | integer | Número da parcela. Presente quando aplicável. |
| `settlement_result` | number | Resultado da liquidação. Presente quando calculado. |
| `total_number_of_units` | integer | Quantidade total de unidades de ativo afetadas pela liquidação. |
| `collection_origin_type` | string | Tipo de origem da cobrança (`borrower` ou `assignor`). Presente quando informado na requisição. |
| `assets` | array | Lista de ativos afetados pela liquidação. Veja [Atributos de `assets`](#atributos-de-assets). |

#### Atributos de `assets`

| Campo | Tipo | Descrição |
|---|---|---|
| `asset_key` | string | Identificador único do ativo (UUID). |
| `number_of_units` | integer | Quantidade de unidades do ativo. |
| `present_value` | number | Valor presente do ativo em reais. |
| `installment_face_value` | number | Valor de face da parcela. Presente quando aplicável. |
| `installment_post_maturity_interest_value` | number | Valor de juros pós-vencimento da parcela. Presente quando aplicável. |
| `installment_delay_interest_value` | number | Valor de juros de atraso da parcela. Presente quando aplicável. |
| `installment_delay_fine_value` | number | Valor de multa de atraso da parcela. Presente quando aplicável. |

## Possíveis erros

STATUS 404

**Lote de pagamento não encontrado**

O `external_id` do lote informado na URL não corresponde a nenhum lote cadastrado para este fundo. Verifique se o identificador está correto.

```json
{
  "title": "Payment batch not found",
  "description": "The Payment Batch with external_id {payment_batch_external_id} was not found",
  "translation": "O Lote de Pagamento com identificador externo {payment_batch_external_id} não foi encontrado",
  "code": "SET000010"
}
```

STATUS 400

**Liquidação com external_id duplicado**

Já existe uma liquidação cadastrada com o `external_id` informado neste lote. Cada liquidação deve ter um identificador único. Gere um novo `external_id` e tente novamente.

```json
{
  "title": "Already Exists Settlement With External Id",
  "description": "The settlement with external_id {settlement_external_id} in payment batch with external id {payment_batch_external_id} already exists",
  "translation": "a liquidação com identificador {settlement_external_id} no lote de identificador {payment_batch_external_id} já existe",
  "code": "SET000013"
}
```

## Próximos passos

Após inserir todas as liquidações desejadas, o fluxo continua com:

1. **[Encerramento do lote](/documentation/iaas/liquidacao_ativos/lote_pagamento/fechamento)** — sinalize que todas as liquidações foram inseridas para que o processamento seja iniciado.

---

# Remoção de Liquidações

URL: /documentation/iaas/liquidacao_ativos/ativos/remocao_liquidacoes

Endpoint para descartar uma liquidação individual previamente inserida em um lote de pagamento. Somente liquidações em lotes que ainda não foram encerrados podem ser removidas.

:::tip Quando utilizar
Use este endpoint quando precisar remover uma liquidação incorreta ou indesejada antes de [encerrar o lote](/documentation/iaas/liquidacao_ativos/lote_pagamento/fechamento). Após o encerramento do lote, não é possível remover liquidações individuais.
:::

## Request

ENDPOINT /settlement/fund_class/{fund_class_key}/payment_batch/{external_id}/settlement/{settlement_external_id}
MÉTODO PUT

### Path params

| Parâmetro | Tipo | Descrição |
|---|---|---|
| `external_id` | string | O `external_id` do lote de pagamento. |
| `settlement_external_id` | string | O `external_id` da liquidação que será descartada. |

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

### Atributos do body

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `status` | string | obrigatório | Novo status da liquidação. Para descartar, envie `discarded`. |

## Response

STATUS 200

```json title="Response Body"
{
    "external_id": "931e9437-d025-41ab-bb53-6b94e10fd361",
    "status": "discarded"
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `external_id` | string | Chave externa da liquidação fornecida pelo parceiro. |
| `status` | string | Novo status da liquidação: `discarded`. |

## Possíveis erros

STATUS 404

**Liquidação não encontrada**

O `settlement_external_id` informado na URL não corresponde a nenhuma liquidação cadastrada neste lote. Verifique se os identificadores do lote e da liquidação estão corretos.

```json
{
  "title": "Settlement not found",
  "description": "The Settlement with external_id {external_id} was not found",
  "translation": "A Liquidação com identificador externo {external_id} não foi encontrada",
  "code": "SET000011"
}
```

STATUS 400

**Status inválido**

O valor informado no campo `status` não é válido. Para remoção, utilize apenas `discarded`.

```json
{
  "title": "Invalid status",
  "description": "The status given: {status} is not suported.",
  "translation": "O status: {status} não possui suporte.",
  "code": "SET000026"
}
```

STATUS 400

**Lote já encerrado**

O lote de pagamento já foi encerrado e não permite mais alterações nas liquidações. Não é possível remover liquidações de lotes que já passaram do status `pending_settlements_insertion`.

```json
{
  "title": "Payment Batch Status mismatch",
  "description": "Payment batch of key: {payment_batch_key} with status: {current} was expected to be: {expected}",
  "translation": "O lote de pagamento com chave: {payment_batch_key} e com status: {current} não passou, era esperado que fosse: {expected}",
  "code": "SET000016"
}
```

STATUS 400

**Status da liquidação incompatível**

A liquidação está em um status que não permite ser descartada. Apenas liquidações com status `validated` podem ser removidas.

```json
{
  "title": "Settlement type mismatch",
  "description": "The settlement given has the status: {current_status} and was expected: {expected_status}",
  "translation": "A liquidação com status: {current_status} era esperado ter: {expected_status}",
  "code": "SET000024"
}
```

---

# Webhooks de Liquidação

URL: /documentation/iaas/liquidacao_ativos/ativos/webhook

Ao longo do processamento das liquidações, o sistema envia webhooks para notificar o parceiro integrador sobre mudanças de status de cada liquidação individual. Todos os webhooks possuem o tipo `settlement.settlement_status_change` e identificam a liquidação pelo `settlement_external_id` fornecido na criação.

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

## Fluxo de status da liquidação

Cada liquidação inserida no lote fica em `validated` e só é processada depois que o lote de pagamento atinge `paid`. A partir daí ela chega a um dos dois status finais que geram webhook: `settled` ou `discarded`. O status `validated` **não** dispara notificação — ele é o resultado da própria chamada de [inserção da liquidação](/documentation/iaas/liquidacao_ativos/ativos).

![Fluxo de status da liquidação, destacando os dois status finais que geram webhook](/img/diagrams/iaas-liquidacao-ativos-ativos-webhook.svg)

_Como ler o diagrama: **contorno tracejado** = status sem webhook · **verde** = conclusão com sucesso · **vermelho** = encerramento sem movimentação financeira._

## Estrutura do webhook

Todos os webhooks de liquidação seguem a mesma estrutura base:

| Campo | Tipo | Descrição |
|---|---|---|
| `webhook_type` | string | Sempre `settlement.settlement_status_change`. |
| `webhook_datetime` | string | Data e hora do evento no formato ISO 8601. |
| `data` | array | Lista com os dados do evento. Veja tabela abaixo. |

#### Atributos de cada objeto em `data`

Os campos condicionais são ecoados diretamente do que foi enviado na criação da liquidação. O payload varia conforme o `settlement_type` e o método de identificação do ativo utilizado.

**Campos sempre presentes:**

| Campo | Tipo | Descrição |
|---|---|---|
| `payment_batch_external_id` | string | O `external_id` do lote de pagamento. |
| `settlement_external_id` | string | O `external_id` da liquidação. |
| `settlement_status` | string | Novo status da liquidação. |
| `settlement_type` | string | Tipo de liquidação. |
| `total_value` | number | Valor total da liquidação em reais. |
| `fund_class_document_number` | string | CNPJ do fundo associado. |
| `fund_class_key` | string | Chave do fundo na QI Tech (UUID). |
| `asset_key` | string | Chave interna do ativo na QI Tech (UUID). |

**Identificação do ativo — apenas um dos campos abaixo estará presente, conforme o que foi informado na criação:**

| Campo | Tipo | Descrição |
|---|---|---|
| `contract_number` | string | Número do contrato. Presente se informado na criação. |
| `asset_external_id` | string | `external_id` do ativo no sistema do parceiro. Presente se informado na criação. |

**Demais campos ecoados quando informados:**

| Campo | Tipo | Descrição |
|---|---|---|
| `if_code` | string | Código de instrumento financeiro (B3). Presente se informado na criação da liquidação. |
| `participant_control_number` | string | Número de controle do participante. Presente se informado na criação da liquidação. |
| `source_document_number` | string | CPF ou CNPJ da contraparte financeira. Presente se informado na [criação do lote](/documentation/iaas/liquidacao_ativos/lote_pagamento/criacao). |

**Campos de parcela — presentes apenas para tipos de liquidação por parcela (`installment_settlement`, `installment_amortization`, `installment_fine_payment`, `gloss`):**

| Campo | Tipo | Descrição |
|---|---|---|
| `installment_number` | integer | Número da parcela. |
| `installment_maturity_date` | string | Data de vencimento da parcela no formato `YYYY-MM-DD`. Presente quando informado na criação. |
| `installment_external_id` | string | `external_id` da parcela. Presente quando informado na criação. |

```json title="Estrutura padrão do webhook"
{
    "data": [
        {
            "payment_batch_external_id": "ac597f90-a13e-4f78-86f0-11c66f5fa6d6",
            "settlement_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
            "settlement_status": "STATUS",
            "settlement_type": "installment_settlement",
            "total_value": 130.50,
            "fund_class_document_number": "60.910.091/0001-24",
            "fund_class_key": "8e2d1c4b-3a5f-4e6d-9b7c-1a2b3c4d5e6f",
            "asset_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c",
            "contract_number": "0032226586/NNT",
            "installment_number": 3
        }
    ],
    "webhook_type": "settlement.settlement_status_change",
    "webhook_datetime": "2024-04-23T15:08:30Z"
}
```

---

## Eventos por status

### Liquidação Concluída

STATUS settled

Enviado quando a liquidação é processada com sucesso e o valor foi devidamente conciliado na carteira do fundo. Este é o status final de uma liquidação bem-sucedida — a partir desse momento, a movimentação financeira está efetivada.

```json title="Webhook Body"
{
    "data": [
        {
            "payment_batch_external_id": "ac597f90-a13e-4f78-86f0-11c66f5fa6d6",
            "settlement_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
            "settlement_status": "settled",
            "settlement_type": "installment_settlement",
            "total_value": 130.50,
            "fund_class_document_number": "60.910.091/0001-24",
            "fund_class_key": "8e2d1c4b-3a5f-4e6d-9b7c-1a2b3c4d5e6f",
            "asset_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c",
            "contract_number": "0032226586/NNT",
            "installment_number": 3
        }
    ],
    "webhook_type": "settlement.settlement_status_change",
    "webhook_datetime": "2024-04-23T15:08:30Z"
}
```

---

### Liquidação Descartada

STATUS discarded

Enviado quando a liquidação é descartada do fluxo de processamento. Liquidações descartadas não geram movimentação financeira. Existem três situações que causam esse status:

1. **Remoção manual antes do encerramento do lote** — o parceiro integrador remove a liquidação via endpoint de [remoção de liquidações](/documentation/iaas/liquidacao_ativos/ativos/remocao_liquidacoes) enquanto o lote ainda está aberto.
2. **Descarte interno após revisão** — a equipe QI Tech descarta uma liquidação que estava em revisão manual (`pending_validation`), por exemplo por inconsistência nos dados.
3. **Rejeição** — durante o processamento, a carteira do fundo retorna uma rejeição definitiva para uma liquidação com valor zero. Nesses casos, o sistema determina que reprocessar a liquidação produziria o mesmo resultado e a descarta.

```json title="Webhook Body"
{
    "data": [
        {
            "payment_batch_external_id": "ac597f90-a13e-4f78-86f0-11c66f5fa6d6",
            "settlement_external_id": "1caff47c-bd05-48b0-a6bc-9569f5070f6b",
            "settlement_status": "discarded",
            "settlement_type": "installment_settlement",
            "total_value": 130.50,
            "fund_class_document_number": "60.910.091/0001-24",
            "fund_class_key": "8e2d1c4b-3a5f-4e6d-9b7c-1a2b3c4d5e6f",
            "asset_key": "b7d3e2a1-4c5f-4e8b-9d1a-2f3c4e5a6b7c",
            "contract_number": "0032226586/NNT",
            "installment_number": 3
        }
    ],
    "webhook_type": "settlement.settlement_status_change",
    "webhook_datetime": "2024-04-23T15:08:30Z"
}
```

---

---

# Fluxo de liquidação de ativos

URL: /documentation/iaas/liquidacao_ativos/fluxo_liquidacao

Esta página oferece uma visão holística do fluxo de liquidação de ativos já encarteirados no fundo: desde a criação do lote de pagamento até a conclusão das liquidações e a atualização da carteira. Acompanhe a evolução dos **status do lote**, dos **status de cada liquidação** e dos **webhooks** 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 lote, com cada liquidação e quais webhooks você receberá após o processamento.
:::

{`
.cf-legend{display:flex;flex-wrap:wrap;gap:8px;margin-bottom:24px}
.cf-legend-item{display:flex;align-items:center;gap:6px;font-size:0.8rem;font-weight:600}
.cf-legend-dot{width:12px;height:12px;border-radius:3px}

.cf-step{position:relative;margin-bottom:4px}
.cf-step:not(:last-child)::after{content:'';display:block;width:2px;height:16px;margin:0 auto;background:var(--ifm-color-emphasis-300)}

.cf-card{border:1.5px solid var(--ifm-color-emphasis-200);border-radius:10px;padding:16px 20px;transition:box-shadow 0.2s,border-color 0.2s;cursor:pointer;background:var(--ifm-background-surface-color,var(--ifm-background-color))}
.cf-card:hover{box-shadow:0 4px 16px rgba(0,0,0,0.08);border-color:var(--ifm-color-primary)}

.cf-card-header{display:flex;align-items:center;gap:10px;flex-wrap:wrap}
.cf-num{width:28px;height:28px;border-radius:50%;display:flex;align-items:center;justify-content:center;font-size:0.8rem;font-weight:800;color:#fff;flex-shrink:0}
.cf-num-int{background:#3b82f6}
.cf-num-qi{background:#8b5cf6}
.cf-num-ges{background:#d946ef}
.cf-title{font-size:1rem;font-weight:700;color:var(--ifm-font-color-base)}
.cf-actor{font-size:0.7rem;font-weight:700;padding:2px 8px;border-radius:12px;margin-left:auto}
.cf-actor-int{background:rgba(59,130,246,0.12);color:#2563eb}
.cf-actor-qi{background:rgba(139,92,246,0.12);color:#7c3aed}
.cf-actor-ges{background:rgba(217,70,239,0.12);color:#c026d3}
.cf-subtitle{font-size:0.82rem;color:var(--ifm-color-emphasis-700);margin-top:4px;margin-left:38px}

.cf-tracks{display:flex;flex-wrap:wrap;gap:8px;margin-top:12px;margin-left:38px}
.cf-track{display:inline-flex;align-items:center;gap:5px;padding:3px 10px;border-radius:6px;font-size:0.75rem;font-family:var(--ifm-font-family-monospace);border:1px solid}
.cf-track-lote{background:rgba(34,197,94,0.1);color:#16a34a;border-color:rgba(34,197,94,0.25)}
.cf-track-ativo{background:rgba(59,130,246,0.1);color:#2563eb;border-color:rgba(59,130,246,0.25)}
.cf-track-wh{background:rgba(245,158,11,0.1);color:#b45309;border-color:rgba(245,158,11,0.25)}
.cf-track-err{background:rgba(239,68,68,0.1);color:#dc2626;border-color:rgba(239,68,68,0.25)}
.cf-track-label{font-family:var(--ifm-font-family-base);font-weight:700;font-size:0.7rem;text-transform:uppercase;letter-spacing:0.03em}
.cf-new{font-weight:700}
.cf-unchanged{opacity:0.5}

.cf-details{max-height:0;overflow:hidden;opacity:0;transition:max-height 0.35s ease,opacity 0.25s ease,margin 0.3s ease;margin-left:38px}
.cf-card:hover .cf-details{max-height:300px;opacity:1;margin-top:14px;padding-top:12px;border-top:1px solid var(--ifm-color-emphasis-200)}

.cf-endpoint{font-family:var(--ifm-font-family-monospace);font-size:0.82rem;padding:8px 12px;border-radius:6px;background:var(--ifm-color-emphasis-100);margin-bottom:8px;display:flex;align-items:center;gap:8px;flex-wrap:wrap}
.cf-method{font-weight:800;padding:2px 6px;border-radius:4px;font-size:0.72rem}
.cf-method-post{background:#f97316;color:#fff}
.cf-method-put{background:#3b82f6;color:#fff}
.cf-method-get{background:#22c55e;color:#fff}
.cf-desc{font-size:0.82rem;color:var(--ifm-color-emphasis-700);margin-bottom:8px}
.cf-link{font-size:0.82rem;font-weight:600;color:var(--ifm-color-primary);text-decoration:none}
.cf-link:hover{text-decoration:underline}

.cf-branch{margin-top:12px;margin-left:38px;display:flex;gap:12px;flex-wrap:wrap}
.cf-branch-path{flex:1;min-width:200px;border-radius:8px;padding:10px 14px;border:1.5px dashed}
.cf-branch-ok{border-color:rgba(34,197,94,0.4);background:rgba(34,197,94,0.05)}
.cf-branch-err{border-color:rgba(239,68,68,0.4);background:rgba(239,68,68,0.05)}
.cf-branch-label{font-size:0.78rem;font-weight:700;margin-bottom:4px}
.cf-branch-label-ok{color:#16a34a}
.cf-branch-label-err{color:#dc2626}

html[data-theme='dark'] .cf-track-lote{background:rgba(34,197,94,0.15);color:#4ade80;border-color:rgba(34,197,94,0.3)}
html[data-theme='dark'] .cf-track-ativo{background:rgba(59,130,246,0.15);color:#60a5fa;border-color:rgba(59,130,246,0.3)}
html[data-theme='dark'] .cf-track-wh{background:rgba(245,158,11,0.15);color:#fbbf24;border-color:rgba(245,158,11,0.3)}
html[data-theme='dark'] .cf-track-err{background:rgba(239,68,68,0.15);color:#f87171;border-color:rgba(239,68,68,0.3)}
html[data-theme='dark'] .cf-branch-ok{background:rgba(34,197,94,0.08)}
html[data-theme='dark'] .cf-branch-err{background:rgba(239,68,68,0.08)}
html[data-theme='dark'] .cf-actor-int{background:rgba(59,130,246,0.2);color:#60a5fa}
html[data-theme='dark'] .cf-actor-qi{background:rgba(139,92,246,0.2);color:#a78bfa}
html[data-theme='dark'] .cf-actor-ges{background:rgba(217,70,239,0.2);color:#e879f9}
`}

## Legenda

Agente Integrador
QI Tech (automático)
Status do Lote
Status da Liquidação
Webhook

## Fluxograma

1
Criação do lote de pagamento
Agente Integrador
Cria um lote com identificador único ( external_id ) por fundo, contendo conta de crédito opcional e demais metadados.
Lote: pending_settlements_insertion
POST /settlement/fund_class/{fund_class_key}/payment_batch
O lote fica pronto para receber liquidações.
Ver documentação completa →

2
Inserção das liquidações
Agente Integrador
Insere cada liquidação (parcela, amortização, liquidação total, etc.) no lote. Repita para todas as operações desejadas.
Lote: pending_settlements_insertion
Liquidação: validated
POST /settlement/fund_class/{fund_class_key}/payment_batch/{external_id}/settlement
Cada liquidação recebe status validated após inserção bem-sucedida. Não há webhook neste momento; os webhooks são enviados após o encerramento e o processamento.
Ver documentação completa →

3
Remoção de liquidação (opcional)
Agente Integrador
Antes de encerrar o lote, você pode descartar uma liquidação inserida por engano. Somente liquidações em status validated podem ser removidas.
Lote: pending_settlements_insertion
Liquidação: validated
Removeu uma liquidação
discarded
A liquidação deixa de entrar no processamento.
Não aplicável
Pule este passo se não precisar remover nenhuma liquidação.
PUT /settlement/fund_class/{fund_class_key}/payment_batch/{external_id}/settlement/{settlement_external_id}
Corpo: {"status": "discarded"} . Após o encerramento do lote não é possível remover liquidações individuais.
Ver documentação completa →

4
Encerramento do lote
Agente Integrador
Sinaliza que todas as liquidações foram inseridas (e ajustadas) e que o processamento pode iniciar — ou descarta o lote inteiro.
Lote: pending_payment / discarded
Liquidação: validated (ou discarded)
Processar lote
pending_payment
É necessário ter ao menos uma liquidação no lote.
Descartar lote
discarded
Nenhuma liquidação será processada. Fluxo encerrado.
PUT /settlement/fund_class/{fund_class_key}/payment_batch/{external_id}
Envie {"batch_status": "pending_payment"} para encerrar e processar, ou {"batch_status": "discarded"} para descartar o lote.
Ver documentação completa →

5
Pagamento do lote
QI Tech
A QI Tech confirma o pagamento do lote. Em seguida as liquidações individuais são processadas e os webhooks de liquidação são disparados.
Lote: paid
Webhook: payment_batch_status_change
Webhook settlement.payment_batch_status_change com status paid . Opcionalmente, use a listagem de lotes para acompanhar o lote.
GET /settlement/fund_class/{fund_class_key}/payment_batches
Consulta opcional para acompanhar o lote por status ou data de referência.
Webhooks do lote →

6
Conclusão das liquidações
QI Tech
Cada liquidação processada com sucesso é conciliada na carteira do fundo. Este é o status final de sucesso por liquidação.
Liquidação: settled
Webhook: settlement_status_change
Webhook settlement.settlement_status_change com settlement_status settled para cada liquidação concluída (após o pagamento do lote).
Ver documentação de webhooks de liquidação →

---

## Resumo de webhooks

A tabela abaixo consolida todos os webhooks da API de liquidação:

| # | Tipo do webhook | Campo de status | Valor | Momento no fluxo | Ação esperada |
|---|---|---|---|---|---|
| 1 | `settlement.payment_batch_status_change` | `status` | `paid` | Após confirmação do pagamento do lote (passo 5) | A partir deste evento, as liquidações são processadas e os webhooks por liquidação passam a ser enviados. |
| 2 | `settlement.settlement_status_change` | `settlement_status` | `settled` | Por liquidação, após processamento bem-sucedido (passo 6) | Liquidação concluída e conciliada na carteira. |
| 3 | `settlement.settlement_status_change` | `settlement_status` | `discarded` | Por liquidação, quando descartada por remoção manual, descarte interno ou rejeição permanente da carteira | Liquidação não será processada. Nenhuma movimentação financeira é gerada. |
| 4 | `settlement.payment_batch_status_change` | `status` | `completed` | Após todas as liquidações do lote atingirem status final (`settled` ou `discarded`) | O ciclo do lote está encerrado. Todas as liquidações foram processadas. |
| 5 | `settlement.payment_batch_status_change` | `status` | `discarded` | Quando o lote é descartado (por solicitação do parceiro, descarte automático ou falha no cancelamento em conta caixa) | Nenhuma liquidação do lote será processada. |

:::info Payload do webhook de liquidação
O payload do webhook `settlement_status_change` varia conforme os dados enviados na criação da liquidação:

- **Identificação do ativo:** apenas um dos campos `contract_number` ou `asset_external_id` estará presente, conforme o método de identificação usado na criação. Nunca os dois simultaneamente.
- **Campos de parcela** (`installment_number`, `installment_maturity_date`, `installment_external_id`): presentes somente para tipos de liquidação por parcela — `installment_settlement`, `installment_amortization`, `installment_fine_payment` e `gloss`. Ausentes em tipos de ativo total (`asset_settlement`, `asset_amortization`, `fine_payment`).

Para a estrutura completa dos payloads, consulte [Webhooks do lote de pagamento](/documentation/iaas/liquidacao_ativos/lote_pagamento/webhook) e [Webhooks de liquidação](/documentation/iaas/liquidacao_ativos/ativos/webhook).
:::

---

# Liquidação de Ativos

URL: /documentation/iaas/liquidacao_ativos/inicio

Esta seção documenta as APIs que viabilizam o processo de Liquidação de Ativos para Fundos de Investimento administrados pela QI CTVM. Por meio dessas APIs, é possível registrar pagamentos de parcelas, amortizações, recompras e demais eventos de liquidação dos ativos que compõem a carteira do fundo.

:::tip Contexto
A liquidação de ativos descrita nesta seção aplica-se exclusivamente a direitos creditórios (CCBs, duplicatas, contratos, etc.) já encarteirados no fundo. Letras do Tesouro, Debêntures e outros ativos de renda fixa não se aplicam a esse fluxo.
:::

:::info Pré-requisitos
- Para ter acesso a esses serviços, entre em contato com [integracao.dtvm@qitech.com.br](mailto:integracao.dtvm@qitech.com.br) para liberação dos ambientes de Homologação (Sandbox) e Produção.
- Você precisará da `fund_class_key` (chave do fundo), que compõe a URL base de todos os endpoints desta API:

```
/settlement/fund_class/{fund_class_key}
```
:::

## Como enviar as baixas

| Caminho | Como funciona | Onde |
|---|---|---|
| **Pela API, liquidação a liquidação** | Criação do lote de pagamento, uma requisição por liquidação e encerramento do lote. É o fluxo detalhado nesta seção | API de integração |
| **Por arquivo** | Um único arquivo com todas as liquidações: **CNAB 444** ou **CSV** | Portal do gestor/consultor |

:::tip Baixa por arquivo
Se você já recebe o retorno CNAB do banco cobrador, pode enviá-lo direto. Veja [Baixa por Arquivo](/documentation/iaas/liquidacao_ativos/arquivo/inicio) e o [Layout CNAB 444 — Baixa](/documentation/iaas/liquidacao_ativos/arquivo/cnab444_baixa).
:::

## Fluxo de liquidação

O diagrama abaixo mostra o caminho principal, as bifurcações e o status resultante de cada etapa. Passe o mouse em um nó para ver o endpoint e clique para abrir a documentação.

<FlowDiagram
  columns={3}
  nodes={[
    { id: 'criacao', row: 1, col: 2, actor: 'you', num: 1,
      title: 'Criação do Lote de Pagamento',
      status: 'pending_settlements_insertion',
      desc: 'Contêiner de todas as liquidações que serão processadas em conjunto, identificado por um external_id único.',
      endpoint: { method: 'POST', path: '/settlement/fund_class/{fund_class_key}/payment_batch' },
      href: '/documentation/iaas/liquidacao_ativos/lote_pagamento/criacao' },

    { id: 'insercao', row: 2, col: 2, actor: 'you', num: 2,
      title: 'Inserção das Liquidações',
      status: 'liquidação: validated',
      desc: 'Uma requisição por liquidação, informando tipo de ativo, valor, tipo de liquidação e identificadores.',
      endpoint: { method: 'POST', path: '.../payment_batch/{external_id}/settlement' },
      href: '/documentation/iaas/liquidacao_ativos/ativos' },

    { id: 'remocao', row: 2, col: 3, actor: 'you', tag: 'Opcional',
      title: 'Remoção de uma liquidação',
      status: 'liquidação: discarded',
      desc: 'Descarta uma liquidação inserida por engano. Só é possível enquanto o lote não foi encerrado.',
      endpoint: { method: 'PUT', path: '.../settlement/{settlement_external_id}' },
      href: '/documentation/iaas/liquidacao_ativos/ativos/remocao_liquidacoes' },

    { id: 'encerramento', row: 3, col: 2, actor: 'you', num: 3,
      title: 'Encerramento do Lote',
      desc: 'Define o batch_status. É necessário ter ao menos uma liquidação inserida.',
      endpoint: { method: 'PUT', path: '.../payment_batch/{external_id}' },
      href: '/documentation/iaas/liquidacao_ativos/lote_pagamento/fechamento' },

    { id: 'descartado', row: 4, col: 1, actor: 'you', tone: 'end',
      title: 'Lote descartado',
      status: 'discarded',
      desc: 'Nenhuma liquidação é processada e nenhuma movimentação financeira é gerada. Fluxo encerrado.' },

    { id: 'pago', row: 4, col: 2, actor: 'qitech',
      title: 'Pagamento do lote confirmado',
      status: 'paid',
      desc: 'A QI Tech confirma o pagamento. A partir deste evento as liquidações individuais passam a ser processadas.',
      href: '/documentation/iaas/liquidacao_ativos/lote_pagamento/webhook' },

    { id: 'processa', row: 5, col: 2, actor: 'qitech',
      title: 'Processamento de cada liquidação',
      status: 'liquidação: settled',
      desc: 'Cada liquidação é conciliada na carteira do fundo e notificada individualmente por webhook.',
      href: '/documentation/iaas/liquidacao_ativos/ativos/webhook' },

    { id: 'conciliada', row: 6, col: 2, actor: 'qitech', tone: 'ok',
      title: 'Carteira do fundo conciliada',
      status: 'completed',
      desc: 'Todas as liquidações atingiram status final e o ciclo do lote está encerrado.',
      href: '/documentation/iaas/liquidacao_ativos/lote_pagamento/webhook' },
  ]}
  edges={[
    { from: 'criacao', to: 'insercao' },
    { from: 'insercao', to: 'remocao', dashed: true },
    { from: 'insercao', to: 'encerramento' },
    { from: 'encerramento', to: 'descartado', label: 'discarded', tone: 'end' },
    { from: 'encerramento', to: 'pago', label: 'pending_payment', tone: 'ok' },
    { from: 'pago', to: 'processa', label: 'webhook' },
    { from: 'processa', to: 'conciliada', label: 'webhook' },
  ]}
/>

:::tip Fluxo completo
Para todas as transições de status, os payloads dos webhooks e os caminhos de exceção, consulte o [Fluxo de liquidação de ativos](/documentation/iaas/liquidacao_ativos/fluxo_liquidacao).
:::

## Passo a passo

### 1. Criação do Lote de Pagamento

Crie um lote de pagamento informando um identificador único (`external_id`). O lote será o contêiner para todas as liquidações que serão processadas em conjunto.

**[Acessar documentação da criação do lote](/documentation/iaas/liquidacao_ativos/lote_pagamento/criacao)**

### 2. Inserção das Liquidações

Adicione as liquidações ao lote criado. Cada liquidação deve ser inserida individualmente, informando o tipo de ativo, o valor, o tipo de liquidação e os identificadores necessários.

**[Acessar documentação da inserção de liquidações](/documentation/iaas/liquidacao_ativos/ativos)**

Enquanto o lote não é encerrado, uma liquidação inserida por engano pode ser removida.

**[Acessar documentação da remoção de liquidações](/documentation/iaas/liquidacao_ativos/ativos/remocao_liquidacoes)**

### 3. Encerramento do Lote

Após inserir todas as liquidações, encerre o lote para que o processamento interno seja iniciado. A conciliação de caixa e a atualização do portfólio de ativos serão realizadas automaticamente. No mesmo endpoint é possível, alternativamente, descartar o lote inteiro — nesse caso nenhuma liquidação é processada.

**[Acessar documentação do encerramento](/documentation/iaas/liquidacao_ativos/lote_pagamento/fechamento)**

### 4. Acompanhamento via Webhooks

Acompanhe o progresso através dos webhooks:
- **[Webhooks do lote de pagamento](/documentation/iaas/liquidacao_ativos/lote_pagamento/webhook)** — notificações sobre o status do lote.
- **[Webhooks das liquidações](/documentation/iaas/liquidacao_ativos/ativos/webhook)** — notificações sobre o status individual de cada liquidação.

:::info Processamento automático
O procedimento de conciliação de caixa e a atualização do portfólio de ativos é feito de forma automática pela API após o encerramento do lote.
:::

---

# Criação do Lote de Pagamento

URL: /documentation/iaas/liquidacao_ativos/lote_pagamento/criacao

Este é o **primeiro passo** do fluxo de liquidação de ativos. A criação do lote de pagamento reserva um agrupamento onde as liquidações que serão processadas serão inseridas nas etapas seguintes.

:::info Pré-requisitos
Antes de criar um lote, você precisa ter em mãos a `fund_class_key` — chave única do fundo no qual os ativos serão liquidados. Essa chave compõe o endpoint utilizado em toda esta API:

```
/settlement/fund_class/{fund_class_key}
```

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

:::caution Atenção
Cada lote deve possuir um `external_id` **único** por fundo. O sistema não permitirá a criação de dois lotes com o mesmo identificador.
:::

## Request

ENDPOINT /settlement/fund_class/{fund_class_key}/payment_batch
MÉTODO POST

```json title="Request Body"
{
    "external_id": "41d6ff41-1dac-4df7-9e50-d15210ec57f3",
    "description": "PAGAMENTOS - ABC - 2025-01-01",
    "account": {
        "account_number": "123456",
        "account_digit": "0",
        "account_branch": "0001",
        "financial_institution_code": "329"
    }
}
```

### Atributos do body

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `external_id` | string | obrigatório | Chave única de identificação deste lote no sistema do parceiro integrador. Máximo de 50 caracteres. |
| `description` | string | opcional | Descrição do lote de liquidação. Máximo de 255 caracteres. |
| `account` | object | opcional | Dados da conta onde a liquidação será creditada. Quando não informado, a liquidação será gerada na conta principal do fundo. Veja [Atributos de `account`](#atributos-de-account). |
| `account_key` | string | opcional | Chave da conta onde a liquidação será creditada (UUID, 36 caracteres). Alternativa ao campo `account`. |
| `reference_date` | string | opcional | Data de referência da liquidação no formato `YYYY-MM-DD`. |
| `end_to_end_id` | string | opcional | Identificador end-to-end do PIX da contraparte financeira da liquidação. Máximo de 32 caracteres. |
| `source_document_number` | string | opcional | CPF ou CNPJ da contraparte financeira da liquidação, com pontuação (ex: `12.345.678/0001-90` ou `123.456.789-00`). |

:::caution Atenção
Os campos `account` e `account_key` não devem ser passados simultaneamente. Caso nenhum dos dois seja informado, a liquidação será gerada na conta principal do fundo. As informações da conta devem ser referentes a uma conta pertencente ao fundo.
:::

#### Atributos de `account`

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `account_number` | string | obrigatório | Número da conta. Máximo de 20 caracteres. |
| `account_digit` | string | obrigatório | Dígito da conta. 1 caractere. |
| `account_branch` | string | obrigatório | Agência da conta. Máximo de 4 caracteres. |
| `financial_institution_code` | string | obrigatório | Código da instituição financeira. Máximo de 20 caracteres. |

## Response

STATUS 201

```json title="Response Body"
{
    "external_id": "41d6ff41-1dac-4df7-9e50-d15210ec57f3",
    "description": "PAGAMENTOS - ABC - 2025-01-01",
    "fund_class": {
        "name": "FUNDO DE INVESTIMENTO EM DIREITOS CREDITÓRIOS",
        "manager": {
            "name": "EXEMPLO CAPITAL",
            "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"
    },
    "payment_batch_key": "63f0dbec-e9c4-4943-929e-1d47b9edbb0b",
    "status": "pending_settlements_insertion",
    "reference_date": "2025-01-01",
    "account_key": "5e621ba2-b4ac-4ddd-9893-82d220e1577e"
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `external_id` | string | A mesma chave externa fornecida na requisição. |
| `description` | string | Descrição do lote. |
| `fund_class` | object | Dados do fundo associado ao lote. Veja [Atributos de `fund_class`](#atributos-de-fund_class). |
| `payment_batch_key` | string | Identificador único do lote gerado pela QI Tech (UUID). |
| `status` | string | Status inicial do lote. Sempre retorna `pending_settlements_insertion`, indicando que o lote está pronto para receber liquidações. |
| `reference_date` | string | Data de referência da liquidação no formato `YYYY-MM-DD`. |
| `account_key` | string | Chave da conta associada ao lote (UUID). |

#### Atributos de `fund_class`

| Campo | Tipo | Descrição |
|---|---|---|
| `name` | string | Nome do fundo. |
| `manager` | object | Dados do gestor do fundo. Veja [Atributos de `manager`](#atributos-de-manager). |
| `fund_class_key` | string | Chave única do fundo (UUID). |
| `document_number` | string | CNPJ do fundo. |

#### Atributos de `manager`

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

## Possíveis erros

STATUS 404

**Fundo não encontrado**

A `fund_class_key` informada na URL não corresponde a nenhum fundo cadastrado. Verifique se a chave está correta.

```json
{
  "title": "Fund Class not Found",
  "description": "Fund Class with key {fund_class_key} was not found.",
  "translation": "A Classe de Fundo com chave {fund_class_key} nao foi encontrado.",
  "code": "SET000005"
}
```

STATUS 409

**External ID duplicado**

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

```json
{
  "title": "Payment batch external id already exists",
  "description": "The Payment Batch with external id {payment_batch_external_id} already exists",
  "translation": "O Lote de Pagamento com identificador externo {payment_batch_external_id} ja existe",
  "code": "SET000009"
}
```

STATUS 400

**Data contábil divergente**

O lote está sendo criado em uma data diferente da data contábil vigente do fundo. Verifique a data contábil do fundo e tente novamente.

```json
{
  "title": "Bad Request",
  "description": "Payment batch is being created in {accounting_date}, while fund is in {fund_class_accounting_date}",
  "translation": "Payment batch esta sendo criado em {accounting_date}, fundo esta em {fund_class_accounting_date}",
  "code": "SET000044"
}
```

STATUS 404

**Conta não encontrada**

A `account_key` informada não corresponde a nenhuma conta cadastrada. Verifique se a chave está correta e se a conta pertence ao fundo.

```json
{
  "title": "Account not found",
  "description": "The account with key ({account_key}) was not found.",
  "translation": "A conta com chave({account_key}) não foi encontrada.",
  "code": "SET000009"
}
```

## Próximos passos

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

1. **[Inserção das liquidações](/documentation/iaas/liquidacao_ativos/ativos)** — adicione as liquidações (pagamentos de parcelas, amortizações, etc.) ao lote.
2. **[Encerramento do lote](/documentation/iaas/liquidacao_ativos/lote_pagamento/fechamento)** — sinalize que todas as liquidações foram inseridas para que o processamento seja iniciado.

---

# Encerrar Inserção no Lote de Pagamento

URL: /documentation/iaas/liquidacao_ativos/lote_pagamento/fechamento

Após inserir todas as liquidações desejadas no lote, utilize este endpoint para sinalizar que a inserção foi concluída e o processamento pode ser iniciado. Também é possível descartar o lote por completo.

:::tip Onde estou no fluxo?
Este é o **3º passo** do fluxo de liquidação. Antes deste passo, você deve ter:
1. [Criado o lote de pagamento](/documentation/iaas/liquidacao_ativos/lote_pagamento/criacao)
2. [Inserido as liquidações](/documentation/iaas/liquidacao_ativos/ativos)
:::

## Request

ENDPOINT /settlement/fund_class/{fund_class_key}/payment_batch/{external_id}
MÉTODO PUT

### Path params

| Parâmetro | Tipo | Descrição |
|---|---|---|
| `external_id` | string | O `external_id` informado na criação do lote. |

```json title="Request Body"
{
    "batch_status": "pending_payment"
}
```

### Atributos do body

| Campo | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `batch_status` | string | obrigatório | Status para o qual o lote será atualizado. Veja [enumeradores](#enumeradores-de-batch_status) abaixo. |

#### Enumeradores de `batch_status`

| Valor | Descrição |
|---|---|
| `pending_payment` | Encerra a inserção e inicia o processamento do lote. |
| `discarded` | Descarta o lote inteiro. Nenhuma liquidação será processada. |

## Response

STATUS 200

```json title="Response Body"
{
    "external_id": "41d6ff41-1dac-4df7-9e50-d15210ec57f3",
    "status": "pending_payment"
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `external_id` | string | Chave externa do lote fornecida pelo parceiro. |
| `status` | string | Novo status do lote. |

## Possíveis erros

STATUS 404

**Lote não encontrado**

O `external_id` informado na URL não corresponde a nenhum lote cadastrado para este fundo. Verifique se o identificador está correto.

```json
{
  "title": "Payment batch not found",
  "description": "The Payment Batch with external_id {payment_batch_external_id} was not found",
  "translation": "O Lote de Pagamento com identificador externo {payment_batch_external_id} não foi encontrado",
  "code": "SET000010"
}
```

STATUS 400

**Status inválido**

O valor informado no campo `batch_status` não é válido. Utilize apenas `pending_payment` ou `discarded`.

```json
{
  "title": "Invalid status",
  "description": "The status given: {status} is not suported.",
  "translation": "O status: {status} não possui suporte.",
  "code": "SET000026"
}
```

STATUS 400

**Lote sem liquidações**

Você tentou encerrar o lote, mas ele ainda não possui nenhuma liquidação inserida. É necessário [inserir pelo menos uma liquidação](/documentation/iaas/liquidacao_ativos/ativos) antes de encerrar o lote.

```json
{
  "title": "Payment Batch with no settlement",
  "description": "Payment batch of external_id: {payment_batch_external_id} have no settlements to be settled",
  "translation": "O lote de pagamento com identificador: {payment_batch_external_id} não possui liquidações",
  "code": "SET000017"
}
```

## Próximos passos

Após encerrar o lote, o processamento é iniciado automaticamente. Acompanhe o resultado através dos webhooks:

1. **[Webhooks do lote de pagamento](/documentation/iaas/liquidacao_ativos/lote_pagamento/webhook)** — notificação quando o lote for pago.
2. **[Webhooks das liquidações](/documentation/iaas/liquidacao_ativos/ativos/webhook)** — notificação individual de cada liquidação processada.

---

# Listagem de Lotes de Pagamento

URL: /documentation/iaas/liquidacao_ativos/lote_pagamento/listagem

Endpoint de consulta paginada que retorna os lotes de pagamento de uma determinada classe de fundo. Utilize os filtros disponíveis para buscar lotes por status ou data de referência.

## Request

ENDPOINT /settlement/fund_class/{fund_class_key}/payment_batches
MÉTODO GET

### Query params

| Parâmetro | Tipo | Obrigatoriedade | Descrição |
|---|---|---|---|
| `status` | string | opcional | Filtra por um status específico do lote. Consulte os [enumeradores de status](#enumeradores-de-status-do-lote). |
| `reference_date` | string | opcional | Filtra por data de referência no formato `YYYY-MM-DD`. |
| `page` | integer | opcional | Número da página (começa em 0). Padrão: `0`. |
| `limit` | integer | opcional | Quantidade de registros por página. Padrão: `10`. Máximo: `50`. |

```python title="Exemplo de chamada"
GET /settlement/fund_class/{fund_class_key}/payment_batches?status=completed&reference_date=2025-01-01&page=0&limit=10
```

## Response

STATUS 200

```json title="Response Body"
{
    "data": [
        {
            "description": "LOTE DE LIQUIDAÇÃO 08/08",
            "fund_class": {
                "name": "FUNDO DE INVESTIMENTO EM DIREITOS CREDITÓRIOS",
                "manager": {
                    "name": "EXEMPLO CAPITAL",
                    "manager_key": "a7498c6c-1893-42ec-a8f3-bc6ad0c6b52c",
                    "document_number": "45.585.471/0001-47"
                },
                "fund_class_key": "a3ecf74b-d280-4d3c-aefd-cb223dbf0451",
                "document_number": "60.910.091/0001-24"
            },
            "payment_batch_key": "50859e88-544c-4c79-a7aa-d373d90aa571",
            "status": "completed",
            "external_id": "5910209c-9cb5-4569-9069-f2dbc8060434",
            "reference_date": "2025-08-08",
            "account_key": "5e621ba2-b4ac-4ddd-9893-82d220e1577e",
            "total_value": 143.18
        }
    ],
    "limit": 10,
    "page": 0,
    "is_last_page": false
}
```

### Atributos da resposta

| Campo | Tipo | Descrição |
|---|---|---|
| `data` | array | Lista de objetos de lote de pagamento. Veja tabela abaixo. |
| `page` | integer | Número da página atual. |
| `limit` | integer | Quantidade de registros por página. |
| `is_last_page` | boolean | Indica se esta é a última página de resultados. |

#### Atributos de cada lote (objetos dentro de `data`)

| Campo | Tipo | Descrição |
|---|---|---|
| `description` | string | Descrição do lote. |
| `fund_class` | object | Dados do fundo associado ao lote. Consulte os [atributos de `fund_class`](/documentation/iaas/liquidacao_ativos/lote_pagamento/criacao#atributos-de-fund_class) na página de Criação. |
| `payment_batch_key` | string | Identificador único do lote (UUID). |
| `status` | string | Status atual do lote. Consulte os [enumeradores de status](#enumeradores-de-status-do-lote) abaixo. |
| `external_id` | string | Chave externa fornecida pelo parceiro. |
| `reference_date` | string | Data de referência no formato `YYYY-MM-DD`. |
| `account_key` | string | Chave da conta associada ao lote (UUID). |
| `total_value` | number | Valor total das liquidações do lote em reais. Pode não estar presente caso o lote ainda não tenha sido processado. |

## Enumeradores de status do lote

| Status | Descrição |
|---|---|
| `pending_settlements_insertion` | Lote criado, aguardando inserção de liquidações. |
| `pending_payment` | Lote encerrado, aguardando processamento do pagamento. |
| `paid` | Pagamento do lote realizado. |
| `completed` | Processamento do lote finalizado com sucesso. |
| `discarded` | Lote descartado. |

---

# Webhooks do Lote de Pagamento

URL: /documentation/iaas/liquidacao_ativos/lote_pagamento/webhook

Ao longo do fluxo de liquidação, o sistema envia webhooks para notificar o parceiro integrador sobre mudanças de status do lote de pagamento. Todos os webhooks possuem o tipo `settlement.payment_batch_status_change` e identificam o lote pelo `external_id` fornecido na criação.

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

## Fluxo de status do lote

O lote passa pelos status abaixo até o encerramento. Três deles geram webhook: `paid`, `completed` e `discarded`. Os dois primeiros — `pending_settlements_insertion` e `pending_payment` — são resultado das suas próprias chamadas de [criação](/documentation/iaas/liquidacao_ativos/lote_pagamento/criacao) e [encerramento](/documentation/iaas/liquidacao_ativos/lote_pagamento/fechamento) do lote e **não** disparam notificação.

![Fluxo de status do lote de pagamento, destacando os três status que geram webhook](/img/diagrams/iaas-liquidacao-ativos-lote-pagamento-webhook.svg)

_Como ler o diagrama: **contorno tracejado** = status sem webhook · **azul** = webhook de andamento · **verde** = encerramento com sucesso · **vermelho** = encerramento sem processamento._

## Estrutura do webhook

Todos os webhooks do lote de pagamento seguem a mesma estrutura:

| Campo | Tipo | Descrição |
|---|---|---|
| `webhook_type` | string | Sempre `settlement.payment_batch_status_change`. |
| `webhook_datetime` | string | Data e hora do evento no formato ISO 8601. |
| `data` | object | Dados do evento. Veja tabela abaixo. |

#### Atributos de `data`

| Campo | Tipo | Descrição |
|---|---|---|
| `external_id` | string | Identificador do lote. Veja [Como o `external_id` é formado](#como-o-external_id-é-formado). |
| `status` | string | Novo status do lote. |
| `fund_class_document_number` | string | CNPJ do fundo associado ao lote. |
| `fund_class_key` | string | Chave do fundo na QI Tech (UUID). |
| `payment_batch_key` | string | Identificador único do lote gerado pela QI Tech (UUID). |
| `reference_date` | string | Data de referência do lote, no formato `AAAA-MM-DD`. |
| `total_value` | number | Valor total do lote em reais. Presente depois que o total é apurado, no encerramento do lote — ou seja, nos webhooks de `paid` e `completed`. |
| `description` | string | Descrição do lote. Presente quando o lote possui descrição. |

```json title="Estrutura padrão do webhook"
{
    "data": {
        "external_id": "57efbd9f-0917-4c79-9a43-bc8f1039fc78",
        "status": "STATUS",
        "fund_class_document_number": "60.910.091/0001-24",
        "fund_class_key": "8e2d1c4b-3a5f-4e6d-9b7c-1a2b3c4d5e6f",
        "payment_batch_key": "c1f0a9d8-7b6e-4c5d-8a9b-0f1e2d3c4b5a",
        "reference_date": "2024-04-23",
        "total_value": 4520.75,
        "description": "PAGAMENTOS - ABC - 2024-04-23"
    },
    "webhook_type": "settlement.payment_batch_status_change",
    "webhook_datetime": "2024-04-23T15:08:30Z"
}
```

---

## Como o `external_id` é formado

O `external_id` é a chave de correlação entre o lote na QI CTVM e o seu próprio controle. A origem do valor depende de como o lote foi criado:

| Origem do lote | Valor do `external_id` |
|---|---|
| [Criação via API](/documentation/iaas/liquidacao_ativos/lote_pagamento/criacao) | Exatamente o `external_id` que você informou no corpo da requisição. |
| Arquivo de liquidação enviado via SFTP | O nome do arquivo **sem a extensão**. |

:::info Lotes criados a partir de um arquivo de liquidação
O webhook **não traz um campo com o nome do arquivo**. Para correlacionar o evento ao arquivo que você enviou, compare o `external_id` com o nome do arquivo sem a extensão:

| Arquivo enviado | `external_id` do lote |
|---|---|
| `liquidacoes_20260811_001.REM` | `liquidacoes_20260811_001` |
| `CNAB_BAIXAS_liquidacoes_20260811_001.REM` | `liquidacoes_20260811_001` |

Como mostra a segunda linha, o prefixo `CNAB_BAIXAS_`, quando presente, também é removido.

O arquivo de retorno com as inconsistências encontradas no processamento, quando gerado, segue a mesma convenção — `retorno_liquidacoes_20260811_001.csv`.
:::

---

## Eventos por status

### Lote Pago

STATUS paid

Enviado quando o pagamento do lote é confirmado pela QI Tech. A partir desse momento, as liquidações individuais são processadas em sequência e os respectivos [webhooks de liquidação](/documentation/iaas/liquidacao_ativos/ativos/webhook) são enviados conforme cada uma for concluída.

```json title="Webhook Body"
{
    "data": {
        "external_id": "57efbd9f-0917-4c79-9a43-bc8f1039fc78",
        "status": "paid",
        "fund_class_document_number": "60.910.091/0001-24",
        "fund_class_key": "8e2d1c4b-3a5f-4e6d-9b7c-1a2b3c4d5e6f",
        "payment_batch_key": "c1f0a9d8-7b6e-4c5d-8a9b-0f1e2d3c4b5a",
        "reference_date": "2024-04-23",
        "total_value": 4520.75,
        "description": "PAGAMENTOS - ABC - 2024-04-23"
    },
    "webhook_type": "settlement.payment_batch_status_change",
    "webhook_datetime": "2024-04-23T15:08:30Z"
}
```

---

### Lote Concluído

STATUS completed

Enviado quando todas as liquidações do lote atingiram um status final (`settled` ou `discarded`). Este é o status terminal do lote após a conclusão bem-sucedida do ciclo de liquidação. Ao receber este evento, o parceiro integrador pode considerar o lote integralmente processado.

Para identificar a que lote o evento se refere, use o `external_id` — veja [Como o `external_id` é formado](#como-o-external_id-é-formado).

```json title="Webhook Body"
{
    "data": {
        "external_id": "57efbd9f-0917-4c79-9a43-bc8f1039fc78",
        "status": "completed",
        "fund_class_document_number": "60.910.091/0001-24",
        "fund_class_key": "8e2d1c4b-3a5f-4e6d-9b7c-1a2b3c4d5e6f",
        "payment_batch_key": "c1f0a9d8-7b6e-4c5d-8a9b-0f1e2d3c4b5a",
        "reference_date": "2024-04-23",
        "total_value": 4520.75,
        "description": "PAGAMENTOS - ABC - 2024-04-23"
    },
    "webhook_type": "settlement.payment_batch_status_change",
    "webhook_datetime": "2024-04-23T15:08:30Z"
}
```

---

### Lote Descartado

STATUS discarded

Enviado quando o lote é descartado. Isso pode ocorrer por solicitação explícita do parceiro integrador no [encerramento do lote](/documentation/iaas/liquidacao_ativos/lote_pagamento/fechamento), por descarte automático de lotes em aberto pela QI Tech, ou após cancelamento junto à conta caixa. Nenhuma liquidação associada ao lote será processada após este status.

Quando o lote é descartado antes do encerramento, o valor total não chega a ser apurado e o campo `total_value` não vem no payload.

```json title="Webhook Body"
{
    "data": {
        "external_id": "57efbd9f-0917-4c79-9a43-bc8f1039fc78",
        "status": "discarded",
        "fund_class_document_number": "60.910.091/0001-24",
        "fund_class_key": "8e2d1c4b-3a5f-4e6d-9b7c-1a2b3c4d5e6f",
        "payment_batch_key": "c1f0a9d8-7b6e-4c5d-8a9b-0f1e2d3c4b5a",
        "reference_date": "2024-04-23",
        "description": "PAGAMENTOS - ABC - 2024-04-23"
    },
    "webhook_type": "settlement.payment_batch_status_change",
    "webhook_datetime": "2024-04-23T15:08:30Z"
}
```