跳到主要内容

示例 — 非常规摊还

本页给出两个创建场景。集成方的交互是 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 窗口内到达，则在内部终结或取消该事件。

故障排查​

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

  • 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。
  • EVC100013（424，SecurityApiUnavailable）— 获取现值时 Security API 暂时不可用；属临时性问题。请稍候重试。
  • SEC000031（400，PostFixedSecurityNotSupported）— V1 不支持后固定利率资产（CDI、IPCA、IGPM）。请使用 pre_price 或 pre_sac 类资产。

另请参阅​