德邦快递API联调测试经验分享
一、业务综述
很多商贸类企业,经常会收发快递,在使用ERP系统的时候想要单独二开对接,调取德邦快递API进行下单,查询等功能操作,上线前,都会进行联调测试;
本文章主要介绍下如何快速联调测试并成功在德邦快递API平台进行API接口的上线;
二、对接渠道
德邦API开放平台:德邦快递-新开放平台 (deppon.com)
三、查看对接文档
进入开放平台,在上方可查看对接文档,可了解德邦快递API的“接入指南”、“对接文档”、“各类接口文档”等;
四、API对接前指引
1、按照合作接入流程进行签约
德邦快递:合作接入流程
如何获取客户编码?
2、API快速入门
签约获取客户编号、并成功注册认证企业后,我们就可以登录平台;
根据API快速入门,进行操作:
3、登录,查看信息并妥善保存接口使用的信息(重要)
客户编码:
CompanyCode:
sign值:
appkey:
(以上四个参数是对接请求必录的参数,请一定要谨记!)
4、接口配置API
接口配置,即您要对接的德邦快递接口;
一般情况下,想要实现快递的需求;
需要使用“(新)下单服务接口”、“(新)标准轨迹查询”,“快递电子运单筛单接口”三个接口一般就够用啦;
那么我们关联一下这三个API,步骤如上:
关联后,如下图所示:
五、工具准备apifox
Apifox:
1、登录Apifox网页版
点击进入网页,直接使用web版即可;微信直接登录;
2、新建一个“个人项目”
联调测试前,可以查看每个接口的API文档,了解参数和传参要求,以便二开人员开发;
测试的示例代码,查看对接文档;或者在“查看对接进度”点击对应接口的“提交验证”即可查看;
详见下述:
联调的顺序是什么呢?当然是按照寄送快递的业务顺序进行;
一般是“(新)下单服务接口”、“(新)标准轨迹查询”,“快递电子运单筛单接口”;
下面具体介绍下:(附上报文)
六、联调接口
1、(新)下单服务接口API联调测试
在Apifox新建一个“根目录”的“post”连接;
录入接口提供的连接地址,如何获取?
路径:在API开放,点击对应接口的“报文校验”可以查看接口的信息;
根据接口文档的请求参数,在post页签里增加4个请求参数值;
注意:logisticID:是sign值+流水号,测试环境里流水号随意;
生成签名和时间戳,这里一会儿再Post里面需要使用;
(新)下单服务接口请求报文
{"companyCode":"公司编码" ,"customerCode":"客户编码", "logisticID":"sign值+流水号", "needTraceInfo":1, "orderType":"2", "transportType":"PACKAGE", "packageInfo":{"cargoName":"货物名","deliveryType":"4","totalNumber":2,"totalVolume":0.01,"totalWeight":10,"packageService":"纸"},"receiver":{"address":"徐泾镇明珠路1018号","city":"上海市","companyName":"德邦快递","county":"青浦区","mobile":"180****2531","name":"AAA","province":"上海","town":"徐泾镇"},"sender":{"address":"崧建路688弄","city":"上海市","companyName":"","county":"青浦区","mobile":"180****3451","name":"AAA","province":"上海","town":"重固镇"},"transportType":"PACKAGE","gmtCommit":"2019-05-20 18:44:19","payType":"1","isOut":"N"}
摘要验证失败原因: 1、平台上MD5+BASE64加密,MD5加密后的数据是全小写的; 2、下面是对1进行不同加密后的结果,可以自己比对下是否一致。(不一致说明加密方法有问题) MD5对1加密结果 --- c4ca4238a0b923820dcc509a6f75849b BASE64对1加密结果 --- MQ== BASE64(MD5())对1解密结果 --- YzRjYTQyMzhhMGI5MjM4MjBkY2M1MDlhNmY3NTg0OWI= 3、参数传递采用http post请求,请求消息头设置:("Content-Type","application/x-www-form-urlencoded;charset=utf-8"); 4、沙箱测试-同步联调接口选择接口测试输入请求报文生成时间戳和签名,看签名是否和本地生产上的签名是否一样; 5、对于params参数中有特殊字符的需要进行url转译。 6、检查调用时appkey是否和平台存在差异。
我们重新再“提交报文”中点击“生成签名和时间戳”再修改传参,发送试下
只要修改了“Parmas”参数的额请求报文,就必须重新再德邦平台的“提交报文”中点击“生成签名和时间戳”
然后根据签名和时间戳,修改“digest”和“timestamp”参数,重新发送,直到成功;
(重新生成签名和时间戳后,不要再德邦平台点击“测试”否则,这里就会提示渠道号或运单号重复)
(新)下单服务接口返回报文:
{ "result": "true", "reason": "成功", "mailNo": "DPK6450265433369", "logisticID": "HWJQ888666555889", "arrivedOrgSimpleName": "上海上海市", "resultCode": "1000", "uniquerRequestNumber": "25588128328665188" }
快递运单号
一眼就能看到“mailNo”参数值,那就是我们需要的下单返回的快递运单号!
DPK6450265433369
logisticID
HWJQ888666555889
2、新轨迹查询接口API联调测试
联调方式和上面一样,都是使用在“报文校验”中的“请求报文”,修改后
点击“生成签名和时间戳”再修改传参,到Apifox,新建一个post,重新接入对应的连接地址
然后,修改传参发送下即可;
新轨迹查询接口请求报文
{"mailNo":"DPK6450265433369"}
新轨迹查询接口返回报文
{ "result": "true", "reason": "", "resultCode": "1000", "responseParam": { "trace_list": [ { "city": "**市(测试)", "description": "正常签收,签收人类型:本人/同事/门卫 等", "site": "【***】营业部", "status": "SIGNED", "time": "2024-04-13 02:52:02" }, { "city": "**市(测试)", "description": "此货已滞留,与客户预约改日派送", "site": "【***】营业部", "status": "ERROR", "time": "2024-04-13 05:52:02" }, { "city": "**市(测试)", "description": "拒绝签收:原因", "site": "【***】营业部", "status": "FAILED", "time": "2024-04-13 02:52:02" }, { "city": "**市(测试)", "description": "派送中,派送人:**,派送人电话:***********", "site": "【***】营业部", "status": "SENT_SCAN", "time": "2024-04-12 23:52:02" }, { "city": "**市(测试)", "description": "货物已到达【***营业部】部门", "site": "【***】营业部", "status": "ARRIVAL", "time": "2024-04-12 20:52:02" }, { "city": "**市(测试)", "description": "运输中,离开【上海市转运中心】,下一站【***营业部】(出发到达对应多个)", "site": "****转运中心/营业部/枢纽中心", "status": "DEPARTURE", "time": "2024-04-12 17:52:02" }, { "city": "**市(测试)", "description": "您的订单已被收件员揽收,【上海市青浦区***营业部】库存中", "site": "上海市转运中心/营业部/枢纽中心", "status": "GOT", "time": "2024-04-12 15:52:02" } ], "tracking_number": "DPK6450265433369" }, "uniquerRequestNumber": "25588739066369245" }
.
3、快递电子运单筛单接口API联调测试
联调方式和上面一样,都是使用在“报文校验”中的“请求报文”,修改后
点击“生成签名和时间戳”,到Apifox,新建一个post,重新接入对应的连接地址
然后,修改传参发送下即可;
这里面有个问题,那就是示例报文中,官方没更新,要比照接口文档,只传必录的就行;
现需要修改的报文参数有:
customerCode:
orderSource:
logisticID:
使用之前的下单时使用的logisticID,orderSource就是companyCode
快递电子运单筛单接口请求报文
{"cargoName":"干果","customerCode":"客户编码","deliveryType":"3","logisticCompanyID":"DEPPON","orderSource":"公司编码","logisticID":"之前传的流水号","serviceType":"2","payType":"0","gmtCommit":"2012-11-27 18:44:19","receiver":{"address":"明珠路1018号","city":"上海市","county":"青浦区","mobile":"15800000000","name":"宝某某","phone":"","province":"上海"},"sender":{"address":"北京中路100号","city":"贵阳市","county":"花溪区","mobile":"15800000001","name":"淘某某","phone":"","province":"贵州省"},"smsNotify":"Y","toNetworkNo":"W01061502","totalNumber":500,"totalVolume":400,"totalWeight":300,"transportType":"PACKAGE","vistReceive":"Y"}
快递电子运单筛单接口返回报文
{ "logisticID": "HWJQ888666555889", "result": "true", "reason": "成功", "resultCode": "1000", "uniquerRequestNumber": "25589569818538331" }
六、查看API状态
每个接口只要用apifox调通一遍即可完成联调!
七、申请上线
全部联调玩点击申请上线即可
如果有面单的,需要上传面单审核,如果有对接人,可以提交无面单审核;
推荐阅读