分账 API 是什么
分账 API 是业务系统与分账系统之间交换订单、参与方、分账请求、查询结果和状态通知的接口集合。它的价值不是暴露一个金额计算函数，而是建立稳定的系统边界和可追踪的业务协议。
正式接入时，字段、签名方式、状态和错误码应以双方确认的接口文档为准。下面内容用于解释通用设计思路，不代表正式接口契约。
常见接口能力
能力 | 主要用途 |
|---|---|
订单接口 | 提交订单、金额、参与角色与业务明细 |
分账接口 | 发起处理并获得业务请求标识 |
查询接口 | 查询订单、分账明细和当前状态 |
退款或调整接口 | 关联原订单提交后续变化 |
Webhook | 向业务系统通知关键状态变化 |
请求示意
以下代码只展示字段关系，不是可直接调用的正式接口：
{
"requestId": "REQ-20260916-001",
"orderId": "ORDER-001",
"amount": 100000,
"participants": ["platform", "merchant"]
}金额单位、字段类型、参与方数据和签名内容都需要在正式文档中明确。
企业接入的五个阶段
业务梳理：确认订单边界、参与角色、规则、退款和结算口径。
技术评估：确定系统职责、网络方式、数据映射和状态同步策略。
接口开发：实现鉴权、签名、幂等、请求记录和错误处理。
联调测试：覆盖正常、重复、超时、退款和异常数据场景。
上线观察：分批切换业务，持续核对订单与处理结果。
不要从字段映射直接开始
如果订单、商户和费用口径尚未统一，接口字段会在联调中不断变化。先用流程图和样本订单确认业务，再固定请求与状态模型，接入成本通常更可控。
业务示例：平台系统发起分账
平台在订单达到约定业务状态后，使用唯一请求号提交订单和参与方信息。分账系统校验数据并返回已受理状态，随后生成结果。状态变化通过 Webhook 通知平台；如果通知未到达，平台可以使用同一业务标识主动查询。
平台因超时使用同一请求号重试时，系统返回已有处理结果，而不是再次创建一笔业务。发生退款后，平台提交原订单和退款明细，系统据此生成可追踪的调整记录。
接口稳定性的关键设计
幂等
调用方为每个业务动作生成稳定且唯一的请求标识。服务方根据该标识识别重复请求，并返回一致结果。
签名与时间窗口
双方按照正式约定对请求关键信息进行签名校验，并结合时间戳或其他机制处理重复与过期请求。具体算法和密钥管理应在接入方案中明确。
查询与通知互补
Webhook 适合及时同步状态，查询接口用于主动确认与异常恢复。调用方不应把一次通知成功作为唯一判断依据。
错误分类
区分参数错误、业务状态不允许、重复请求、系统暂时不可用等情况，明确哪些可以修正、哪些可以重试、哪些需要人工处理。
联调测试清单
相同请求号重复提交是否返回一致结果。
请求超时后查询能否确认真实处理状态。
通知失败、重复、乱序时业务系统能否正确处理。
金额、参与方或签名错误是否返回明确分类。
部分退款能否准确关联原订单与原分账明细。
测试环境与生产环境的配置和数据是否隔离。
常见问题
接入分账 API 需要改造订单系统吗
取决于现有系统能否提供稳定订单号、参与方、金额明细和状态。如果这些信息分散在多个系统，需要先设计数据汇总或映射方式。
Webhook 没收到怎么办
调用方应支持签名校验、重复通知和主动查询；服务方应提供可追踪的通知记录与重试约定。具体机制以正式接入方案为准。
为什么要同时保存请求号和订单号
订单号定位业务交易，请求号定位一次具体操作。一个订单可能经历分账、查询、退款等多个动作，分开管理更便于幂等和问题排查。