插入清算

用于向已创建的付款批次中插入单笔清算的端点。每笔清算代表一次与基金投资组合中某项资产相关的付款（全部或部分）——例如分期清算、摊销、回购或利息支付。

适用范围

角色	主机	所需权限
管理人	`manager-api`	写入
顾问	`consultant-api`	Create Batches
转让方	`assignor-api`	写入

各主机的 Base URL：环境（主机）。

清算、回购与转付

清算和回购使用同一个端点。collection_origin_type 字段表示付款方：

borrower——由付款人/债务人支付的清算。
assignor——由转让方支付的回购。
collection_agent——由收款代理转付的款项。需提供 counter_party_document_number。
bankslip——通过 Boleto 收到的款项。

我在流程中的哪一步？

这是清算流程的第 2 步。在此之前，您应已创建付款批次。批次必须处于 pending_settlements_insertion。

Request

ENDPOINT

/settlement/fund_class/{fund_class_key}/payment_batch/{external_id}/settlement

MÉTODO

POST

Path params

参数	类型	描述
`external_id`	string	要插入清算的付款批次的 `external_id`。

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"
}

请求体属性

字段	类型	是否必填	描述
`asset_type`	string	必填	资产类型。参见 `asset_type` 枚举值。最多 255 个字符。
`total_value`	number	必填	付款总额，最多两位小数。仅在 `installment_settlement`、`asset_settlement`、`asset_refund` 和 `asset_extension` 中可以为 `0`。
`external_id`	string	必填	该清算在批次内、在集成合作伙伴系统中的唯一 key。最多 50 个字符。
`settlement_type`	string	必填	清算类型。参见 `settlement_type` 枚举值。最多 50 个字符。
`collection_origin_type`	string	可选	付款方。参见 `collection_origin_type` 枚举值。省略时，使用基金清算配置中的默认值（如有）。
`counter_party_document_number`	string	条件必填	付款方的 CPF 或 CNPJ，带标点（14 到 18 个字符）。当 `collection_origin_type` 为 `collection_agent` 且基金清算配置未定义默认证件号时必填。使用 `borrower`、`bankslip` 或 `assignor` 时，如省略，则以该资产付款人或转让方的证件号填充。
`contract_number`	string	可选	资产对应的合同编号。最多 50 个字符。
`asset_external_id`	string	可选	资产的唯一标识 key，在转让时提供。最多 50 个字符。
`asset_key`	string	可选	资产在 QI Tech 中的内部 key（UUID，36 个字符）。
`if_code`	string	可选	金融工具代码（B3）。最多 36 个字符。
`participant_control_number`	string	可选	转让时提供的参与方控制编号。最多 50 个字符。
`installment_number`	integer	条件必填	分期期数。参见分期标识。
`installment_maturity_date`	string	条件必填	分期到期日，格式为 `YYYY-MM-DD`。
`installment_external_id`	string	条件必填	分期的外部标识。最多 50 个字符。
`collection_date`	string	可选	付款日期，格式为 `YYYY-MM-DD`。供集成方内部控制使用。
`remaining_face_value`	number	可选	付款后该分期剩余的面值余额。仅在 `installment_amortization` 中且清算只涉及单一资产时接受。
`asset_reduction_value`	number	可选	当与付款金额不同时，从资产中扣减的金额。仅在 `installment_amortization` 和 `installment_partial_refund` 中接受。不得大于 `total_value`。
`new_maturity_date`	string	条件必填	新的到期日，格式为 `YYYY-MM-DD`。在 `asset_extension` 中必填，其他类型拒绝该字段。
`reversed_settlement_external_id`	string	条件必填	被冲正清算的 `external_id`。在 `installment_payment_reversal` 中必填，其他类型拒绝该字段。

external_id 的区别

请求体中的 external_id 字段指的是清算的标识。URL 中的 external_id 指的是付款批次的标识。

资产和分期的标识

资产标识只能填写一个：contract_number、asset_external_id、asset_key、if_code 或 participant_control_number。一个都不填或填写多个都会返回错误。Duplicata 及其他信用权利不接受 contract_number 和 if_code；CCB 及其他信贷业务不接受 participant_control_number。
对于按分期清算的类型（installment_* 和 gloss），分期标识只能填写一个：installment_number、installment_maturity_date 或 installment_external_id。对于 CCB 和合同，仅凭 installment_external_id 也可以识别资产。

`asset_type` 枚举值

值	描述
`ccb`	银行信贷凭证（Cédula de Crédito Bancário）
`cce`	出口信贷凭证（Cédula de Crédito à Exportação）
`structured_ccb`	结构化银行信贷凭证
`structured_cce`	结构化出口信贷凭证
`structured_nce`	结构化出口信贷票据（Nota de Crédito à Exportação）
`structured_cci`	结构化不动产信贷凭证（Cédula de Crédito Imobiliário）
`duplicata_mercantil`	商业 duplicata（Duplicata Mercantil）
`duplicata_servicos`	服务 duplicata（Duplicata de Serviços）
`discounted_contract`	贴现合同
`cte`	电子运输单据（Conhecimento de Transporte Eletrônico）
`check`	支票
`promissory_note`	本票
`legal_fees`	律师费
`debt_acknowledgment`	债务确认书
`financing_contract`	融资合同
`contract`	合同

`settlement_type` 枚举值

值	描述
`asset_settlement`	资产全额清算。
`asset_amortization`	资产摊销。
`fine_payment`	资产利息或滞纳金支付。
`asset_refund`	资产全额退回。
`asset_partial_refund`	资产部分退回。
`asset_gloss`	资产扣减（glosa）。
`asset_extension`	Duplicata 及其他信用权利的到期日展期。需提供 `new_maturity_date` 且只涉及单一资产。
`installment_settlement`	分期清算。
`installment_amortization`	分期摊销。
`installment_fine_payment`	分期利息或滞纳金支付。
`installment_refund`	分期全额退回。
`installment_partial_refund`	分期部分退回。
`installment_payment_reversal`	冲正 CCB 或信贷业务某一分期的付款。需提供 `reversed_settlement_external_id` 和 `installment_number`；`total_value` 必须与被冲正清算的金额相同。
`gloss`	分期扣减（glosa）。
`rco_revenue`	RCO 收入。

合同（debt_acknowledgment、financing_contract、contract）仅接受 asset_settlement、asset_amortization、installment_settlement 和 installment_amortization。

`collection_origin_type` 枚举值

值	描述
`borrower`	清算——由付款人/债务人付款。
`assignor`	回购——由转让方付款。
`collection_agent`	由收款代理转付。需提供 `counter_party_document_number`（或基金配置中的默认证件号）。
`bankslip`	通过 Boleto 收到的款项。

Response

STATUS

201

响应会回显请求体中发送的字段，并附加 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
        }
    ]
}

响应属性

除请求体中发送的字段外：

字段	类型	描述
`status`	string	插入后的清算状态：`validated` 或 `pending_validation`。见下文。
`type`	string	清算类型（与 `settlement_type` 的值相同）。
`settlement_key`	string	QI Tech 生成的清算唯一标识（UUID）。
`total_value`	number	付款总额。在 `gloss`、`asset_gloss` 和 `installment_payment_reversal` 中为负数。
`total_number_of_units`	integer	受该清算影响的资产单位总数。
`installment_number`	integer	所定位分期的期数。适用时返回。
`settlement_result`	number	付款金额与资产或分期预期金额之间的差额。计算后返回。
`contract_number`, `asset_external_id`	string	在投资组合中定位到的资产的标识（CCB 和合同）。
`assignor_document_number`, `borrower_document_number`	string	资产转让方和付款人的证件号。
`counter_party_document_number`	string	付款方的证件号。提供或自动填充时返回。
`collection_origin_type`	string	付款来源。提供或由基金配置确定时返回。
`next_execution_datetime`	string	QI Tech 处理用的控制字段。可忽略。
`denial_reason`	string	废弃原因。仅在已废弃的清算中返回。
`assets`	array	受该清算影响的资产。参见 `assets` 属性。

响应中的状态：

validated——付款金额与资产或分期的预期金额之差在容差范围内。批次付款后将处理该清算。
pending_validation——付款金额与预期金额的差异超出容差，该清算等待 QI Tech 审核。审核结束后，其状态变为 validated 或 discarded，您会收到相应的清算 webhook。根据基金的清算配置，这种差异也可能直接导致插入被拒绝，返回 SET000066。

`assets` 属性

字段	类型	描述
`asset_key`	string	资产的唯一标识（UUID）。
`number_of_units`	integer	资产的单位数量。
`present_value`	number	资产现值，以雷亚尔为单位。
`installment_face_value`	number	分期面值。适用时返回。
`installment_post_maturity_interest_value`	number	分期的到期后利息金额。适用时返回。
`installment_delay_interest_value`	number	分期的逾期利息金额。适用时返回。
`installment_delay_fine_value`	number	分期的逾期罚金金额。适用时返回。
`total_purchase_value`	number	资产的购入金额。适用时返回。
`maturity_date`	string	资产到期日。适用时返回。
`contract_number`	string	资产的合同编号。适用时返回。
`external_id`	string	资产的外部标识。适用时返回。

重发与重复

如发生错误，请重发请求。重复（SET000013）表示该清算已存在于此批次中：请通过清算查询获取它，而不是重新创建。参见重发与重复。

后续步骤

插入所有所需清算后，流程继续：

关闭批次——表明所有清算均已插入，以便开始处理。

没有用于移除单笔清算的端点。如果误插入了某笔清算，请在关闭时废弃该批次（batch_status: discarded），并使用正确的清算新建一个批次。

错误

状态码	代码	触发条件
404	`SET000010`	URL 中指定的批次在该基金中不存在。
403	`SET000028`	该基金不属于您的角色。
400	`SET000026`	批次不处于 `pending_settlements_insertion`（已关闭或已废弃）。
400	`SET000013`	该批次中已存在使用此 `external_id` 的清算。请查询该清算，而不是重新创建。
409	`SET000053`	两个使用相同 `external_id` 的请求同时到达；其中一个已被保存。
400	`SET000012`	`asset_type` 无效。
400	`SET000025`	`settlement_type` 无效。
400	`SET000014`	`total_value` 超过两位小数，或在不接受零的类型中为零。
400	`SET000019`	未提供资产标识。
400	`SET000020`	提供了多个资产标识，或多个分期标识。
400	`SET000029`	按分期清算的类型缺少分期标识。
400	`SET000040` / `SET000041`	该 `asset_type` 不接受此清算类型或标识。
400	`SET000022` / `SET000023` / `SET000047`	资产不处于有效状态，或在当前状态下不接受此清算类型。
400	`SET000086` / `SET000087` / `SET000088`	`remaining_face_value` 用于 `installment_amortization` 以外的类型、超过两位小数，或清算涉及多个资产。
400	`SET000092` / `SET000093` / `SET000094`	`asset_extension` 缺少 `new_maturity_date`、在其他类型中提供了 `new_maturity_date`，或展期涉及多个资产。
400	`SET000112` / `SET000113` / `SET000114`	`asset_reduction_value` 用于 `installment_amortization`/`installment_partial_refund` 以外的类型、超过两位小数，或大于 `total_value`。
400	`SET000104` / `SET000105`	`installment_payment_reversal` 缺少 `reversed_settlement_external_id`/`installment_number`，或在其他类型中提供了 `reversed_settlement_external_id`。
400 / 404 / 409	`SET000106` 至 `SET000111`、`SET000115`	被冲正的清算不存在、不处于 `settled`、类型、分期或资产不同、已被冲正，或金额不一致。
404	`SET000015`	在基金投资组合中未找到与所提供标识对应的资产。
400	`SET000035` / `SET000042` / `SET000052` / `SET000060`	所指定的分期不存在，或在资产中没有余额。
400	`SET000046`	同一批次中已有同一组别、针对同一资产/分期的另一笔清算。
400	`SET000080`	对已清算完毕（现值为零）的资产进行全额清算。
400	`SET000066`	付款金额超出容差，且基金配置为自动拒绝。
400	`SET000067`	`collection_origin_type` 无效。
400	`SET000078`	`collection_origin_type` 为 `collection_agent`，但未提供 `counter_party_document_number`。
400	`SET000001`	`counter_party_document_number` 不是有效的 CPF/CNPJ。
400	`QIT000001`	请求体无效（缺少必填字段、类型错误或包含不接受的字段）。

认证、权限和主机相关错误：参见 API 错误。

Request​

Path params​

请求体属性​

资产和分期的标识​

asset_type 枚举值​

settlement_type 枚举值​

collection_origin_type 枚举值​

Response​

响应属性​

assets 属性​

重发与重复​

后续步骤​

错误​