开放平台对接常见问题
正式(调试)环境接口链接:https://apiopen.kuaidizs.cn/api/gateway
接口API : http://open.kuaidizs.cn/doc/_book/%E5%89%8D%E8%A8%80.html
注意:
开放平台分为单店铺和多店铺的模式,请注意下自己的店铺类型,请根据自己的类型对应查询文档。
快递助手软件简介
快递助手的主要功能是查询订单,打印,发货。开发商需要将订单推送给我们,只要是有新订单生成,或者订单信息修改等操作都要调用我们对应的创建订单和修改订单等接口,保证快递助手的订单信息与后台同步。查询订单之后,用户可以选择订单进行打印,打印完成之后页面将会自动生成运单号,点击发货,快递助手调用开发商提供的发货接口,将此次打印的运单号作为发货接口的入参传递到开发商,完成发货操作。
必读:
a.单店铺模式下,由于只有一个用户,所以appkey和appScret就唯一代表一个用户。
假设appkey=aaaa appScret=bbbbb
b.多店铺模式下,appkey唯一代表一个应用(一个商家平台),没有办法具体到每个用户,所以我们采取 appKey_shopName_token(这里的shopName也需要唯一,商家自定义shopName的值,第一次登陆相当于注册)的方式唯一对应到对应应用下具体的某个用户,所以开发商需要维护好每个用户的token和mallUserId的关系(因为多店铺模式推送订单 公共参数 都需要传mallUserId),其中 token 是开发商自己生成分配给用户的,唯一标识一个用户。由于第一次店铺登录时我们会回调user.push 接口,回调该接口时我们会推送该店铺的mallUserId给你们。
所以在对接之前需要先开发user.push和user.login接口,详情见文档 回调接口 。
注意:
只会在第一次登录时回调接口推送mallUserId,需要自行管理维护好对应用户的mallUserId和token的关系,如果丢失,没办法重新推送。不过可以联系我们帮忙查询数据。
appKey_shopName_token这种格式只在登录时需要在页面的appkey处按这种格式填写,其他接口的appkey还是按照之前分配给应用的appkey.
假设appkey=aaaa shop_name=测试店铺 token=ccc
appScret=bbbbb
开发商接入准备:
a.单店铺模式:
发货接口是开发商开发给我们调用,其余接口就是开发商调用我们的接口推送和修改订单或者商品信息。
a.拿到我们分配的单店铺账号即可开发对应接口
b.无需实现user.push店铺信息推送接口(多店铺模式专用)
c.无需实现user.login店铺登录接口(多店铺模式专用)
d.只需按需求正常开发推送或修改订单,商品等接口即可
e.发货接口也是按选择开发,供应商可以支持后台发货,或者支持在快递助手软件发货(前提是提供发货接口)。
f.如果开发了发货接口,需要提供接口链接给我们配置,配置完成之后就可以在快手助手使用发货功能
g.接口开发完成,测试完成之后,即可登录,使用快递助手软件。
b.多店铺模式:
发货接口,user.push,user.login,是开发商开发给我们调用,其余接口就是开发商调用我们的接口推送和修改订单或者商品信息。
a.拿到我们分配的多店铺账号即可开发对应接口
b.需要实现user.push 店铺信息推送接口,只在用户第一次登录的时候调用,主要是用来给我们校验用户信息,推送mallUserId给开发商,供应商相应的需要维护每个用户的token与mallUserId的关系。
c.需要实现user.login店铺登录接口,除了第一次登录之外,接下来每次登录都会调用,校验token来保证用户的正确性
d.需要先将user.push,user.login接口开发完成,然后将接口链接提供给我们配置好,才可以进行登录操作,登录参数请参照常见问题中“登录时出现账号密码登录不正确或者appkey填写不完整”的解答。
e.只需按需求正常开发推送或修改订单,商品等接口即可,相应接口开发完成并且第一次登录成功之后,就可以获取到mallUserId进行订单推送等接口的测试。
f.发货接口也是按选择开发,供应商可以支持后台发货,或者支持在快递助手软件发货(前提是提供发货接口)。
g.如果开发了发货接口,需要提供给我们配置(也就是之前的接口链接,配置过就不要重新配置),配置完成之后就可以在快手助手使用发货功能
常见问题
1.登录时出现账号密码登录不正确或者appkey填写不完整
开放平台分为单店铺和多店铺的模式,请注意下自己的店铺类型,根据不同店铺类型选择不同的登录方式。
单店铺类型:
使用分配给你们的appkey和appScret直接登录就好。
多店铺类型:
appkey: 采取appKey_shopName_token格式填写
appSecret:将appSecret填入即可
多店铺类型店铺登录请一定注意自己的appkey填写格式,一般登录错误都是格式不对引起的,并且请注意shopName或者token不要采取‘_’方式拼接,因为会与我们的拼接方式有冲突。
2.订单推送接口测试用例(这里以测试接口链接测试账号调试)
建议使用postman进行接口调试
所有请求均为POST请求,不要用get请求,以本文档为主!
Content-Type:application/x-www-form-urlencoded
Boby:x-www-form-urlencoded
postman测试接口输入的参数不要有双引号
正确:appKey : qishantest
错误: ”appKey ”: ”qishantest”
单店铺模式下:
参数:
appKey:qishantest
method:trade.create
timestamp:1584332050
v:1.0
appParam:{"buyerMessage":"买家信息","buyerNick":"默读","created":1584447014455,"discountFee":"10.0","modified":1584447014455,"orders":[{"created":1584447014456,"discountFee":"0.0","itemId":"115551","modified":1584447014456,"number":2,"orderId":"87348787487113475","outerId": "hjh11","outerSkuId":"hjsh99","payment":"20.0","picPath":"12133","price":"10.0","refundStatus":"REFUND_ING","saleProps":[{"enableStatus":1, "key":"颜色","name":"test","value":"白色"}],"sendTime":1584447014456,"skuId":"115550011","skuUrl":"","status":"ORDER_PAID","title":"美丽", "totalFee":"20.0"}],"payTime":1584447014455,"payment":"20.0","postFee":"20.0","receiverAddress":"11111","receiverCity":"长沙市","receiverCounty":"雨花区","receiverMobile":"17666666666", "receiverName":"收件人是美女","receiverPhone":"17666666666","receiverProvince":"湖南省","receiverZip": "10000","refundStatus":"REFUND_ING","sellerMemo":"卖家备注","sendTime":1584447014455,"status":"ORDER_PAID","tid":"38478378374873840" ,"totalFee":"20.0", "totalNum":10}
sign:DEE1DF6B6E4F723B1A610E68BD6BB64F
签名规则:
步骤一:非空的系统参数和应用参数根据参数名按acsii字符集排序规则排序(注意是非空!)得到值:
appKey=qishantest&appParam={\"buyerMessage\":\"买家信息\",\"buyerNick\":\"默读\",\"created\":1584447014455,\"discountFee\":\"10.0\",\"modified\":1584447014455,\"orders\":[{\"created\":1584447014456,\"discountFee\":\"0.0\",\"itemId\":\"115551\",\"modified\":1584447014456,\"number\":2,\"orderId\":\"87348787487113475\",\"outerId\":\"hjh11\",\"outerSkuId\":\"hjsh99\",\"payment\":\"20.0\",\"picPath\":\"12133\",\"price\":\"10.0\",\"refundStatus\":\"REFUND_ING\",\"saleProps\":[{\"enableStatus\":1,\"key\":\"颜色\",\"name\":\"test\",\"value\":\"白色\"}],\"sendTime\":1584447014456,\"skuId\":\"115550011\",\"skuUrl\":\"\",\"status\":\"ORDER_PAID\",\"title\":\"美丽\",\"totalFee\":\"20.0\"}],\"payTime\":1584447014455,\"payment\":\"20.0\",\"postFee\":\"20.0\",\"receiverAddress\":\"11111\",\"receiverCity\":\"长沙市\",\"receiverCounty\":\"雨花区\",\"receiverMobile\":\"17666666666\",\"receiverName\":\"收件人是美女\",\"receiverPhone\":\"17666666666\",\"receiverProvince\":\"湖南省\",\"receiverZip\":\"10000\",\"refundStatus\":\"REFUND_ING\",\"sellerMemo\":\"卖家备注\",\"sendTime\":1584447014455,\"status\":\"ORDER_PAID\",\"tid\":\"38478378374873840\",\"totalFee\":\"20.0\",\"totalNum\":10}&method=trade.create×tamp=1584332050&v=1.0
步骤二:在第一步取到的值的基础上,在首尾都拼接上appScret的值(假设appScret=96220332)
96220332appKey=qishantest&appParam={\"buyerMessage\":\"买家信息\",\"buyerNick\":\"默读\",\"created\":1584447014455,\"discountFee\":\"10.0\",\"modified\":1584447014455,\"orders\":[{\"created\":1584447014456,\"discountFee\":\"0.0\",\"itemId\":\"115551\",\"modified\":1584447014456,\"number\":2,\"orderId\":\"87348787487113475\",\"outerId\":\"hjh11\",\"outerSkuId\":\"hjsh99\",\"payment\":\"20.0\",\"picPath\":\"12133\",\"price\":\"10.0\",\"refundStatus\":\"REFUND_ING\",\"saleProps\":[{\"enableStatus\":1,\"key\":\"颜色\",\"name\":\"test\",\"value\":\"白色\"}],\"sendTime\":1584447014456,\"skuId\":\"115550011\",\"skuUrl\":\"\",\"status\":\"ORDER_PAID\",\"title\":\"美丽\",\"totalFee\":\"20.0\"}],\"payTime\":1584447014455,\"payment\":\"20.0\",\"postFee\":\"20.0\",\"receiverAddress\":\"11111\",\"receiverCity\":\"长沙市\",\"receiverCounty\":\"雨花区\",\"receiverMobile\":\"17666666666\",\"receiverName\":\"收件人是美女\",\"receiverPhone\":\"17666666666\",\"receiverProvince\":\"湖南省\",\"receiverZip\":\"10000\",\"refundStatus\":\"REFUND_ING\",\"sellerMemo\":\"卖家备注\",\"sendTime\":1584447014455,\"status\":\"ORDER_PAID\",\"tid\":\"38478378374873840\",\"totalFee\":\"20.0\",\"totalNum\":10}&method=trade.create×tamp=1584332050&v=1.096220332
步骤三:在第二步取到的值的基础上,做大写32位MD5加密得到DEE1DF6B6E4F723B1A610E68BD6BB64F
多店铺模式接口调用与单店铺模式基本一致,只是系统参数多了一个mallUserId(确定是推送哪个用户的订单)mallUserId也参与签名规则,模拟单店铺模式调用即可。
3.推送订单参数异常问题
推送订单时出现该应用不存在或者参数异常等情况,请先对找第二点的案例以及API文档仔细检查一下传递参数的格式,确保无误,一般这种报错都是参数格式问题引起的,请先自查。
a.postman测试接口输入的参数不要有双引号
b.确保系统参数和应用参数的格式
c.所有请求均为POST请求,不要用get请求
Content-Type:application/x-www-form-urlencoded
Boby:x-www-form-urlencoded
postman测试接口输入的参数不要有双引号
正确:appKey : qishantest
错误: ”appKey ”: ”qishantest”
4.多店铺模式免登链接(单店铺模式不可用)
5.订单信息格式规范须知
a.订单号和订单号里的子订单号不能重复,订单号必须大于8位
b.注意接口文档中不能为空的字段必须传,字符串也不能为空字符串
c.订单号不要拼接“:”这种特殊字符,否则会报错
6.发货接口补充
三种发货方式可选:
a.支持快递助手发货:只需开发这个发货接口(快递助手调用开发商接口),在快递助手发货之后,同步订单的状态和运单号到开发商后台
b.不支持快递助手发货,只在自己后台发货,只需要提供下面的接口(开发商调用快递助手的接口),同步后台订单的状态和运单号到快递助手
c.既支持快递助手发货,又支持后台发货,以上两个都需要完成,即要开发一个给快递助手调用的接口,也需要开发调用快递助手的接口,实现订单状态同步。