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.

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

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.

Onde estou no fluxo?

Este é o 2º passo do fluxo de liquidação. Antes deste passo, você deve ter criado o lote de pagamento. 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.

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 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. Máximo de 50 caracteres.
collection_origin_type	string	opcional	Quem pagou. Veja 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.
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.

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.

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.

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 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 em vez de recriar. Veja Reenvio e duplicidade.

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.

Não há endpoint para remover uma liquidação individual. Se uma liquidação foi inserida por engano, descarte o lote no encerramento (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.