中通开放平台签名详解 - chocotan/ztosdk GitHub Wiki

本文已过期，请点击查看官方示例：http://58.40.16.125:9001/zopdoc

company_id和key是需要注册之后到个人中心中查看的，不是网点给你的账号密码

如果你使用的是JAVA8，推荐用我个人开发的https://github.com/chocotan/ztosdk，无需关注签名生成

旧的签名方式

本段适用于接口地址是 japi.zto.cn/gateway.do和japi.zto.cn/zto/api_utf8/traceInterface 这样的

如果你所调用的接口地址是 japi.zto.cn/traceInterfaceNewTraces 这样的，那么请跳过这段，直接看新的签名方式

这类旧的接口基本都有如下四个公共参数，且只支持Content-Type为application/x-www-form-urlencoded

  1. company_id
  2. data
  3. data_digest
  4. msg_type

其中，data字段为业务参数，中通开放平台文档里的业务参数都要转为json格式放入其中

data_digest=base64(md5(data+key))

注意这里的md5是应该返回一个byte数组，我们平常所说的md5基本是指32位的字符串，中通的接口用的不是这个，本wiki提供java、python、php、nodejs等语言的签名方式，可以点 https://git.io/vAVV6 查看

新的签名方式

中通开放平台改版之后更改了签名生成的方式，company_id和data_digest也放到http header中了： x-companyid和x-datadigest，http header的名称是不区分大小写的

新的签名方式和老的类似，只不过不再是data+key了，而是请求body+key

data_digest=base64(md5(请求body+key))

请求body是未经url编码的querystring

以获取单号（无秘钥）为例，该接口目前有3个业务入参：data、company_id、msg_type，那么请求body为

data={"partner":"test","id":"xfs101100111011","tradeid":"2701843","sender":{"id":"131*****010","name":"XXX","company":"XXXXX有限公司","mobile":"1391***5678","phone":"021-87***321","area":"310118","city":"上海,上海市,青浦区","address":"华新镇华志路XXX号","zipcode":"610012","email":"[email protected]","im":"1924656234","starttime":"2013-05-20 12:00:00","endtime":"2013-05-20 15:00:00"},"receiver":{"id":"130520142097","name":"XXX","company":"XXXX有限公司","mobile":"136*****321","phone":"010-222***89","area":"501022","city":"四川省,XXX,XXXX","address":"育德路XXX号","zipcode":"610012","email":"[email protected]","im":"yangyijia-abc"},"weight":"0.753","size":"12,23,11","quantity":"2","price":"126.50","freight":"10.00","premium":"0.50","pack_charges":"1.00","other_charges":"0.00","order_sum":"0.00","collect_moneytype":"CNY","collect_sum":"12.00","remark":"请勿摔货","order_type":"1"}&company_id=your_company_id&msg_type=submitAgent

以实名制-个人用户上传为例，该接口目前有1个业务入参：perUser，那么请求body为

perUser={"data":"{\"name\":\"姓名\",\"sex\":\"1\",\"typeOfId\":\"01\",\"numberOfId\":\"有效身份证件号码\",\"mo                 bileNumber\":\"联系电话\",\"province\":\"省\",\"city\":\"市\",\"county\":\"区县\",\"address\":\"详细地址\",\"typeOfUser\":\"1\"}","msg_type":"USER_UPLOAD"}

注意这里拼接的顺序一定要和http请求时的参数顺序一致，注意Content-Type也是application/x-www-form-urlencoded

测试环境和生产环境

  1. 有少数几个查询数据的接口如"快件跟踪"是只有生产环境的，测试环境无法调用，具体可以咨询中通相应的技术
  2. 测试环境一般都是需要用指定的companyid和key，具体看对应接口的文档

问题排查

提示"签名错误"

datadigest字段生成错误，原因有很多，以下是对接过程中遇到过一些原因

  1. key写错了，key不是网点给的，而是登陆后自己查看的
  2. application/x-www-form-urlencoded，顾名思义数据是要url编码的，部分语言的http工具会自动url编码
  3. 不要使用GBK编码，请使用UTF-8编码
  4. 不是用data字段加上key再生成签名，而是请求body加上key
  5. 签名生成时的拼接顺序要和http请求时候的参数顺序一致

请仔细阅读上面签名生成的部分，中通提供一个检测签名的页面 http://58.40.16.125:9001/digesttool/，在调试的时候左边的请求body里的数据尽量别带换行符

请保证所有可能涉及到字符编码的地方都是用的UTF-8，比如字符串的getBytes以及IO流相关的地方

提示"无权限访问"

  1. 是否用的你自己的companyid调用的测试环境，需要查看文档更换成测试环境专用的companyid和key
  2. 如果调用的是生产环境，需要到"控制台"里开启这个接口，开启后等待几分钟后就能调用了

提示"S11"错误码

S11是中通服务端未能查询到你所传的msg_type，在确定你所传的是正确的情况下，一般是以下原因：

中通部分接口不支持application/json的方式调用，本文档也不提供该方式的使用介绍，请更换为application/x-www-form-urlencoded