异步回调设置

1. 功能概述

为了解决下单处理时间较长（约 1-20 分钟）导致的响应超时问题，系统支持异步回调机制。用户在下单时设置异步标识，系统将自动在后台处理订单，并在处理完成后，主动将结果回传至用户指定的回调地址。

2. 接入流程

2.1 配置回调地址

用户需在后台系统的相应配置项中，设置接收回调结果的异步回调URL，并将状态设置为启用（如下图）。

2.2 下单传参

用户在发起下单 API 请求时，需要在请求参数中传递以下字段以开启异步模式：

• 参数名：async
• 参数值：10 (示例值，具体以最新API文档为准)
• 说明：当该参数为 10 时，系统将在后台异步处理该订单，并触发回调流程。

3. 回调机制说明

• 触发时机：下单请求成功后，系统将在 1 - 20 分钟 内完成后台处理并触发回调。
• 执行方式：系统将以 POST 请求的方式，向用户预设的回调地址主动发送回调数据。

3.1 回调数据结构说明

回调返回的结果 JSON 中通常包含以下核心业务数据：

• success (boolean): 业务处理是否成功（如：true）。
• err_code (int): 错误码（如：200）。
• msg (string): 描述信息（如："success"）。
• result (object): 包含完整的订单回传结果：
  • customer_order_num: 客户订单号
  • master_tracking_number: 主追踪号
  • tracking_number: 子包裹追踪号
  • merge_label / package_label: 对应的标签/PDF文件下载地址

3.2 接收结果日志参考

{
  "err_code": 200,
  "success": true,
  "msg": "success",
  "result": {
    "total": 31,
    "customer_order_num": "test-xxxx-0006",
    "master_tracking_number": "1Z9XXXXXXXXXXXXX",
    "merge_label": "https://files.xxx.com/1Z9XXXXXXXXXXXXX_xxxxxxxxxx_xxxxx.pdf",
    "order_num": "LSM9XXXXXXXXXXXXXXX",
    "packages_list": [
      {
        "tracking_number": "1Z9XXXXXXXXXXXXX",
        "is_main": "10",
        "seq": "test-xxxx-00060001",
        "box_num": "1",
        "package_label": "https://files.xxx.com.cn/2026/11/06/6aedxxxxxxxx_18b4f8a8.pdf"
      },
      {
        "tracking_number": "1Z9XXXXXXXXXXXXX",
        "is_main": "9",
        "seq": "test-xxxx-00060002",
        "box_num": "2",
        "package_label": "https://files.xxx.com.cn/2026/11/06/6aedxxxxxxxx_c2955a48.pdf"
      }
    ]
  }
}

4. 常见问题 (FAQ)

1. 回调失败怎么办？ 请检查您配置的回调地址是否具备公网访问权限，且支持 POST 请求。同时，建议您的接口增加幂等性校验（根据 customer_order_num 或 tracking_number 去重），以防止因网络抖动导致的数据重复接收。

2. 超过 20 分钟未收到回调？ 如果超过 20 分钟仍未收到回调，请排查本地防火墙是否拦截了回调 IP，或直接执行查询运单接口获取，如无法操作可直接联系客服进行协助处理。