解决多快递公司API对接噩梦！全球物流查询统一接口封装实战

在物流和供应链管理领域，实时跟踪快递包裹的状态是一个关键需求。万维易源提供的“按次计费查询物流”API为开发者提供了一个高效、便捷的工具，可以通过简单的接口调用查询全球快递物流信息。本文将详细介绍如何使用该API，以及其核心功能和调用方法。

一、API概述

1. 接入点说明

- **计费模式**：本服务采用按次计费模式，即用户每次进行查询快递时都会产生相应的费用。
- **调用方式**：调用此服务时，接口会以阻塞式同步调用方式运行，这意味着在请求处理完成并收到响应之前，调用者将无法进行其他操作，需耐心等待结果返回。
- **更多帮助**：查看 [帮助文档](https://www.showapi.com/apiGateway/view/2650/8?tab=3)。

 2. 接口地址

```
https://route.showapi.com/2650-3?appKey={your_appKey}
```

请将 `{your_appKey}` 替换为你在万维易源平台申请的个人 `appKey`。

二、请求参数

以下是提交物流查询任务所需的请求参数：

表格

参数名称	类型	示例值	必须	描述
com	String	kuayue	是	快递公司字母简称，可以从“快递公司列表”或“快递公司查询”接口中查到该信息。如不知道快递公司名，可以使用auto代替，此时将自动识别快递单号。但请注意，auto是基于以往单号的特征进行人工智能分析，会有一定的误差，请谨慎使用。
nu	String	KY4000645091211	是	快递单号。
phone	String	2611	否	收件人或寄件人电话号码后四位。目前，查询【顺丰、跨越、中通】时该参数必填。注：隐私号需要完整后四位，例如：13xxxxx1-234，则需要传入的后四位为1234。
delivery_address	String	湖南省长沙市长沙县	否	最终收件地址，可用于反生成最终经纬度和预测收件时间，添加时最少包含省市区。
shipping_address	String	上海市	否	寄件地址，用于预测收件时间，添加时最少包含省市区。

三、返回参数

以下是接口返回的参数及其描述：

表格

参数名称	类型	示例值	描述
nu	String	KY4000645091211	快递单号。
logo	String	https://www.ky-express.com/src/assets/image/logo/logo-purple.svg	快递公司logo。
ret_code	Number	104	调用说明： 0 查询成功 或 提交成功 1 输入参数错误 2 查不到物流信息 3 单号不符合规则 4 快递公司编码不符合规则 5 快递查询渠道异常 6 auto时未查到单号对应的快递公司，请指定快递公司编码 7 单号与手机号不匹配 其他参数：接口调用失败 101 揽件 102 在途中 103 派送中 104 已签收 (完结状态) 105 用户拒签 106 疑难件 107 无效单 (完结状态)  108 超时单 109 签收失败 110 退回 111 转投 112 待签 113 邮件回收
com	String	kuayue	快递公司编码。
update_time	String	2025-02-07 15:50:14	更新时间。
tel	String	95324	快递公司联系方式。
showapi_inner_fee_num	Number	1	计费次数。
query_num	Number	1	当前单号查询的次数。
data	Object[]	（物流跟踪信息列表）	物流跟踪信息列表，即在途数据。
- time	String	2025-02-09 07:14:09	发生的时间。
- context	String	快件已在【长沙西龙点部】完成分拣，准备中转	跟踪信息。
- location	String	113.080555,28.246821	位置对应的坐标信息，坐标系是：GCJ-02。
- address	String	湖南省-长沙市-长沙县	位置信息。
- status	Number	102	状态信息： 101 揽件 102 在途中 103 派送中 104 已签收 (完结状态) 105 用户拒签 106 疑难件 107 无效单 (完结状态)  108 超时单 109 签收失败 110 退回 111 转投 112 待签
- sub_status	Number	（子状态）	（试营）子状态： status=104 已签收 (完结状态) - 10401 已签收 - 10402 从快递柜或者驿站取出 - 10403 退回签收
com_name	String	跨越速运	快递公司名称。
possible_exp_list	Object[]	[]	猜测列表。仅当com参数值为auto，且查询失败时才有返回值。返回结果参考如下： "possible_exp_list": [ { "com": "zhongtong", "com_name": "中通快递" },... ]
- com	String	shunfeng	快递公司编码。
- com_name	String	顺丰速运	快递公司名称。
msg	String	查询成功	返回说明。
delivery_time	String	（预计到达时间）	预计到达时间（格式：yyyy-MM-dd HH:mm）。该信息是基于历史数据分析的结果，不代表实际情况，仅供参考。

四、调用示例

以下是一个使用 `curl` 命令调用该接口的示例：

```bash
curl 'https://route.showapi.com/2650-3?appKey=your_appKey' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'com=kuayue' \
  -d 'phone=2611' \
  -d 'shipping_address=%E4%B8%8A%E6%B5%B7%E5%B8%82' \
  -d 'delivery_address=%E6%B9%96%E5%8D%97%E7%9C%81%E9%95%BF%E6%B2%99%E5%B8%82%E9%95%BF%E6%B2%99%E5%8E%BF' \
  -d 'nu=KY4000645091211'
```

请将 `your_appKey` 替换为你在万维易源平台申请的 `appKey`。

五、返回示例

以下是接口返回的JSON示例：

```json
{
  "showapi_res_error": "",
  "showapi_fee_num": 1,
  "showapi_res_code": 0,
  "showapi_res_id": "67aac910fb638c23e1791ccf",
  "showapi_res_body": {
    "delivery_time": "",
    "nu": "KY4000645091211",
    "logo": "https://www.ky-express.com/src/assets/image/logo/logo-purple.svg",
    "original_com": "kuayue",
    "com": "kuayue",
    "tel": "95324",
    "data": [
      {
        "time": "2025-02-10 15:20:14",
        "location": "113.080555,28.246821",
        "status": 104

六、获取 appKey

 要获取 appKey，请访问万维易源的控制台页面：

查看 appKey

七、总结

万维易源的“按次计费查询物流”API为开发者提供了一个高效、便捷的工具，可以通过简单的接口调用查询全球快递物流信息。该API支持全球范围内的快递物流查询，覆盖了包括顺丰、中通、跨越等在内的众多主流快递公司。通过简单的接口调用，用户可以获取快递包裹的实时状态，包括揽件、运输途中、派送中和已签收等详细信息希望本文能帮助你更好地了解和使用该API。如果你有任何问题或需要进一步的帮助，请随时访问万维易源的官方文档或联系技术支持。