跳到主要内容

创建非常规摊还

本端点针对某笔发行的一期或多期 installment 创建非常规摊还。event-conciliation-service 会将这些分期归入单个非常规摊还事件，按所提供的 amortization_type 分配所声明的 amount，并通过 security-service 获取现值 — 集成方无需在自己这一侧计算现值。reference_date 由调用方在非常规摊还请求中提供，是本服务在划分逾期分期和进行按比例折现时使用的唯一时间基准。

Request​

ENDPOINT
/event_conciliation/extraordinary_event
方法
POST

Request Body​

installment_list（installment_number 数组，整数 ≥ 1）对所有类型均为必填：它指定目标分期，amortization_type 则决定 amount 在这些分期之间的分配方式。installment_list 中提交的数字会由服务与对应 security 的 installment_number 进行解析匹配。

示例 — early_amortization（单笔未来分期）：

{
  "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": [1]
}

示例 — equal_amount（在所选分期之间按比例分配）：

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

示例 — nominal_amount（未来分期按名义价值结清）：

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

Request Body Params​

字段类型是否必填描述
security_keystring (UUID)是将被摊还的资产（security）的唯一键值。
investment_keystring (UUID)是目标投资的键值。security-service 在计算现值时以此作为按比例分配的基准。
amortization_typestring是分配策略。取值：equal_amount、first_installments、present_amount、matured_installments、early_amortization、nominal_amount、full_amortization。
amountnumber是待摊还的总金额（以 BRL 计）。按 amortization_type 在所选分期之间进行分配。
reference_datestring (date)是参考日期，格式为 YYYY-MM-DD。由调用方提供 — 服务将其作为"今天"，用于划分逾期分期并对现值进行按比例折现。
due_datestring (date)是目标清算日期（通常与 reference_date 相同）。
installment_list整数数组（≥ 1）是目标分期的 installment_number 列表（不是 UUID），minItems: 1。对所有类型均为必填 — 省略时返回 EVC100002。服务会将每个数字与该 security 的 installment_number 进行匹配；不存在的数字会返回 EVC000007。旧版 installment_key_list 已移除 — 仍提交该字段的客户端会收到 QIT000001（400）。
total_discountnumber否仅与 present_amount 搭配使用 — 按利息 → 罚金 → 本金的顺序分配折扣。
number_of_installmentsinteger条件必填使用 first_installments 时必填：所选分期中（按到期日）有多少期获得金额。

Response​

STATUS
201
Response Body
{
  "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"
    }
  ]
}

Response Body Params​

字段类型描述
extraordinary_event_conciliation_keystring (UUID)所创建的非常规摊还总事件的键值。
security_keystring (UUID)资产键值 — 回显提交的值。
amortization_typestring所选的摊还类型 — 回显提交的值。
total_expected_amountnumber由所选类型的引擎在各 event_conciliation（分期对账事件）之间分配的总额。
total_discount_amountnumber已应用的折扣总额。仅在 present_amount 时不为零。
statusstring非常规事件的初始状态。创建时恒为 pending_conciliation。
reference_datestring (date)请求中提交的参考日期（必须与结清日期一致）。
due_datestring (date)请求中提交的目标清算日期。
event_conciliation_listarray所生成的 event_conciliation（分期对账事件）列表。event_conciliation_list 对象。

event_conciliation_list 对象​

字段类型描述
event_conciliation_keystring (UUID)分期对账事件（event_conciliation）的键值。
installment_keystring (UUID)受该对账事件影响的分期的键值。
expected_amountnumber分配引擎分配给该分期对账事件的金额。
discount_amountnumber分配给该分期对账事件的 total_discount 份额（present_amount），或该分期现值与所得份额之差（full_amortization）。
due_datestring (date)关联分期的到期日。
statusstring分期对账事件的初始状态。创建时恒为 pending_conciliation。
event_conciliation_typestringevent_conciliation 的类型。由本流程创建的分期对账事件恒为 extraordinary。

错误​

错误码HTTP含义
EVC100001400amortization_type 无效。请使用七个受支持取值之一。
EVC100002400对所有摊还类型而言，installment_list 为必填且不得为空。
EVC100003400使用 first_installments 时，number_of_installments 为必填。
EVC100004400所提供的某期分期不属于目标 security。
EVC000007404installment_list 中的某个整数与该 security 的任何 installment_number 都不匹配（InstallmentNumberNotFound）。
QIT000001400Schema 校验失败 — 例如提交了已移除的旧版 installment_key_list，或 installment_list 中某项不是 ≥ 1 的整数。
EVC100005400amount 不足以覆盖所有选中的分期（不适用于 early_amortization）。
EVC100006400total_discount 超过所选分期现值之和。
EVC100007400对 matured_installments 而言，所选分期必须全部已逾期。
EVC100008400该分期已存在一笔待处理的非常规摊还 — 请先取消后再创建新的。
EVC100013424Security API 不可用（Failed Dependency）。属临时性问题 — 恢复后重试。
EVC100015400early_amortization 要求 installment_list 中恰好有 1 期分期。
EVC100016400early_amortization 的目标分期不得已逾期。
EVC100017400在 early_amortization 中，amount 必须小于等于该分期的现值。
EVC100030400在 nominal_amount 中，所选分期必须全部为未来分期（在 reference_date 未逾期）。
EVC100031400在 nominal_amount 中，amount 必须小于等于所选分期的名义价值之和。
EVC100032400没有任何所选分期会获得正的 expected_amount — 不会创建该事件。
EVC100033400已分配的 expected_amount 之和与所声明的 amount 相差超过 R$ 0.01。
EVC100034400某一所选分期的 expected_amount 将为零 — 请只选择 amount 能覆盖的分期。
EVC100035400amount 超过所选分期现值之和（按现值定价的类型）。

完整的处理方案请参阅错误目录。

另请参阅​