SaaS 账务参考
本文介绍月付、年付 SaaS 接入中的账务资源、字段和处理规则。调用时，请使用当前应用 API 产品提供的接口路径、Schema 和 Scope。
当前能力状态
| 能力 | 状态 |
|---|---|
| 固定月付/年付 SaaS 套餐规则 | 已确定 |
| Application、API 调用权限、Webhook 申请 | 可通过开发者控制台申请 |
| Commerce Checkout Sandbox API Product | 已实现，可按 Application 签发后调用 |
| Production API Product | 尚未开放 |
| 储值余额、按量和超额扣费 | 当前商业方案不支持 |
资源与使用方式
| 资源 | 管理入口或方式 | 接入方用法 |
|---|---|---|
| Application、API 产品、API 调用权限、Webhook 订阅 | 开发者控制台 | 申请接入并获取对应版本的调用配置 |
| Product/Plan/PriceVersion、Order、SaaSSubscription | 客户工作区 | 展示和操作商业资源；第三方按已授权接口查询必要状态 |
| 支付、退款和支付状态 | 客户工作区 | 完成付款和退款；第三方按已授权接口查询脱敏状态 |
| ProductAccess、Entitlement | 产品权限快照尚未开放 | 按已发布合同处理事件；不使用内部回查接口 |
| 支付/退款证据 | 已授权的支付状态接口 | 查询脱敏状态和证据引用 |
| 卡片或钱包凭证 | 支付服务商 | 只通过 Hosted Checkout/Tokenization 处理 |
公共字段
以下字段只适用于未来签发的服务端 API/Event 契约，不是客户工作区跳转参数。当前商业页面入口不接受第三方拼接的业务 Query 参数。
| 字段 | 约束 |
|---|---|
application_code | 由 Application 和服务端会话确定，浏览器不能覆盖 |
plan_code / plan_version | 指向已批准套餐和不可变版本 |
price_version_ref | 指向不可变价格快照，不由浏览器生成 |
billing_interval | 仅允许 month 或 year |
amount_scaled / amount_scale | 整数金额和精度；由服务端价格快照产生 |
currency | 大写 ISO 4217 代码；由套餐/订单确定 |
operation_id | 不可猜测的异步操作标识，不是支付凭证 |
resource_version | 同一资源单调递增，用于事件乱序保护 |
金额按 amount_scaled × 10^-amount_scale 解释。例如 2900 和 2 表示 29.00。不要使用浮点数计算或传输金额。
调用要求
- 浏览器不持有服务端 OAuth Client Secret、Webhook Secret 或支付凭证。
- 第三方浏览器只打开平台客户工作区，不提交套餐、金额、币种、租户、Provider 或任意回跳 URL。
- Checkout 只由平台客户工作区的受控 BFF 创建，并使用稳定的
Idempotency-Key。 - 浏览器回跳不能证明支付成功；最终状态来自支付服务商验签通知或服务端对账。
- 支付成功后，分别确认订阅和 ProductAccess 状态，再开放产品功能。
- 当前商业方案只记录订阅支付和退款证据，不接受储值余额、按量或超额扣费字段。
发布后预期的 API Product 组成
| 能力组 | 典型操作 |
|---|---|
| Catalog | 查询当前 Application 可售的月付/年付套餐 |
| Subscription | 查询订阅摘要、计划取消、恢复或变更套餐 |
| Checkout | 创建 Hosted Checkout，查询异步 Operation |
| Billing | 查询脱敏支付/退款证据和状态 |
| Access | 产品权限快照待独立开放，当前不可调用 |
| Events | 订阅生命周期、支付/退款结果和访问状态事件 |
Sandbox Commerce Checkout 已提供产品目录、Checkout Session、Operation 查询、订阅查询、取消和套餐变更接口。金额使用平台已发布的 USD 价格。
- 写请求携带
Idempotency-Key。 - 取消或变更套餐时，使用当前
resource_version设置If-Match。 - 平台验证支付服务商回调，再通过已批准的 Webhook Subscription 投递脱敏支付／退款事件。第三方无需调用支付回调入口。
正式环境开放前，开发者控制台将提供 API Product 版本、Base URL、Audience、Scope、OpenAPI/AsyncAPI 和弃用说明。
登录后由用户与客户空间取得用户别名与当前空间；订阅按应用、环境、客户空间和 subscription ID 关联。用户上下文不授予付费或产品权限，详见多应用、用户与事件接入与产品权限快照。
安全返回字段
第三方前端只接收最小 ProductAccess 状态和服务端配置的平台入口。套餐展示字段、脱敏支付方式、短期 Checkout URL、Operation 状态和支付/退款证据摘要只进入平台客户工作区。任何前端都不得接收完整卡号、CVC、可扣款 Token、Provider Secret、Webhook Secret、内部路由或平台审计数据。