# 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 12 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/) - Consulta de Liquidação (/documentation/iaas/liquidacao_ativos/ativos/recuperacao) - 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) - Consulta de Lote de Pagamento (/documentation/iaas/liquidacao_ativos/lote_pagamento/recuperacao) - 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 DTVM. 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`, `06`, `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 (`asset_settlement` / `installment_settlement`) | Sacado | | `14` | **Pagamento parcial** | Amortização (`asset_amortization` / `installment_amortization`) | Sacado | | `75` | **Baixa por depósito do cedente** | Liquidação integral (`asset_settlement` / `installment_settlement`) | Cedente | | `04` | **Abatimento** | Amortização pelo valor do abatimento (posições 206–218, maior que zero) | Cedente | | `06` | **Alteração de vencimento** | Prorrogação (`asset_extension`). Só duplicatas e demais direitos creditórios | Sacado | :::caution Só essas cinco Qualquer outro código de ocorrência recusa o arquivo com a mensagem *"This field only allows one of this values: ['04', '06', '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º de controle do participante** (038–062), o mesmo da cessão | 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º de controle do participante e pela data de vencimento | ## Checklist antes de enviar - [ ] Todas as linhas com exatamente 444 caracteres - [ ] Ocorrência `04`, `06`, `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-liquidacao) | | `installment_number` | obrigatória (coluna) | Número da parcela. Preencha para ativos com parcelas (CCB); deixe vazio para duplicatas; em contratos, use `installment_number` ou `installment_external_id` | | `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` | | `new_maturity_date` | condicional | Nova data de vencimento, no formato `YYYY-MM-DD`. Obrigatória em `asset_extension` e recusada nos demais tipos | | `installment_external_id` | opcional | Para contratos, alternativa a `installment_number` | :::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 | | `asset_extension` | Prorrogação do vencimento (só direitos creditórios; exige a coluna `external_id` e `new_maturity_date`) | ### Tipos de ativo aceitos `ccb` · `cce` · `structured_ccb` · `structured_cce` · `structured_nce` · `structured_cci` · `duplicata_mercantil` · `duplicata_servicos` · `discounted_contract` · `cte` · `commercial_paper` · `check` · `promissory_note` · `debt_acknowledgment` · `financing_contract` · `contract` **[📄 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 Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | ---------------------------------------------- | | Gestora | `manager-api` | Escrita | | Consultoria | `consultant-api` | Criar Lotes | | Cedente | `assignor-api` | Escrita | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: :::info Liquidação, recompra e repasse Liquidação e recompra usam este mesmo endpoint. O campo `collection_origin_type` indica quem pagou: - `borrower` — **liquidação** paga pelo sacado/devedor. - `assignor` — **recompra** paga pelo cedente. - `collection_agent` — pagamento repassado por um agente de cobrança. Exige `counter_party_document_number`. - `bankslip` — pagamento recebido por boleto. ::: :::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). O lote precisa estar em `pending_settlements_insertion`. ::: ## 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 no máximo duas casas decimais. Só pode ser `0` em `installment_settlement`, `asset_settlement`, `asset_refund` e `asset_extension`. | | `external_id` | string | obrigatório | Chave única desta liquidação dentro do lote, 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 | opcional | Quem pagou. Veja [enumeradores de `collection_origin_type`](#enumeradores-de-collection_origin_type). Quando omitido, vale o padrão da configuração de liquidação do fundo, se houver. | | `counter_party_document_number` | string | condicional | CPF ou CNPJ de quem pagou, com pontuação (14 a 18 caracteres). **Obrigatório** quando `collection_origin_type` é `collection_agent` e a configuração de liquidação do fundo não define um documento padrão. Com `borrower`, `bankslip` ou `assignor`, quando omitido, é preenchido com o documento do sacado ou do cedente do ativo. | | `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, 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 | condicional | Número da parcela. Veja [identificação da parcela](#identificacao-do-ativo-e-da-parcela). | | `installment_maturity_date` | string | condicional | Data de vencimento da parcela no formato `YYYY-MM-DD`. | | `installment_external_id` | string | condicional | Identificador externo da parcela. Máximo de 50 caracteres. | | `collection_date` | string | opcional | Data de pagamento no formato `YYYY-MM-DD`. Campo destinado ao controle do integrador. | | `remaining_face_value` | number | opcional | Saldo de valor de face que resta na parcela após o pagamento. Aceito somente em `installment_amortization` e quando a liquidação atinge um único ativo. | | `asset_reduction_value` | number | opcional | Valor a abater do ativo, quando diferente do valor pago. Aceito somente em `installment_amortization` e `installment_partial_refund`. Não pode ser maior que `total_value`. | | `new_maturity_date` | string | condicional | Nova data de vencimento, no formato `YYYY-MM-DD`. **Obrigatório** em `asset_extension` e recusado nos demais tipos. | | `reversed_settlement_external_id` | string | condicional | `external_id` da liquidação que está sendo estornada. **Obrigatório** em `installment_payment_reversal` e recusado nos demais tipos. | :::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**. ::: ### Identificação do ativo e da parcela - Informe **exatamente um** identificador do ativo: `contract_number`, `asset_external_id`, `asset_key`, `if_code` ou `participant_control_number`. Nenhum ou mais de um devolve erro. Duplicatas e demais direitos creditórios não aceitam `contract_number` nem `if_code`; CCBs e demais operações de crédito não aceitam `participant_control_number`. - Nos tipos de liquidação por parcela (`installment_*` e `gloss`), informe **exatamente um** identificador da parcela: `installment_number`, `installment_maturity_date` ou `installment_external_id`. Em CCBs e contratos, `installment_external_id` sozinho também identifica o ativo. #### 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 descontado | | `cte` | Conhecimento de Transporte Eletrônico | | `check` | Cheque | | `promissory_note` | Nota promissória | | `legal_fees` | Honorários | | `debt_acknowledgment` | Confissão de dívida | | `financing_contract` | Contrato de financiamento | | `contract` | Contrato | #### Enumeradores de `settlement_type` | Valor | Descrição | |---|---| | `asset_settlement` | Liquidação total do ativo. | | `asset_amortization` | Amortização do ativo. | | `fine_payment` | Pagamento de juros ou mora do ativo. | | `asset_refund` | Devolução integral do ativo. | | `asset_partial_refund` | Devolução parcial do ativo. | | `asset_gloss` | Glosa do ativo. | | `asset_extension` | Prorrogação do vencimento de duplicatas e demais direitos creditórios. Exige `new_maturity_date` e um único ativo. | | `installment_settlement` | Liquidação de parcela. | | `installment_amortization` | Amortização de parcela. | | `installment_fine_payment` | Pagamento de juros ou mora de parcela. | | `installment_refund` | Devolução integral de parcela. | | `installment_partial_refund` | Devolução parcial de parcela. | | `installment_payment_reversal` | Estorno do pagamento de uma parcela de CCB ou operação de crédito. Exige `reversed_settlement_external_id` e `installment_number`; `total_value` deve ser igual ao da liquidação estornada. | | `gloss` | Glosa de parcela. | | `rco_revenue` | Receita de RCO. | Contratos (`debt_acknowledgment`, `financing_contract`, `contract`) aceitam somente `asset_settlement`, `asset_amortization`, `installment_settlement` e `installment_amortization`. #### Enumeradores de `collection_origin_type` | Valor | Descrição | |---|---| | `borrower` | Liquidação — pagamento realizado pelo sacado/devedor. | | `assignor` | Recompra — pagamento realizado pelo cedente. | | `collection_agent` | Repasse de um agente de cobrança. Exige `counter_party_document_number` (ou documento padrão na configuração do fundo). | | `bankslip` | Pagamento recebido por boleto. | ## Response STATUS 201 A resposta ecoa os campos enviados no corpo e acrescenta os dados calculados pela QI Tech. ```json title="Response 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", "asset_external_id": "CCB-0001", "assignor_document_number": "33.444.555/0001-81", "borrower_document_number": "969.698.790-03", "status": "validated", "type": "installment_settlement", "settlement_key": "b2c3d4e5-f6a7-8901-abcd-ef1234567890", "total_number_of_units": 1, "settlement_result": 0.0, "next_execution_datetime": "2025-01-01 13:00:00.000000", "counter_party_document_number": "969.698.790-03", "assets": [ { "asset_key": "f34e9437-d025-41ab-bb53-6b94e10fd361", "number_of_units": 1, "present_value": 1250.00, "installment_face_value": 130.50 } ] } ``` ### Atributos da resposta Além dos campos enviados no corpo: | Campo | Tipo | Descrição | |---|---|---| | `status` | string | Status da liquidação após a inserção: `validated` ou `pending_validation`. Veja abaixo. | | `type` | string | Tipo de liquidação (mesmo valor de `settlement_type`). | | `settlement_key` | string | Identificador único da liquidação gerado pela QI Tech (UUID). | | `total_value` | number | Valor total do pagamento. Negativo em `gloss`, `asset_gloss` e `installment_payment_reversal`. | | `total_number_of_units` | integer | Quantidade total de unidades de ativo afetadas pela liquidação. | | `installment_number` | integer | Número da parcela localizada. Presente quando aplicável. | | `settlement_result` | number | Diferença entre o valor pago e o valor esperado do ativo ou parcela. Presente quando calculado. | | `contract_number`, `asset_external_id` | string | Identificadores do ativo localizado na carteira (CCBs e contratos). | | `assignor_document_number`, `borrower_document_number` | string | Documento do cedente e do sacado do ativo. | | `counter_party_document_number` | string | Documento de quem pagou. Presente quando informado ou preenchido automaticamente. | | `collection_origin_type` | string | Origem do pagamento. Presente quando informada ou definida pela configuração do fundo. | | `next_execution_datetime` | string | Controle do processamento da QI Tech. Pode ser ignorado. | | `denial_reason` | string | Motivo do descarte. Presente apenas em liquidações descartadas. | | `assets` | array | Ativos afetados pela liquidação. Veja [Atributos de `assets`](#atributos-de-assets). | **Status na resposta:** - `validated` — o valor pago está dentro da tolerância em relação ao valor esperado do ativo ou da parcela. A liquidação será processada quando o lote for pago. - `pending_validation` — o valor pago diverge do esperado além da tolerância e a liquidação aguarda revisão da QI Tech. Ao final da revisão ela passa para `validated` ou `discarded`, e você recebe o [webhook de liquidação](/documentation/iaas/liquidacao_ativos/ativos/webhook) correspondente. Dependendo da configuração de liquidação do fundo, a divergência pode, em vez disso, recusar a inserção com `SET000066`. #### 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. | | `total_purchase_value` | number | Valor de aquisição do ativo. Presente quando aplicável. | | `maturity_date` | string | Vencimento do ativo. Presente quando aplicável. | | `contract_number` | string | Número do contrato do ativo. Presente quando aplicável. | | `external_id` | string | Identificador externo do ativo. Presente quando aplicável. | ## Reenvio e duplicidade Em caso de erro, reenvie a requisição. Duplicidade (`SET000013`) significa que a liquidação já existe neste lote: consulte-a pela [consulta de liquidação](/documentation/iaas/liquidacao_ativos/ativos/recuperacao) em vez de recriar. Veja [Reenvio e duplicidade](/documentation/iaas/introducao/erros#reenvio-e-duplicidade). ## 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. Não há endpoint para remover uma liquidação individual. Se uma liquidação foi inserida por engano, descarte o lote no [encerramento](/documentation/iaas/liquidacao_ativos/lote_pagamento/fechamento) (`batch_status: discarded`) e crie um novo lote com as liquidações corretas. ## Erros | Status | Código | Quando acontece | |---|---|---| | 404 | `SET000010` | O lote informado na URL não existe neste fundo. | | 403 | `SET000028` | O fundo não pertence ao seu perfil. | | 400 | `SET000026` | O lote não está em `pending_settlements_insertion` (já foi encerrado ou descartado). | | 400 | `SET000013` | Já existe liquidação com este `external_id` no lote. Consulte-a em vez de recriar. | | 409 | `SET000053` | Duas requisições simultâneas com o mesmo `external_id`; uma delas foi gravada. | | 400 | `SET000012` | `asset_type` inválido. | | 400 | `SET000025` | `settlement_type` inválido. | | 400 | `SET000014` | `total_value` com mais de duas casas decimais, ou zero num tipo que não aceita zero. | | 400 | `SET000019` | Nenhum identificador do ativo foi informado. | | 400 | `SET000020` | Mais de um identificador do ativo, ou mais de um identificador da parcela. | | 400 | `SET000029` | Tipo de liquidação por parcela sem identificação da parcela. | | 400 | `SET000040` / `SET000041` | Tipo de liquidação ou identificador não aceito para este `asset_type`. | | 400 | `SET000022` / `SET000023` / `SET000047` | O ativo não está ativo ou não aceita este tipo de liquidação no status atual. | | 400 | `SET000086` / `SET000087` / `SET000088` | `remaining_face_value` fora de `installment_amortization`, com mais de duas casas, ou com a liquidação atingindo mais de um ativo. | | 400 | `SET000092` / `SET000093` / `SET000094` | `asset_extension` sem `new_maturity_date`, `new_maturity_date` em outro tipo, ou prorrogação atingindo mais de um ativo. | | 400 | `SET000112` / `SET000113` / `SET000114` | `asset_reduction_value` fora de `installment_amortization`/`installment_partial_refund`, com mais de duas casas, ou maior que `total_value`. | | 400 | `SET000104` / `SET000105` | `installment_payment_reversal` sem `reversed_settlement_external_id`/`installment_number`, ou `reversed_settlement_external_id` em outro tipo. | | 400 / 404 / 409 | `SET000106` a `SET000111`, `SET000115` | A liquidação estornada não existe, não está `settled`, é de outro tipo, parcela ou ativo, já foi estornada, ou o valor difere. | | 404 | `SET000015` | Nenhum ativo encontrado na carteira do fundo com o identificador informado. | | 400 | `SET000035` / `SET000042` / `SET000052` / `SET000060` | A parcela informada não existe ou não tem saldo no ativo. | | 400 | `SET000046` | Já existe, no mesmo lote, outra liquidação do mesmo grupo para o mesmo ativo/parcela. | | 400 | `SET000080` | Liquidação total de um ativo que já está liquidado (valor presente zero). | | 400 | `SET000066` | Valor pago fora da tolerância e o fundo está configurado para recusar automaticamente. | | 400 | `SET000067` | `collection_origin_type` inválido. | | 400 | `SET000078` | `collection_origin_type` é `collection_agent` sem `counter_party_document_number`. | | 400 | `SET000001` | `counter_party_document_number` não é um CPF/CNPJ válido. | | 400 | `QIT000001` | Corpo inválido (campo obrigatório ausente, tipo errado ou campo não aceito). | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # Consulta de Liquidação URL: /documentation/iaas/liquidacao_ativos/ativos/recuperacao Retorna uma liquidação de um lote de pagamento pelo `external_id` informado na inserção. Use para conferir o status da liquidação ou quando a inserção devolve duplicidade (`SET000013`). :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | -------------------------------------------- | | Gestora | `manager-api` | Leitura | | Consultoria | `consultant-api` | Visualizar Lotes | | Cedente | `assignor-api` | Leitura | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ## Request ENDPOINT /settlement/fund_class/{fund_class_key}/payment_batch/{external_id}/settlement/{settlement_external_id} MÉTODO GET ### Path params | Parâmetro | Tipo | Descrição | |---|---|---| | `fund_class_key` | string | Chave do fundo (UUID). | | `external_id` | string | O `external_id` do lote de pagamento. | | `settlement_external_id` | string | O `external_id` da liquidação, informado no corpo da [inserção](/documentation/iaas/liquidacao_ativos/ativos). | ## Response STATUS 200 O objeto é o mesmo devolvido na [inserção da liquidação](/documentation/iaas/liquidacao_ativos/ativos#atributos-da-resposta): os campos enviados no corpo da inserção mais os dados calculados pela QI Tech, com o `status` atual. ```json title="Response 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", "asset_external_id": "CCB-0001", "assignor_document_number": "33.444.555/0001-81", "borrower_document_number": "969.698.790-03", "status": "settled", "type": "installment_settlement", "settlement_key": "b2c3d4e5-f6a7-8901-abcd-ef1234567890", "total_number_of_units": 1, "settlement_result": 0.0, "next_execution_datetime": "2025-01-01 13:00:00.000000", "counter_party_document_number": "969.698.790-03", "assets": [ { "asset_key": "f34e9437-d025-41ab-bb53-6b94e10fd361", "number_of_units": 1, "present_value": 1250.00, "installment_face_value": 130.50 } ] } ``` ### Status da liquidação | Status | Significado | |---|---| | `validated` | Inserida e aprovada; aguarda o pagamento do lote. | | `pending_validation` | Valor pago fora da tolerância; aguarda revisão da QI Tech. | | `waiting_send_to_queue` / `on_queue` | Lote pago; liquidação em processamento na carteira do fundo. | | `settled` | Concluída e conciliada na carteira. Status final. | | `discarded` | Descartada, sem movimentação financeira. Status final. O campo `denial_reason` traz o motivo, quando houver. | | `inconsistent_asset` | A carteira recusou o pagamento por inconsistência no ativo. A QI Tech trata o caso; o lote não chega a `completed` enquanto houver liquidação neste status. | O mapa completo, com os status que geram webhook, está em [Webhooks de liquidação](/documentation/iaas/liquidacao_ativos/ativos/webhook). ## Erros | Status | Código | Quando acontece | |---|---|---| | 404 | `SET000011` | Não existe liquidação com este `settlement_external_id` no lote informado (ou o lote não existe neste fundo). | | 404 | `SET000005` | A `fund_class_key` não existe. | | 403 | `SET000028` | O fundo não pertence ao seu perfil (gestora do fundo, consultoria vinculada ou cedente associado). | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # 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. A gestora e a consultoria do fundo recebem os webhooks de todas as liquidações; o cedente recebe apenas os das liquidações de ativos cedidos por ele. ::: ## Fluxo de status da liquidação Nem toda mudança de status gera webhook. Só três situações notificam: a conclusão (`settled`) e o resultado de uma revisão da QI Tech (`validated` ou `discarded`). Para os demais status, use a [consulta de liquidação](/documentation/iaas/liquidacao_ativos/ativos/recuperacao). ![Fluxo de status da liquidação, destacando os status que geram webhook](/img/diagrams/iaas-liquidacao-ativos-ativos-webhook.svg) _Como ler o diagrama: **contorno tracejado** = status sem webhook · **azul** = webhook de andamento · **verde** = conclusão com sucesso · **vermelho** = descarte notificado._ | Status | Quando acontece | Webhook? | |---|---|---| | `validated` | Na [inserção](/documentation/iaas/liquidacao_ativos/ativos), quando o valor pago está dentro da tolerância. | Não — é a resposta da própria inserção. | | `pending_validation` | Na inserção, quando o valor pago diverge do esperado além da tolerância. A liquidação aguarda revisão da QI Tech. | Não — é a resposta da própria inserção. | | `validated` (após revisão) | A QI Tech aprova uma liquidação que estava em `pending_validation`. | **Sim** | | `discarded` (após revisão) | A QI Tech descarta uma liquidação que estava em `pending_validation` ou `validated`, com o lote ainda aberto. | **Sim** | | `waiting_send_to_queue` / `on_queue` | O lote foi pago e a liquidação está sendo enviada à carteira do fundo. | Não | | `settled` | A liquidação foi conciliada na carteira. Status final de sucesso. | **Sim** | | `inconsistent_asset` | A carteira recusou o pagamento por inconsistência no ativo. A QI Tech trata o caso e reprocessa; o lote não chega a `completed` enquanto houver liquidação neste status. | Não | | `discarded` (sem aviso) | O lote foi descartado (as liquidações abertas são descartadas junto), ou a carteira recusou em definitivo uma liquidação de valor zero. | Não — no descarte do lote, o aviso é o [webhook do lote](/documentation/iaas/liquidacao_ativos/lote_pagamento/webhook) com `discarded`. | ## 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). Se a liquidação atingir mais de um ativo, traz o primeiro. | **Identificação do ativo:** | Campo | Tipo | Descrição | |---|---|---| | `contract_number` | string | Número do contrato. Presente se informado na criação; em CCBs e contratos, é preenchido a partir da carteira mesmo quando não informado. | | `asset_external_id` | string | `external_id` do ativo no sistema do parceiro. Presente se informado na criação; em CCBs e contratos, é preenchido a partir da carteira mesmo quando não informado. | **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). | | `new_maturity_date` | string | Nova data de vencimento. Presente em `asset_extension`. | **Campos de parcela — presentes apenas para tipos de liquidação por parcela (`installment_*` e `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": "11.222.333/0001-81", "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": "11.222.333/0001-81", "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 Aprovada após Revisão STATUS validated Enviado quando a QI Tech aprova uma liquidação que estava em `pending_validation`. A liquidação segue para o processamento normal quando o lote for pago. O payload tem a mesma estrutura, com `settlement_status` igual a `validated`. --- ### Liquidação Descartada STATUS discarded Enviado quando a QI Tech descarta uma liquidação após revisão — por exemplo, uma liquidação em `pending_validation` cujo valor não se confirma. Liquidações descartadas não geram movimentação financeira. Descartes que acontecem junto com o descarte do lote, ou por rejeição definitiva da carteira para liquidações de valor zero, **não** geram este webhook. Veja o [mapa de status](#fluxo-de-status-da-liquidacao). ```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": "11.222.333/0001-81", "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 / pending_validation POST /settlement/fund_class/{fund_class_key}/payment_batch/{external_id}/settlement Cada liquidação recebe validated ou, se o valor pago divergir do esperado além da tolerância, pending_validation (revisão pela QI Tech; o resultado chega por webhook). Não há como remover uma liquidação individual: se necessário, descarte o lote e crie outro. Ver documentação completa → 3 Encerramento do lote Agente Integrador Sinaliza que todas as liquidações foram inseridas e que o processamento pode iniciar — ou descarta o lote inteiro. Lote: pending_payment / pending_validation / pending_discard Liquidação: validated Processar lote pending_payment É necessário ter ao menos uma liquidação no lote. Se houver liquidação em revisão, o lote fica em pending_validation e segue sozinho para pending_payment ao fim da revisão. Descartar lote pending_discard → discarded Nenhuma liquidação será processada. O webhook do lote com discarded confirma o fim do fluxo. 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 → 4 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 consulta de lote para acompanhar o lote. GET /settlement/fund_class/{fund_class_key}/payment_batch/{external_id} Consulta opcional do status atual do lote. Webhooks do lote → 5 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. Se a carteira recusar o ativo, a liquidação fica em inconsistent_asset (sem webhook) até a QI Tech tratá-la. 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 4) | 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 5) | Liquidação concluída e conciliada na carteira. | | 3 | `settlement.settlement_status_change` | `settlement_status` | `validated` | Por liquidação, quando a QI Tech aprova uma liquidação que estava em `pending_validation` | Nenhuma: a liquidação segue o fluxo normal. | | 4 | `settlement.settlement_status_change` | `settlement_status` | `discarded` | Por liquidação, quando a QI Tech a descarta após revisão | Liquidação não será processada. Nenhuma movimentação financeira é gerada. | | 5 | `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. | | 6 | `settlement.payment_batch_status_change` | `status` | `discarded` | Quando o descarte do lote é concluído (por solicitação do parceiro ou descarte automático de lotes em aberto) | Nenhuma liquidação do lote será processada. As liquidações abertas são descartadas sem webhook próprio. | :::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:** `contract_number` e `asset_external_id` aparecem quando informados na criação; em CCBs e contratos, os dois são preenchidos a partir da carteira. - **Campos de parcela** (`installment_number`, `installment_maturity_date`, `installment_external_id`): presentes somente para tipos de liquidação por parcela (`installment_*` e `gloss`). 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 DTVM. 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 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: ```text /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. :::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)** Para conferir um lote já criado, use a [consulta de lote](/documentation/iaas/liquidacao_ativos/lote_pagamento/recuperacao). ### 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)** Não há endpoint para remover uma liquidação individual. Se uma liquidação foi inserida por engano, descarte o lote no encerramento e crie um novo. Para conferir uma liquidação já inserida, use a [consulta de liquidação](/documentation/iaas/liquidacao_ativos/ativos/recuperacao). ### 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 Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | ---------------------------------------------- | | Gestora | `manager-api` | Escrita | | Consultoria | `consultant-api` | Criar Lotes | | Cedente | `assignor-api` | Escrita | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: :::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: ```text /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. Em caso de erro, reenvie a requisição. Duplicidade (`SET000009`) significa que o lote já existe: consulte-o pela [consulta de lote](/documentation/iaas/liquidacao_ativos/lote_pagamento/recuperacao) em vez de recriar. Veja [Reenvio e duplicidade](/documentation/iaas/introducao/erros#reenvio-e-duplicidade). ::: ## 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 do lote no formato `YYYY-MM-DD`. Quando omitida, vale a data corrente (horário de Brasília). Não pode ser anterior à data contábil atual do fundo. | | `end_to_end_id` | string | opcional | Identificador end-to-end do Pix da contraparte financeira da liquidação (32 caracteres, começando com `E`). | | `source_document_number` | string | opcional | CPF ou CNPJ da contraparte financeira da liquidação, com pontuação (ex: `11.222.333/0001-81` ou `969.698.790-03`). Quando omitido, pode ser preenchido pelo documento padrão da configuração de liquidação do fundo. | | `settlement_expenses` | array | opcional | Despesas de liquidação descontadas no lote, no máximo uma por tipo. Veja [Atributos de `settlement_expenses`](#atributos-de-settlement_expenses). | :::caution Atenção Os campos `account` e `account_key` não devem ser passados simultaneamente (`SET000034`). Caso nenhum dos dois seja informado, a liquidação será gerada na conta principal do fundo. A conta deve pertencer ao fundo ou tê-lo como agente autorizado (`SET000032`). ::: #### 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. | #### Atributos de `settlement_expenses` | Campo | Tipo | Obrigatoriedade | Descrição | |---|---|---|---| | `amount` | number | obrigatório | Valor da despesa. | | `expense_type` | string | obrigatório | `bank_account` (despesa bancária) ou `collection_agent_fee` (taxa de agente de cobrança). | | `description` | string | opcional | Descrição da despesa. Máximo de 255 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": "22.333.444/0001-81" }, "fund_class_key": "4b8377d0-58ec-479f-8ee9-9f963d5c47ad", "document_number": "11.222.333/0001-81", "accounting_date": "2025-01-01", "payment_batch_automatic_discard": false }, "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 do lote no formato `YYYY-MM-DD`. | | `account_key` | string | Chave da conta associada ao lote (UUID). | | `settlement_expenses` | array | Despesas de liquidação criadas, com `settlement_expense_key`, `amount`, `status`, `description` e `type`. Presente apenas quando informadas. | A resposta também ecoa os demais campos enviados no corpo (por exemplo `account`, `source_document_number`, `end_to_end_id`). #### 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. | | `accounting_date` | string | Data contábil atual do fundo, no formato `YYYY-MM-DD`. | | `payment_batch_automatic_discard` | boolean | Indica se o fundo descarta automaticamente lotes deixados em aberto. | #### 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. | ## 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. ## Erros | Status | Código | Quando acontece | |---|---|---| | 409 | `SET000009` | Já existe lote com este `external_id` no fundo. Consulte-o em vez de recriar. | | 404 | `SET000005` | A `fund_class_key` não existe. | | 403 | `SET000028` | O fundo não pertence ao seu perfil (gestora do fundo, consultoria vinculada ou cedente associado). | | 400 | `SET000044` | `reference_date` anterior à data contábil atual do fundo. | | 404 | `SET000031` | A conta informada (`account_key` ou `account`) não foi encontrada. | | 400 | `SET000032` | A conta informada não pertence ao fundo. | | 400 | `SET000034` | `account` e `account_key` enviados juntos. | | 403 | `SET000085` | Conta escrow não autorizada a operar para este fundo. | | 400 | `SET000001` | `source_document_number` não é um CPF/CNPJ válido. | | 400 | `SET000050` / `SET000051` | `expense_type` inválido, ou mais de uma despesa do mesmo tipo. | | 400 | `QIT000001` | Corpo inválido (campo obrigatório ausente, formato inválido ou campo não aceito). | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # 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. :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | ---------------------------------------------- | | Gestora | `manager-api` | Escrita | | Consultoria | `consultant-api` | Criar Lotes | | Cedente | `assignor-api` | Escrita | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: :::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. Só é aceito com o lote em `pending_settlements_insertion` e com ao menos uma liquidação `validated` ou `pending_validation`. | | `discarded` | Descarta o lote inteiro. Nenhuma liquidação será processada. Aceito com o lote em `pending_settlements_insertion`, `pending_validation` ou `pending_payment`. | ## 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. Veja abaixo. | **Status devolvido:** | Você enviou | Status devolvido | O que significa | |---|---|---| | `pending_payment` | `pending_payment` | Lote encerrado; aguarda a confirmação do pagamento. | | `pending_payment` | `pending_validation` | Há liquidações em revisão pela QI Tech. Quando a revisão terminar, o lote segue sozinho para `pending_payment`. | | `discarded` | `pending_discard` ou `pending_discard_on_cash_account` | Descarte em processamento. O status final `discarded` chega pelo [webhook do lote](/documentation/iaas/liquidacao_ativos/lote_pagamento/webhook). | ## Próximos passos Após encerrar o lote, o processamento é iniciado automaticamente. Acompanhe o resultado através dos webhooks ou da [consulta do lote](/documentation/iaas/liquidacao_ativos/lote_pagamento/recuperacao): 1. **[Webhooks do lote de pagamento](/documentation/iaas/liquidacao_ativos/lote_pagamento/webhook)** — notificação quando o lote for pago, concluído ou descartado. 2. **[Webhooks das liquidações](/documentation/iaas/liquidacao_ativos/ativos/webhook)** — notificação individual de cada liquidação processada. ## Erros | Status | Código | Quando acontece | |---|---|---| | 404 | `SET000005` | A `fund_class_key` não existe. | | 403 | `SET000028` | O fundo não pertence ao seu perfil (gestora do fundo, consultoria vinculada ou cedente associado). | | 404 | `SET000010` | O lote informado na URL não existe neste fundo. | | 400 | `SET000026` | `batch_status` diferente de `pending_payment` ou `discarded`. | | 400 | `SET000049` | Pedido de encerramento para um lote já em `pending_payment`, `paid` ou `completed`. | | 400 | `SET000016` | Pedido de encerramento para um lote fora de `pending_settlements_insertion` (por exemplo, em `pending_validation` ou em descarte). | | 400 | `SET000017` | O lote não tem nenhuma liquidação `validated` ou `pending_validation`. | | 400 | `SET000069` | Pedido de descarte para um lote já em status final (`paid`, `completed` ou `discarded`). | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # 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. Para consultar um lote específico pelo `external_id`, use a [consulta de lote](/documentation/iaas/liquidacao_ativos/lote_pagamento/recuperacao). :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | -------------------------------------------- | | Gestora | `manager-api` | Leitura | | Consultoria | `consultant-api` | Visualizar Lotes | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ## 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`. | ```text 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": "22.333.444/0001-81" }, "fund_class_key": "a3ecf74b-d280-4d3c-aefd-cb223dbf0451", "document_number": "11.222.333/0001-81", "accounting_date": "2025-08-08", "payment_batch_automatic_discard": false }, "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_validation` | Lote encerrado com liquidações em revisão pela QI Tech. | | `pending_payment` | Lote encerrado, aguardando processamento do pagamento. | | `paid` | Pagamento do lote realizado; liquidações em processamento. | | `completed` | Todas as liquidações chegaram a `settled` ou `discarded`. | | `pending_discard` | Descarte solicitado, em processamento. | | `pending_discard_on_cash_account` | Descarte solicitado, aguardando o cancelamento na conta caixa. | | `discarded` | Lote descartado. | Os lotes também trazem `settlement_expenses` quando há despesas de liquidação, e ecoam os campos enviados na criação. Veja a [consulta de lote](/documentation/iaas/liquidacao_ativos/lote_pagamento/recuperacao#atributos-da-resposta). ## Erros | Status | Código | Quando acontece | |---|---|---| | 404 | `SET000005` | A `fund_class_key` não existe. | | 403 | `SET000028` | O fundo não pertence ao seu perfil. | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # Consulta de Lote de Pagamento URL: /documentation/iaas/liquidacao_ativos/lote_pagamento/recuperacao Retorna um lote de pagamento pelo `external_id` informado na criação. Use para acompanhar o status do lote ou quando a criação devolve duplicidade (`SET000009`). :::info Disponível em | Perfil | Host | Permissão exigida | | ----------- | ---------------- | -------------------------------------------- | | Gestora | `manager-api` | Leitura | | Consultoria | `consultant-api` | Visualizar Lotes | | Cedente | `assignor-api` | Leitura | URL base de cada host: [Ambientes (Hosts)](/documentation/iaas/introducao/inicio#ambientes-hosts). ::: ## Request ENDPOINT /settlement/fund_class/{fund_class_key}/payment_batch/{external_id} MÉTODO GET ### Path params | Parâmetro | Tipo | Descrição | |---|---|---| | `fund_class_key` | string | Chave do fundo (UUID). | | `external_id` | string | O `external_id` informado na [criação do lote](/documentation/iaas/liquidacao_ativos/lote_pagamento/criacao). Também aceita o `payment_batch_key` devolvido pela QI Tech. | ## Response STATUS 200 A resposta ecoa os campos enviados na criação do lote (por exemplo `account`, `source_document_number`, `end_to_end_id`) e acrescenta os dados abaixo. ```json title="Response 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" }, "fund_class": { "name": "FUNDO DE INVESTIMENTO EM DIREITOS CREDITÓRIOS EXEMPLO", "manager": { "name": "EXEMPLO CAPITAL", "manager_key": "a7498c6c-1893-42ec-a8f3-bc6ad0c6b52c", "document_number": "22.333.444/0001-81" }, "fund_class_key": "4b8377d0-58ec-479f-8ee9-9f963d5c47ad", "document_number": "11.222.333/0001-81", "accounting_date": "2025-01-01", "payment_batch_automatic_discard": false }, "payment_batch_key": "63f0dbec-e9c4-4943-929e-1d47b9edbb0b", "status": "pending_payment", "reference_date": "2025-01-01", "account_key": "5e621ba2-b4ac-4ddd-9893-82d220e1577e", "total_value": 4520.75, "settlement_expenses": [ { "settlement_expense_key": "0b6f3c1e-8f0a-4c55-9a4e-2f1d7c9e3b10", "amount": 15.00, "status": "pending_submission", "description": "Despesa de Liquidação - Despesa Bancária", "type": "bank_account" } ] } ``` ### Atributos da resposta | Campo | Tipo | Descrição | |---|---|---| | `external_id` | string | Chave externa do lote fornecida pelo parceiro. | | `description` | string | Descrição do lote. Quando não informada na criação, é gerada como `Lote de Pagamento - {reference_date} - {external_id}`. | | `fund_class` | object | Dados do fundo: `name`, `manager` (`name`, `manager_key`, `document_number`), `fund_class_key`, `document_number`, `accounting_date` (data contábil atual do fundo) e `payment_batch_automatic_discard`. | | `payment_batch_key` | string | Identificador único do lote gerado pela QI Tech (UUID). | | `status` | string | Status atual do lote. Veja abaixo. | | `reference_date` | string | Data de referência do lote, no formato `YYYY-MM-DD`. | | `account_key` | string | Chave da conta associada ao lote (UUID). | | `total_value` | number | Valor total do lote. Presente depois que o total é apurado. | | `settlement_expenses` | array | Despesas de liquidação informadas na criação, com `settlement_expense_key`, `amount`, `status`, `description` e `type`. Presente apenas quando há despesas. | ### Status do lote | Status | Significado | |---|---| | `pending_settlements_insertion` | Lote criado, aceitando liquidações. | | `pending_validation` | Lote encerrado com liquidações em revisão pela QI Tech. Ao fim da revisão, segue para `pending_payment`. | | `pending_payment` | Lote encerrado, aguardando a confirmação do pagamento. | | `paid` | Pagamento confirmado; as liquidações estão sendo processadas. | | `completed` | Todas as liquidações chegaram a `settled` ou `discarded`. Status final. | | `pending_discard` / `pending_discard_on_cash_account` | Descarte solicitado, em processamento. | | `discarded` | Lote descartado. Status final. | ## Erros | Status | Código | Quando acontece | |---|---|---| | 404 | `SET000010` | Não existe lote com este `external_id` (nem com este `payment_batch_key`) no fundo. | | 404 | `SET000005` | A `fund_class_key` não existe. | | 403 | `SET000028` | O fundo não pertence ao seu perfil (gestora do fundo, consultoria vinculada ou cedente associado). | Erros de autenticação, permissão e host: veja [Erros da API](/documentation/iaas/introducao/erros). --- # 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. Só três geram webhook: `paid`, `completed` e `discarded`. Os demais — `pending_settlements_insertion`, `pending_validation`, `pending_payment`, `pending_discard` e `pending_discard_on_cash_account` — resultam das suas chamadas de [criação](/documentation/iaas/liquidacao_ativos/lote_pagamento/criacao) e [encerramento](/documentation/iaas/liquidacao_ativos/lote_pagamento/fechamento), ou de etapas internas, e **não** disparam notificação. Para acompanhá-los, use a [consulta de lote](/documentation/iaas/liquidacao_ativos/lote_pagamento/recuperacao). ![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._ | Status | Quando acontece | Webhook? | |---|---|---| | `pending_settlements_insertion` | Lote criado, aceitando liquidações. | Não | | `pending_validation` | Lote encerrado com liquidações em revisão pela QI Tech. Ao fim da revisão, segue sozinho para `pending_payment`. | Não | | `pending_payment` | Lote encerrado, aguardando a confirmação do pagamento. | Não | | `paid` | Pagamento confirmado; as liquidações passam a ser processadas. | **Sim** | | `completed` | Todas as liquidações chegaram a `settled` ou `discarded`. Uma liquidação em `inconsistent_asset` segura o lote em `paid` até ser tratada. | **Sim** | | `pending_discard` / `pending_discard_on_cash_account` | Descarte solicitado (ou automático) em processamento. | Não | | `discarded` | Lote descartado. | **Sim** | ## 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-e-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": "11.222.333/0001-81", "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 DTVM 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": "11.222.333/0001-81", "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-e-formado). ```json title="Webhook Body" { "data": { "external_id": "57efbd9f-0917-4c79-9a43-bc8f1039fc78", "status": "completed", "fund_class_document_number": "11.222.333/0001-81", "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 descarte do lote é concluído. Isso ocorre: - por solicitação do parceiro integrador no [encerramento do lote](/documentation/iaas/liquidacao_ativos/lote_pagamento/fechamento) (`batch_status: discarded`); ou - por descarte automático, nos fundos configurados para isso: lotes que continuam em `pending_settlements_insertion`, `pending_validation` ou `pending_payment` quando a data contábil do fundo avança são descartados. Quando o lote já estava em `pending_payment` com valor apurado, o descarte passa antes pelo cancelamento da expectativa na conta caixa (`pending_discard_on_cash_account`). Nenhuma liquidação associada ao lote será processada após este status, e as liquidações abertas são descartadas sem webhook próprio. 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": "11.222.333/0001-81", "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" } ```