物流信息上传

商户通过此接口上传交易的物流配送信息，用于结算确认和订单追踪。接口接受物流公司编码和物流追踪单号，帮助完成交易的最终确认流程。

使用场景

物流信息上传主要用于以下场景：

• stc pay 结算要求：stc pay 支付方式的交易，必须上传物流信息才能触发结算
• 订单追踪：为交易关联物流信息，便于商户和客户追踪包裹状态
• 争议处理：提供物流凭证，用于处理交易争议和拒付申诉

stc pay 支付要求

使用 stc pay 支付方式时，必须满足以下条件才能上传物流信息并触发结算：

• 订单状态：交易必须已到终态（成功或失败，不能是处理中状态）
• 包裹状态：必须上传已签收的物流信息（包裹已送达客户）
• 交易类型：必须是实体商品交易，不支持虚拟商品或分期交易
• 结算影响：只有上传符合要求的物流信息后，Onerway 才会进行资金结算

其他支付方式可选择性接入此接口，用于订单追踪和管理。

上传时机

建议在以下时间点上传物流信息：

1. 包裹发货后：尽快上传物流单号，便于客户追踪
2. 包裹签收后（stc pay 必需）：确认客户签收后立即上传，触发结算流程
3. 交易完成后 30 天内：建议在交易完成后及时上传，避免影响对账和结算

物流公司编码列表

Onerway 支持全球超过 1,000 家物流公司。由于物流公司数量众多，我们提供 csv 文件供您下载查阅：

📥 下载物流公司编码列表

csv 文件包含以下信息：

• 物流公司编码（用于 carrierNo 参数）
• 物流公司名称

使用建议

建议下载并保存物流公司编码列表，便于集成开发和上传物流信息时参考使用。

请求参数

POST

Parameter	Type	Length	Required	Signed	Description
merchantNo	String	20	Yes	Yes	Merchant number assigned by Onerway upon registration, obtained from the Onerway merchant dashboard.
transactionId	String	20	Yes	Yes	Transaction ID generated by Onerway.
carrierNo	String	64	Yes	Yes	Carrier code identifying the logistics service provider. Download Carrier Code List
trackingNo	String	64	Yes	Yes	Logistics tracking number for package delivery tracking.
sign	String	/	Yes	No	Digital signature string for request verification and security. Please refer to Signature for signature generation method.

响应参数

名称	类型	描述
respCode	String	来自 Onerway 的响应码
respMsg	String	来自 Onerway 的响应信息
data	Object	响应数据。 请参阅对象 data

data

Parameter	Type	Length	Required	Signed	Description
transactionId	String	20	Yes	Yes	Transaction ID generated by Onerway.

API使用示例

POST

请求参数

{
  "merchantNo": "800058",                    // 商户号
  "transactionId": "1484408335541923840",    // Onerway交易订单号
  "carrierNo": "SF",                         // 物流公司编码（如顺丰：SF）
  "trackingNo": "SF1234567890",              // 物流追踪单号
  "sign": "a1b2c3d4e5f6789..."               // 签名字符串
}

响应 - 成功

{
  "respCode": "20000",                       // 成功响应码
  "respMsg": "Success",                      // 响应消息
  "data": {
    "transactionId": "1484408335541923840"   // 交易订单号
  }
}

响应 - 订单状态错误

{
  "respCode": "40001",                       // 错误响应码
  "respMsg": "Transaction not in final status", // 订单未到终态
  "data": null
}

常见错误场景

错误场景	解决方案
订单状态未到终态	等待交易完成（成功或失败）后再上传
交易不存在	检查 transactionId 是否正确
物流公司编码无效	下载并参考物流公司编码列表
重复上传	系统已记录该交易的物流信息，无需重复上传
签名验证失败	检查签名生成逻辑，参考签名文档

实施最佳实践

1. 订单状态验证：上传前检查订单是否已完成，避免因状态不符导致上传失败
2. 物流信息准确性：确保物流单号准确无误，错误的单号会影响客户追踪体验
3. 及时上传：包裹发货后尽快上传物流信息，提升客户满意度
4. 错误处理：实施重试机制，处理网络故障等临时错误
5. 记录日志：保存上传记录和响应结果，便于问题排查
6. stc pay 特殊要求：使用 stc pay 时，务必在包裹签收后上传，否则无法结算
7. 幂等性设计：支持重复上传同一物流信息，系统会自动去重

集成检查清单

上线前确认以下事项：

• 已获取正确的物流公司编码列表
• 实现了订单状态检查逻辑
• 测试了正常上传流程
• 测试了各种错误场景（订单不存在、状态错误等）
• 实现了错误处理和重试机制
• 添加了日志记录
• stc pay 交易已验证签收状态检查
• 在沙箱环境完成端到端测试