#第三方物流API#顺丰快递API联调测试经验分享原创
言鱼
40人赞赏了该文章
700次浏览
未经作者许可，禁止转载编辑于2024年04月15日 10:09:27
顺丰快递API联调测试经验分享
一、业务综述
很多商贸类企业，经常会收发快递，在使用ERP系统的时候想要单独二开对接，调取顺丰API进行下单，查询、取消下单等功能操作，上线前，都会进行联调测试；
本文章主要介绍下如何快速联调测试并成功顺丰API平台进行API接口的上线；
二、对接渠道
顺丰开放平台：顺丰开放平台 (sf-express.com)
三、查看快速对接文档
进入开放平台，就会弹框，可了解顺丰API的快速对接指南；
四、联调测试对接前指引
1、登录并验证用户或者企业
如何完成认证，看文档就行了，顺丰官方的文档还是比较亲民的；
2、创建应用
认证完成后，需要在“开发者对接”里进行创建应用，填写信息，系统会自动生成对应的
“顾客编码”、“沙箱校验码”、“生产校验码”；
3、妥善保存应用对应的信息（重要）
顾客编码
沙箱校验码（每次接口都要使用）
生产校验码
4、关联API
关联API，即您要对接的顺丰快递接口，该应用下可实现的功能等；
一般情况下，想要实现快递的需求；
需要使用“下订单接口”、“路由查询接口”，“订单筛单接口”、“取消下单接口”这四接口一般就足够了；
那么我们关联一下这四个API
关联后，是这样的；基本三个通用寄件的API和一个服务查询就完全够用了；
五、联调测试
联调测试前，可以查看每个接口的API文档，了解参数和传参要求，以便二开人员开发，当然联调其实很简单的，并且顺丰自带有联调的工具！连测试联调的代码都准备好了，直接套用即可；
联调的顺序是什么呢？当然是按照寄送快递的业务顺序进行；
一般是“下订单接口”、“路由查询接口”，“订单筛单接口”、“取消下单接口”
总之最先下单，最后取消下单准没错！
下面具体介绍下：（附上报文）
1、下订单接口
下订单请求报文
{
"cargoDetails":[
{
"count":2.365,
"unit":"个",
"weight":6.1,
"amount":100.5111,
"currency":"HKD",
"name":"护肤品1",
"sourceArea":"CHN"
}],
"contactInfoList": [
{
"address":"广东省深圳市南山区软件产业基地11栋",
"contact":"小曾",
"contactType":1,
"country":"CN",
"postCode":"580058",
"tel":"4006789888"
},
{
"address":"广东省广州市白云区湖北大厦",
"company":"顺丰速运",
"contact":"小邱",
"contactType":2,
"country":"CN",
"postCode":"580058",
"tel":"18688806057"
}],
"language":"zh_CN",
"orderId":"OrderNum20200618888"
}
下单接口返回报文：
{
"apiErrorMsg": "",
"apiResponseID": "00018EC2B55DB13FEB38420FD18EBA3F",
"apiResultCode": "A1000",
"apiResultData": "{\"success\":true,\"errorCode\":\"S0000\",\"errorMsg\":null,\"msgData\":{\"orderId\":\"OrderNum20200618888\",\"originCode\":\"755\",\"destCode\":\"020\",\"filterResult\":2,\"remark\":\"\",\"url\":null,\"paymentLink\":null,\"isUpstairs\":null,\"isSpecialWarehouseService\":null,\"mappingMark\":null,\"agentMailno\":null,\"returnExtraInfoList\":null,\"waybillNoInfoList\":[{\"waybillType\":1,\"waybillNo\":\"SF7444481560594\",\"boxNo\":null,\"length\":null,\"width\":null,\"height\":null,\"weight\":null,\"volume\":null}],\"routeLabelInfo\":[{\"code\":\"1000\",\"routeLabelData\":{\"waybillNo\":\"SF7444481560594\",\"sourceTransferCode\":\"755W\",\"sourceCityCode\":\"755\",\"sourceDeptCode\":\"755\",\"sourceTeamCode\":\"\",\"destCityCode\":\"020\",\"destDeptCode\":\"020NKAL\",\"destDeptCodeMapping\":\"020W\",\"destTeamCode\":\"012\",\"destTeamCodeMapping\":\"\",\"destTransferCode\":\"020RD\",\"destRouteLabel\":\"020RD-NKAL-012C\",\"proName\":\"\",\"cargoTypeCode\":\"C201\",\"limitTypeCode\":\"T4\",\"expressTypeCode\":\"B1\",\"codingMapping\":\"R215\",\"codingMappingOut\":\"\",\"xbFlag\":\"0\",\"printFlag\":\"000000000\",\"twoDimensionCode\":\"MMM={'k1':'020RD','k2':'020NKAL','k3':'012','k4':'T801','k5':'SF7444481560594','k6':'','k7':'83379e50'}\",\"proCode\":\"T 特快\",\"printIcon\":\"00000000\",\"abFlag\":\"\",\"destPortCode\":\"\",\"destCountry\":\"\",\"destPostCode\":\"\",\"goodsValueTotal\":\"\",\"currencySymbol\":\"\",\"cusBatch\":\"\",\"goodsNumber\":\"\",\"errMsg\":\"\",\"checkCode\":\"83379e50\",\"proIcon\":\"\",\"fileIcon\":\"\",\"fbaIcon\":\"\",\"icsmIcon\":\"\",\"destGisDeptCode\":\"020NKAL\",\"newIcon\":null,\"sendAreaCode\":null,\"destinationStationCode\":null,\"sxLabelDestCode\":null,\"sxDestTransferCode\":null,\"sxCompany\":null,\"newAbFlag\":null,\"destAddrKeyWord\":\"\",\"rongType\":null,\"waybillIconList\":null},\"message\":\"SF7444481560594:\"}],\"contactInfoList\":null,\"sendStartTm\":null,\"customerRights\":null,\"expressTypeId\":null}}"
}快递运单号
一眼就能看到“WaybillNO”参数值，那就是我们需要的下单返回的快递运单号！
SF7444481560594
orderid
OrderNum20200618888
2、路由查询接口
路由查询请求报文
{
"language": "zh-CN",
"trackingType": "1",
"trackingNumber": ["SF7444481560594"],
"methodType": "1"
}路由查询返回报文
{
"apiErrorMsg": "",
"apiResponseID": "00018EC2C6B3143FE1B7DD0040E3133F",
"apiResultCode": "A1000",
"apiResultData": "{\"success\":true,\"errorCode\":\"S0000\",\"errorMsg\":null,\"msgData\":{\"routeResps\":[{\"mailNo\":\"SF7444481560594\",\"routes\":[{\"acceptAddress\":\"深圳市\",\"acceptTime\":\"2024-04-09 20:13:05\",\"remark\":\"顺丰速运 已收取快件\",\"opCode\":\"50\"}]}]}}"
}3、订单筛单接口
订单筛单接口请求报文
[
{
"contactInfos":[
{
"address":"创业总部基地B07二楼",
"city":"天津市",
"contactType":2,
"country":"中国",
"county":"武清区",
"province":"天津市",
"tel":"19851401196"
},
{
"address":"测试订单，请不要接单",
"city":"成都市",
"contactType":1,
"country":"中国",
"county":"锦江区",
"province":"四川省"
}],
"filterType":1
}]订单筛单接口返回报文
{
"apiErrorMsg": "",
"apiResponseID": "00018EC2CB711C3FD50E7CCBBBF27C3F",
"apiResultCode": "A1000",
"apiResultData": "{\"success\":true,\"errorCode\":\"S0000\",\"errorMsg\":null,\"msgData\":[{\"orderId\":null,\"filterResult\":2,\"originCode\":\"028\",\"destCode\":\"022\",\"remark\":null}]}"
}4、取消下单接口
看接口文档发现，确认与取消，是一个接口，那么一定有参数区别，而我们没有修改；
再看传参说明
最终我找到了原因，是因为请求参数里“dealType”的值默认是“1确认”；
但是联调是自动确认的，因此要取消应该传“2取消”；
修正后重新传！
取消下单接口请求报文
{
"dealType": 2,
"orderId": "OrderNum20200618888",
"totalHeight": 29.98,
"totalLength": 29.98,
"totalVolume": 26946.035992000005,
"totalWeight": 2.09,
"totalWidth": 29.98,
"waybillNoInfoList": [{
"waybillNo": "SF7444481560594",
"waybillType": 1
}]
}取消下单接口返回报文
{
"apiErrorMsg": "",
"apiResponseID": "00018EC2ED70AC3FE1B5B3815123353F",
"apiResultCode": "A1000",
"apiResultData": "{\"success\":true,\"errorCode\":\"S0000\",\"errorMsg\":null,\"msgData\":{\"orderId\":\"OrderNum20200618888\",\"waybillNoInfoList\":[{\"waybillType\":1,\"waybillNo\":\"SF7444481560594\"}],\"resStatus\":2,\"extraInfoList\":null}}"
}六、查看API状态
发现怎么还在“测试中”，最后发现文档中有说明
每个接口要测三遍才能达到“待上线”的状态！
那么我们就按照前面的步骤三次即可；
自定义三个orderid，调取下单接口，获取三个运单号，然后再调用取消下单接口进行销单即可
完成后，全部达到“待上线”的状态！
七、接口上线
除了“下订单”的接口外，其他直接点击上线；
八、上传电子面单
问对接客户要一张真实的面单上传上去即可，按照要求；
另外看下电子面单上传须知！
再点一下，确保传上去了
阅读须知！接下来就是耐心等待啦！
推荐阅读