上传运单

PATCH {BASE_URL}/api/v1/open/charges/{orderIdentifier}/shipping

用于在订单支付后上传或更正物流。orderIdentifier 支持以下两种原单标识：

• 开放 API 建单返回的原单 UUID（order.id）；
• 平台支付单号 order_no，格式如 PAY-20260917-ABC123（大小写不敏感）。

支付单号只会在当前 API 密钥所属商户、开放 API 原单范围内解析。不能使用 merchant_order_id、charge_code、其他业务单号或 USDT 内部子单 ID。

可写订单

• 普通订单状态为 PAID、PARTIALLY_REFUNDED 或 REFUNDED。
• 转 USDT 成功时仍传原单 UUID 或原单支付单号；物流实际保存到唯一的已支付 USDT 子单，响应、后续查单和 Webhook 仍返回原单 UUID。
• 非开放 API 建单、跨商户订单、未支付订单或异常父子关系会被拒绝。

请求头

头	必填	说明
Authorization	是	Bearer + 完整 API 密钥
Content-Type	是	application/json

请求体最大 16 KiB，且只接受以下字段：

字段	必填	最大长度	说明
shipping_carrier	是	64	物流公司，去除首尾空白后不能为空
tracking_no	是	128	追踪单号，去除空白并保留前导零；不能清空
shipping_note	否	1000	省略则保留原备注；null 或空白字符串会清空备注

{
  "shipping_carrier": "DHL",
  "tracking_no": "00123456789",
  "shipping_note": "请放前台"
}

成功响应 200

{
  "success": true,
  "changed": true,
  "order": {
    "id": "<规范原单 UUID；即使请求使用支付单号也返回 UUID>",
    "shipping": {
      "shipping_carrier": "DHL",
      "tracking_no": "00123456789",
      "shipping_note": "请放前台",
      "shipped_at": "2026-09-17T02:00:00.000Z"
    }
  }
}

相同内容重试返回 changed=false，且保留首次 shipped_at。更正物流返回 changed=true，首次发货时间仍不改变。此接口不使用 Idempotency-Key；若先写 A、再更正为 B、随后重放旧请求 A，A 会再次覆盖 B，因此调用方应丢弃过期重试。

保存成功后，可按商户通知配置触发 SHIPPED 或 LOGISTICS_UPDATED Webhook、客户邮件及适用支付网关的物流同步。这些动作是提交后的尽力执行；接口成功只证明物流已保存，不承诺外部系统已经收到。

错误

写入失败响应为 { "error": "...", "code": "..." }。

HTTP	code	场景
400	invalid_request	订单标识（UUID / PAY-...）、JSON、未知字段或字段内容无效
401	unauthorized	缺少或无效 API 密钥
404	order_not_found / child_order_id	UUID/支付单号对应订单不可见、非开放 API 原单，或传了内部子单 ID
409	order_state_conflict / conversion_conflict / write_busy	状态或父子关系冲突，或并发写入繁忙
413	payload_too_large	请求体超过 16 KiB
422	order_not_paid / shipping_conflict	订单未支付，或物流与本商户其他客户冲突
429	rate_limited	IP 或商户物流配额耗尽；响应含 Retry-After 秒数
500	internal_error	内部错误

限流约为 IP 120 次/分钟、商户物流写入 60 次/分钟。当前计数保存在单个应用实例内，多实例之间不共享；客户端仍应遵守 Retry-After 并使用退避重试。

保存后可用查询订单回读最终物流。USDT 映射见 USDT 结算说明，通知语义见 支付结果回调。