申购与赎回

理财 › 指南

申购、赎回、改续期方式 —— 三个写操作与它们的边界。

先试算，再申购


POST /v1/earn/subscription-quotes

起息日、到期日、预计利息。别自己按年化重算一遍 —— 起息日、day count、舍入位置全在服务端，而定期的 estimated_interest 与到期实收必须是同一个数（我方结算时会重算并断言相等）。自己算出来的会在某一天对不上，而那一天你已经把它显示给用户了。

不落行、不占额度。

产品	关键出参
活期	`value_at` 起息时刻 · `estimated_daily_interest` · `first_settle_date`
定期	`value_date` · `maturity_date` · `estimated_interest` · `total_at_maturity`

⚠ 活期的 disclaimer 恒为 estimate，别在界面上写成「到期可得」 ——活期利率随时会变（改利率 = 往利率历史插一行），这个数是「按今天的利率算」。定期的利率在下单那一刻快照进订单行，所以那个数就是到期实收。

⚠ 起息之前赎回不计息，而活期赎回是 LIFO（先扣没起息的那部分）——所以 value_at 要显示给用户。

申购


POST /v1/earn/subscriptions
{ "product_id": "…", "amount": "1000.00", "rollover_mode": "principal_interest" }

rollover_mode 三个合法值：none · principal · principal_interest。只对定期有意义，活期申购忽略它。

传别的值 → 400 invalid_request。不传 = 取产品的默认档。

⚠ 产品不可续期时，principal / principal_interest 会被静默改成 none ——

申购这一步不报错。而事后再调 PATCH .../rollover 设同样的值会被拒

（earn_rollover_not_supported）。两个端点在这一点上不一致。

所以：先看产品的 renewable，不可续期就别在界面上放那两个选项。

赎回


POST /v1/earn/redemptions

活期：随时，LIFO（先扣没起息的那部分）
定期：客户端不可提前赎回。这个端点对定期订单会拒

界面上定期持仓不要画「赎回」按钮 —— 画了再报错是一次白白的挫败。

改续期方式


PATCH /v1/earn/orders/{id}/rollover

只在到期之前可改。 已经进入结算或已结清就拒（state_invalid）。

持仓与订单详情


GET /v1/earn/positions/{id}   活期：含**其中未起息**
GET /v1/earn/orders/{id}      定期：年化 / 预计利息 / 到期日

⚠ 定期的年化取订单行的快照，不是产品当前值。 下单那一刻利率就快照进订单行了 —— 拿 GET /v1/earn/products/{id} 的 apr_bps 去渲染历史订单，运营一调价历史就全错，而两边都 200。

⚠ 活期的 pending_principal 是「其中未起息」，已经包含在 principal里，不是另加。它是客服工单量最大的那个问题唯一的答案 ——「我昨天存了钱，今天为什么没收益」。拿不到它你只能回「系统正在计算」。

活期赎回是 LIFO（先扣没起息的那部分），所以这个数同时也是「现在赎回不损失任何已计利息的额度」。

定期订单的状态机


pending_start ──► starting ──► accruing ──► pending_settle ──► settling ──► settled
                                                                              │
                                                                              └──► closed

状态	含义	能改续期方式
`pending_start`	已下单，还没到起息日	✓
`starting`	起息处理中	✓
`accruing`	计息中	✓
`pending_settle`	已到期，等结算	✓
`settling`	结算处理中	✗ `earn_rollover_locked`
`settled`	已结本息	✗
`closed`	已了结	✗

申购成功时返回的是 pending_start，不是 accruing ——定期有起息日，下单那一刻还没开始计息。

⚠ 别把这几档 default 成「处理中」。 认不出的状态原样显示。

我方这条线上的状态名有过拼写错误（pending_value / pending_start），

是「原样回显」当场把它们抓出来的 —— fallback 会把它们藏起来。

活期没有订单状态，只有持仓：active（持有中）/ closed（已清空）。

计息区间是左闭右开

value_date（含）→ maturity_date（不含）。

⚠ 按「含头含尾」算天数会多算一天的利息，而用户会拿你的数来对账。

标识符前缀

前缀	是什么
`ern_`	产品
`ers_`	活期申购/赎回的操作
`ero_`	定期订单

传参时带不带前缀都认（我方会剥掉）。