跳到主要内容

示例 — 非常规摊还

本页给出两个创建场景。集成方的交互是 fire-and-forget 的：只需发起创建调用，QI Tech 会在内部编排清算、终结与取消。不存在面向租户、专门对应非常规 event_conciliation 状态转换的 webhook；操作生效的确认通过底层操作已有的报表与 webhook 观察（例如 commercial_paper.operation_status_change）。

场景 1：某期分期的部分提前结清（early_amortization）​

覆盖单笔未来分期，允许部分支付。

POST /event_conciliation/extraordinary_event

{
  "security_key": "971380d4-469e-48f6-a64b-3afb8a88109e",
  "investment_key": "<investment_key>",
  "amortization_type": "early_amortization",
  "amount": 1500.00,
  "reference_date": "2026-04-24",
  "due_date": "2026-04-24",
  "installment_list": [3]
}

响应：201 Created

{
  "extraordinary_event_conciliation_key": "11111111-1111-4111-8111-111111111111",
  "security_key": "971380d4-469e-48f6-a64b-3afb8a88109e",
  "amortization_type": "early_amortization",
  "total_expected_amount": 1500.00,
  "total_discount_amount": 0,
  "status": "pending_conciliation",
  "reference_date": "2026-04-24",
  "due_date": "2026-04-24",
  "event_conciliation_list": [
    {
      "event_conciliation_key": "22222222-2222-4222-8222-222222222222",
      "installment_key": "33333333-3333-4333-8333-333333333333",
      "expected_amount": 1500.00,
      "discount_amount": 0,
      "due_date": "2026-04-24",
      "status": "pending_conciliation",
      "event_conciliation_type": "extraordinary"
    }
  ]
}

收到该 201 之后，集成方这一侧的集成工作即告完成。当 R$ 1.500,00 的付款到达对应的清算账户时，QI Tech（account-liquidation-api）会在内部清算该分期对账事件并更新 paid_amount；当累计金额覆盖 total_expected_amount - tolerance_amount 时，父事件转为 paid。若付款未到账，该事件会由 security-service 的每日 settlement 例行任务取消或终结。

场景 2：带折扣的全额结清（present_amount，2 期分期）​

创建一笔带合并折扣、覆盖两期分期的摊还。

POST /event_conciliation/extraordinary_event

{
  "security_key": "971380d4-469e-48f6-a64b-3afb8a88109e",
  "investment_key": "<investment_key>",
  "amortization_type": "present_amount",
  "amount": 5000.00,
  "reference_date": "2026-04-24",
  "due_date": "2026-04-24",
  "installment_list": [1, 2],
  "total_discount": 100.00
}

响应 201 Created — 会生成两个分期对账事件，其金额按 present_amount 引擎的规则分配（利息 → 罚金 → 本金）。完整的响应结构请参阅创建非常规摊还。

收到 201 之后，集成方的交互与场景 1 相同：QI Tech 会在相应付款到账时清算每个分期对账事件，若金额未在 settlement 窗口内到达，则在内部终结或取消该事件。

场景 3：未来分期按名义价值结清（nominal_amount）​

发行人希望在到期前结清第 3 期和第 4 期分期，按每期的名义价值（到期日的本金 + 利息）支付，不做现值折现。reference_date 早于两期的到期日。

{
  "security_key": "971380d4-469e-48f6-a64b-3afb8a88109e",
  "investment_key": "<investment_key>",
  "amortization_type": "nominal_amount",
  "amount": 18670.00,
  "reference_date": "2026-02-08",
  "due_date": "2026-06-06",
  "installment_list": [3, 4]
}

响应 201 Created — 每期分期生成一个分期对账事件，expected_amount 等于各期的名义价值（本例中为 9360.00 和 9310.00）。若 amount 小于两期之和，则先覆盖第 3 期，第 4 期收到剩余金额。已逾期的分期返回 EVC100030；amount 超过名义价值之和返回 EVC100031。清算时允许部分支付，与 early_amortization 相同。

场景 4：按协商金额全额结清（full_amortization）​

发行人与投资者约定以 R$ 10,000.00 结清第 1 期和第 2 期分期，尽管二者在 reference_date 的现值分别为 R$ 9,460.00 和 R$ 9,410.00。amount 按现值比例分配，每期在清算时全额结清。

{
  "security_key": "971380d4-469e-48f6-a64b-3afb8a88109e",
  "investment_key": "<investment_key>",
  "amortization_type": "full_amortization",
  "amount": 10000.00,
  "reference_date": "2026-02-08",
  "due_date": "2026-02-08",
  "installment_list": [1, 2]
}

响应 201 Created — 两个分期对账事件，expected_amount 分别为 5013.25 和 4986.75（之和等于 amount），discount_amount 分别为 4446.75 和 4423.25。amount 超过现值之和返回 EVC100035；amount 过小以致无法给每期正份额则返回 EVC100034。

故障排查​

调用创建接口时最常见的错误码。完整列表请参阅错误目录。

  • EVC100015（400，EarlyAmortizationRequiresSingleInstallment）— early_amortization 在 installment_list 中只接受恰好一期分期。请减少为 1 期。
  • EVC000007（404，InstallmentNumberNotFound）— installment_list 中提交的某个 installment_number 在目标 security 中不存在。调用前请先核对 GET /security/security/{security_key} 返回的编号。
  • QIT000001（400）— schema 被拒绝。典型原因：提交了已移除的旧版 installment_key_list 字段，或 installment_list 中含有非整数项。
  • EVC100016（400，EarlyAmortizationInstallmentOverdue）— early_amortization 的目标分期已逾期，不符合条件。请选择一期未来的分期。
  • EVC100017（400，EarlyAmortizationAmountExceedsPresentValue）— 在 early_amortization 中，amount 超过了该分期的现值。调用前请先确认 PV。
  • EVC100030（400，InstallmentNotEligibleForNominalAmortization）— 在 nominal_amount 中，installment_list 里的某期分期在 reference_date 已逾期。请只选择未来的分期。
  • EVC100031（400，NominalAmountExceedsInstallmentsNominalValue）— 在 nominal_amount 中，amount 超过了所选分期的名义价值（本金 + 利息）之和。请调低 amount。
  • EVC100033（400，DistributionDoesNotMatchAmount）— 已分配的 expected_amount 之和与所声明的 amount 相差超过 R$ 0.01。对于 present_amount，请发送等于现值之和减去 total_discount 的 amount。
  • EVC100034（400，DistributionWithZeroInstallment）— 某一所选分期的 expected_amount 将为零（例如 total_discount 等于现值，或 amount 在最后一期之前已耗尽）。请只选择 amount 能覆盖的分期。
  • EVC100035（400，AmountExceedsInstallmentsPresentValue）— amount 超过所选分期现值之和。请降低 amount。
  • EVC100013（424，SecurityApiUnavailable）— 获取现值时 Security API 暂时不可用；属临时性问题。请稍候重试。
  • SEC000031（400，PostFixedSecurityNotSupported）— V1 不支持后固定利率资产（CDI、IPCA、IGPM）。请使用 pre_price 或 pre_sac 类资产。

另请参阅​