创建客户端与数据约定
Android 使用 MobileSdk.commerce(context, activityHost, apiBase, language)；iOS 使用 [[IRCommerceClient alloc] initWithBaseURL:apiBase language:language]。两端以 execute 调用 action，返回可取消的操作对象。成功回调为 JSON 字符串或 null，宿主解码后使用。
完整字段声明见接入包 contracts/commerce.d.ts。ID 使用字符串，金额为人民币分整数，时间为 ISO 8601。忽略服务端新增字段，不要依赖对象字段顺序。客户端固定创建时的账号/token，变更后重新创建。
浏览商品与门店
| action | 参数 |
|---|---|
context |
空对象；返回 clientId 和 manufacturerId |
availability、catalog |
vehicleId |
products |
vehicleId，可选 page、categoryId |
product |
vehicleId、id |
storeAvailability |
vehicleId |
stores |
vehicleId，可选 page、keyword、city、serviceType、longitude、latitude、radiusKm |
store |
vehicleId、id |
固定厂家 APP 可省略上述浏览参数的 vehicleId；官方跨厂家应用按当前车辆查询。门店坐标使用 GCJ-02。根据服务端 enabled、purchasable、unavailableReason 控制入口与购买按钮；不要仅依据本地厂家配置展示可购买状态。
地址、报价与下单
addresses、regions 使用空对象。saveAddress 接收 body，更新时附带 id；deleteAddress 使用 id 与 version。地址字段见公开声明。
先执行 quote，参数为 vehicleId 和 body={bindingVersion, skuId, quantity, addressId}。展示返回的价格、运费与支付方式，让用户确认。然后调用 purchaseCreate，其中 body 为：
{
"clientOrderKey": "<one UUID per purchase intent>",
"vehicleId": "<vehicle ID>",
"bindingVersion": 1,
"skuId": "<SKU ID>",
"quantity": 1,
"addressId": "<address ID>",
"addressVersion": 1,
"expectedQuote": {
"unitPriceCent": 100,
"shippingFeeCent": 0,
"paymentMethod": "ALIPAY"
}
}
以上为字段结构示意；所有 ID、版本、金额与支付方式来自当前服务端结果。clientOrderKey 是本次购买意图生成一次的 UUID。未知响应后的重试必须沿用同一购买意图，不能生成新 UUID 重复下单。
显式支付与恢复
- 检查 SDK 的
paymentAvailable与订单允许的动作；用户明确点击付款后调用purchasePay({id, paymentMethod})。 - SDK 获取订单和签名支付参数并调用供应商，宿主不接收
orderInfo。 - 返回订单以服务端资金状态为准。供应商回调“成功”不是最终到账凭证。
- 启动或回到前台调用
purchaseRecover({retry:false})，必要时sync({id})。恢复不能自动再次拉起支付。 - 用户确认当前订单后调用
purchaseAcknowledge({id})；SDK 会重新获取本人订单，未确认支付仍保留恢复标记。
purchaseIntent 只读当前购买意图。purchaseRecover 的 retry 默认 false，仅在用户明确重试创建订单时传 true；服务端确认 PAID 或 CLOSED 后可自动清理恢复记录。WAIT_PAY 且支付 UNCONFIRMED 时只做有限次数查单。
支付调用取消后可能仍需等待供应商回调或超时；等待原操作结束再发起新支付。取消、离开页面、关闭 App 都不会撤销已发生的付款。
订单与供应商配置
orders 可带 page、status、clientOrderKey，order、sync、cancel 使用 id，receive 额外使用 version。按钮按 allowedActions 展示，订单只属于当前账号且受应用范围限制。
iOS 使用接入包的 InfiniteRideMobile/Alipay 子模块，配置 paymentScheme 并转发全部支付 URL，详见 iOS 接入。真实支付还需要宿主应用与商户登记。iOS 仅支持 production，Android 支持 production/sandbox，使用平台返回的环境与支付参数。SIMULATED 仅在平台明确启用时可用，不能作为真实付款成功证据。