解决多快递公司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	调用说明：<br>0 查询成功 或 提交成功<br>1 输入参数错误<br>2 查不到物流信息<br>3 单号不符合规则<br>4 快递公司编码不符合规则<br>5 快递查询渠道异常<br>6 auto时未查到单号对应的快递公司，请指定快递公司编码<br>7 单号与手机号不匹配<br>其他参数：接口调用失败<br>101 揽件<br>102 在途中<br>103 派送中<br>104 已签收 (完结状态)<br>105 用户拒签<br>106 疑难件<br>107 无效单 (完结状态) <br>108 超时单<br>109 签收失败<br>110 退回<br>111 转投<br>112 待签<br>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	状态信息：<br>101 揽件<br>102 在途中<br>103 派送中<br>104 已签收 (完结状态)<br>105 用户拒签<br>106 疑难件<br>107 无效单 (完结状态) <br>108 超时单<br>109 签收失败<br>110 退回<br>111 转投<br>112 待签
- sub_status	Number	（子状态）	（试营）子状态：<br>status=104 已签收 (完结状态)<br>- 10401 已签收<br>- 10402 从快递柜或者驿站取出<br>- 10403 退回签收
com_name	String	跨越速运	快递公司名称。
possible_exp_list	Object[]	[]	猜测列表。仅当com参数值为auto，且查询失败时才有返回值。返回结果参考如下：<br>"possible_exp_list": [<br> {<br> "com": "zhongtong",<br> "com_name": "中通快递"<br> },...<br> ]
- 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。如果你有任何问题或需要进一步的帮助，请随时访问万维易源的官方文档或联系技术支持。