作为一家深受用户信赖的快递物流服务商，圆通快递通过开放平台为用户提供高效的快递物流查询API。圆通开放平台是将圆通下单、轨迹、工单及基础服多种服务接口通过开放平台赋能客户，帮助客户快速建立全面的物流解决方案的共联平台。平台现有接口文档统一管理，提供线上在线自测、联调的服务，提供自主发起接口上线申请及参数变更的模式； 完善每一个项目的系统对接流程，为客户提供了一个官方的开发平台，可以同时对接圆通的数个接口，提高对接效率， 减少人力投入节约对接成本，优化项目上线后的管理。
本篇博客将详细介绍该API的对接流程及相关技术细节，旨在帮助开发者快速完成接入工作，提升业务效率。
目录
一、API简介
1.物流查询API
圆通开放平台提供标准化的API接口，旨在为客户和平台实现高效的数据交互。通过物流查询服务，用户可轻松获取快件的实时物流信息，优化自身业务流程。
核心功能：
- 物流轨迹查询：通过物流单号获取快件的详细轨迹信息。
二、对接流程
1.注册用户
首先，需要在圆通开放平台完成注册。注册链接
2. 申请成为开发者
注册完成后，需前往“控制台-接口管理”完善开发者信息，获取开发者权限。该权限是后续接入API的必要前提，填写开发者信息时，确保联系方式准确无误。
3. 选择接口
申请成为开发者后，可获得完整接口的访问权限，包括物流轨迹查询、订单服务等功能模块。
可前往“控制台-接口管理”选择自己需要的接口，点击添加即可
4. 联调测试
在正式上线前，需在平台提供的测试环境中进行联调测试，确保接口能够稳定运行。
测试建议：
- 测试环境：使用开放平台提供的沙箱环境；
- 数据校验：对测试数据和接口返回值进行验证，确保符合文档要求；
- 沟通协调：保持与技术支持团队的良好沟通，快速解决问题。
5. 发布上线
完成联调测试后，与平台技术团队确认细节，进入正式环境。上线后，定期监控接口的调用状态，确保服务稳定运行。
三、签名机制详解
圆通API采用签名认证机制，旨在确保接口调用安全。以下是签名的生成规则及代码示例。
1. 加密步骤
生成签名规则的具体步骤如下：
| 序号 | 步骤 |
| 1 | 在POST时用“sign”字段进行签名验证。 |
| 2 | 将 param+method（方法）+v（版本） 拼接得到 data，将 data和 客户密钥 拼接。（通过 控制台——接口管理，添加自己所需接口，即可得到相应的测试地址、客户编码、客户密钥、方法和版本） |
| 3 | 假设data内容为： opentest， partnerId（客户密钥）为123456。 则要签名的内容为opentest123456，然后对opentest123456先进行MD5加密，然后转换为base64字符串。 即经过md5(16位byte)和base64后的内容就为 YLstCNa3x8ijQx16e/jqOA== |
2. 签名示例
代码示例：
/**
* 开放平台公共加密方法-使用commons-codec-1.11.jar进行md5加密,然后对数组进行base64编码
* @param data = param+method+v
* @param secret
* @return
*/
public static String encryptSignForOpen(String data, String secret) {
String sign;
try {
byte[] signByte = DigestUtils.md5(data + secret);
sign = Base64.encodeBase64String(signByte);
} catch (Throwable e) {
log.error("加密失败.e:{}.", e.toString());
sign = "ERROR";
}
return sign;
}
{
"timestamp": "1619515421751",
"param": "{\"NUMBER\":\"YT2600216627986\"}",
"sign": "rkXHJf8AZbhbZq4yEkQcsQ==",
"format": "JSON"
}3. 成功返回格式-json
- 字段类型：严格按照文档中定义的字段格式与大小传参；
- 必选字段：调用接口时，确保必选字段不漏传；
- 错误处理：若签名错误，请确认请求数据是否正确编码。
四、物流轨迹服务
1.【接口描述】
根据圆通物流运单号查询已有的快件物流信息，在物流信息里面会包含物流状态，如 【客户 **** 已签收】，物流信息保持与官网一致。
2.【传输方式】
本文档内描述的接口均采用HTTPS传输协议。客户方采用POST方式发送至本接口。
3.【报文结构】
| 参数名称 | 说明 |
| sign | 签名 |
| timestamp | 时间戳 |
| param | 传递的参数 |
| format | param格式(JSON/XML) |
4.【请求参数列表】
| 字段名 | 含义 | 类型 | 是否必填（Y：是，N：否） |
| Number | 圆通物流运单号，一次只能查询一个单号。 | String | Y |
5.【返回参数列表(JSON格式返回字段首字母小写)】
| 字段名 | 含义 | 类型 | 是否必填（Y：是，N：否） |
| waybill_No | 运单号 | String | Y |
| upload_Time | 走件产生时间 yyyy-MM-dd HH:mm:ss | String | Y |
| infoContent | 物流状态，固定为：GOT 已揽收;ARRIVAL 已收入;DEPARTURE 已发出;SENT_SCAN 派件;INBOUND 自提柜入柜;SIGNED 签收成功;FAILED 签收失败;FORWARDING 转寄;TMS_RETURN 退回; AIRSEND 航空发货;AIRPICK 航空提货 | String | Y |
| processInfo | 物流信息 | String | Y |
| city | 当前操作城市 | String | N |
| district | 当前操作区或者县 | String | N |
| weight | 重量，单位：kg | Number | N |
6.【请求格式-json】
{
"timestamp": "1619515421751",
"param": "{\"NUMBER\":\"YT2600216627986\"}",
"sign": "rkXHJf8AZbhbZq4yEkQcsQ==",
"format": "JSON"
}7.【成功返回格式-json】
[
{
"waybill_No": "YT2000000000000",
"upload_Time": "2023-04-24 20:37:33",
"infoContent": "GOT",
"processInfo": "您的快件被【浙江省金华市义乌市上溪镇】揽收，揽收人: xxx (xxxxxxxxx)",
"city": "金华市",
"district": "义乌市",
"weight": 0.68
},
{
"waybill_No": "YT2000000000000",
"upload_Time": "2023-04-24 23:12:15",
"infoContent": "DEPARTURE",
"processInfo": "您的快件离开【浙江省金华市义乌市上溪镇】，准备发往【义乌转运中心直营公司】",
"city": "金华市",
"district": "义乌市"
}
]
7.【查询为空返回格式-json】
{
"map": {
"YT2600205450611": []
},
"code": "1001",
"success": "true",
"message": "查询结果为空。"
}
五、圆通快递单号查询的其他方案
如果需要同时对接多家快递公司（如中通、圆通、韵达等），逐一对接可能增加开发复杂度。可以考虑集成类似**快递100API**的服务，它集成了超过2100家国内外快递公司，能够一次性完成多个快递公司的物流查询。
- 快递100API优势：
- 提供统一的接口规范；
- 支持多快递公司物流查询、电子面单等功能。
官方工具链接：快递100API调试工具
六、总结
圆通开放平台的快递物流查询API为开发者提供了灵活高效的解决方案，而通过对接多快递公司平台（如快递100API）能进一步提升开发效率。希望本篇博客能为你的开发过程提供帮助，祝你顺利完成项目！
扫一扫
3946
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
