#第三方物流API#顺丰快递API联调测试经验分享

顺丰快递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，调取下单接口，获取三个运单号，然后再调用取消下单接口进行销单即可

完成后，全部达到“待上线”的状态！

七、接口上线

除了“下订单”的接口外，其他直接点击上线；

八、上传电子面单

问对接客户要一张真实的面单上传上去即可，按照要求；

另外看下电子面单上传须知！

再点一下，确保传上去了

阅读须知！接下来就是耐心等待啦！