Inserção de Liquidações

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.

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

Onde estou no fluxo?

Este é o 2º passo do fluxo de liquidação. Antes deste passo, você deve ter criado o lote de pagamento.

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.

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. 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. Máximo de 50 caracteres.
collection_origin_type	string	opcional	Determina se a operação é uma liquidação (borrower) ou uma recompra (assignor). Veja 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.

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.

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

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

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.

{
  "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.

{
  "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 — sinalize que todas as liquidações foram inseridas para que o processamento seja iniciado.