物品包裹上条形码内容用完整订单号,格式CODE128
电商系统要考虑用户单个订单买了很多东西,存入多个格子的情况
测试apikey=aac36fc7a9354e06adb9c3eef7fe8b56测试apisecret=989cd798a81d475c8ad6f3ab39347db0签名计算方法:参数按key名称顺序排序+apisecret,获得结果再用MD5加密。如:网点查询APIsign = MD5(apikey+city+district+nonce+apisecret);
注意:1、sign值小写,2、所用编码UTF-8
d0ef059237133cd0bda46fb4a3ad5390 = md5(aac36fc7a9354e06adb9c3eef7fe8b564a742e5037cd4054988ae6b7e8757420989cd798a81d475c8ad6f3ab39347db0)
http://api.usmartbox.com/ec/branch.json?apikey=aac36fc7a9354e06adb9c3eef7fe8b56&nonce=4a742e5037cd4054988ae6b7e8757420&city=&district=&sign=d0ef059237133cd0bda46fb4a3ad5390
登录管理后台,在“公司信息设置”中查看
登录管理后台,在“公司信息设置”中设置
智能柜系统提供的API由电商调用,支持HTTP、HTTPS GET、POST方式调用,参数格式为application/x-www-form-urlencoded
说明:电商端生成订单后通知智能柜服务器端URL :http://api.usmartbox.com/ec/ordercreate.json https://api.usmartbox.com/ec/ordercreate.json 智能柜系统提供的API都支持http、https两种方式调用请求参数:
cardfaceno和cardno用于用户刷卡取件,若不需要用户刷卡取件,这两项可以为空返回结果:
{"r" : "000000"}
返回状态码说明
说明:根据城市及区号查询下属网点
URL :http://api.usmartbox.com/ec/branch.json
请求参数:
返回结果:
{ "r": "000000", "list": [ { "city": "310100", "dtname": "浦东新区", "branchno": "00001-310115-0001", "lon": "121.533704", "name": "测试网点", "district": "310115", "lat": "31.231365" } ] }
返回字段说明
说明:根据城市及区号及网点编号查询下属柜子
URL :http://api.usmartbox.com/ec/box.json
{ "r": "000000", "list": [ { "city": "310100", "lon": "121.533704", "location": "测试柜子地址", "boxno": "00001-310115-0001-01", "district": "310115", "lat": "31.231365" } ] }
说明:根据城市及区号查询下属网点及柜子
URL :http://api.usmartbox.com/ec/branchbox.json
{ "r": "000000", "list": [ { "boxlist": [ { "city": "310100", "lon": "121.533704", "location": "测试柜子地址", "boxno": "00001-310115-0001-01", "district": "310115", "lat": "31.231365" } ], "city": "310100", "dtname": "浦东新区", "branchno": "00001-310115-0001", "lon": "121.533704", "name": "测试网点", "district": "310115", "lat": "31.231365" } ] }
http://api.usmartbox.com/ec/boxinfo.json
返回结果正常返回:
{ "city": "110100", "lon": "1", "location": "测试网点", "boxno": "00000-110101-0001-01", "district": "110101", "lat": "2" }
异常返回:
{ "r": "000023" }
http://api.usmartbox.com/ec/grid.json
{ "r": "000000", "list": [ { "gridno": "00001-310115-0001-01-0001", "status": 1, "showgridno": "01", "size": 1 }, { "gridno": "00001-310115-0001-01-00002", "status": 1, "showgridno": "02", "size": 1 } ] }
说明:查询所有配送员信息
URL :http://api.usmartbox.com/ec/courier.json
{ "r": "000000", "list": [ { "buname": "配送", "butype": 1, "phone": "13812345678", "userName": "配送员1" }, { "buname": "配送", "butype": 1, "phone": "13812345679", "userName": "配送员2" } ] }
http://api.usmartbox.com/ec/boxdetail.json
{ "r": "000000", "list": [ { "buname": "默认业务", "list": [ { "func": 1, "sizeList": [ { "size": 2, "idle": 10, "name": "中格" } ], "name": "普通" } ], "butype": 1 } ] }
http://api.usmartbox.com/ec/cun.json
返回结果
正常返回:
{ "r": "000000", "gridno": "00001-310115-0001-01-0004", "showgridno": "04", "opencode": "38737660", "seqid": "327957388306939904" }
异常返回:
{"r":"000024"}
http://api.usmartbox.com/ec/cunr.json
请求参数:
返回结果 正常返回:
{ "r": "000000", "list": [ { "gridno": "00001-310115-0001-01-0004", "showgridno": "04", "seqid": "327957388306939904", "location": "测试柜子地址", "starttime": "2018-06-23 23:45:33", "status": 1 } ] }
{"r":"120020"}
说明: 开柜成功后柜管理系统会调用用户取出时通知电商平台API通知电商系统URL :http://api.usmartbox.com/ec/qu.json请求参数:
{"r" : "000000","showgridno":"04"} {"r" : "000023"}
http://api.usmartbox.com/ec/qur.json
{"r":"000000","status":"2"}
{"r":"000023"}
电商端提供的API由智能柜端通过HTTP、HTTPS POST方式调用电商端接收成功后返回{"r" : "000000"},若没有返回{"r" : "000000"},智能柜系统会在3分钟后再次调用,若仍然没返回{"r" : "000000"},系统30分钟后再调用一次,之后不再调用。在后台配置回调地址如:http://api.dianshang.com/apihttps://api.dianshang.com/api
msgtype=cun
msgtype=qu请求参数:
柜管理系统会先查询本地数据,若未能查到则调用该API查询用户手机号及卡号,卡号用于用户刷卡取件,没有可以不返回msgtype=phone请求参数:
{ r : '000000', cardfaceno:'0000001', cardno:'0057947563', phone:'13812345678', }
发送取货密码后用户未能成功接收,或接收后删除了短信,系统后台可重发一条短信msgtype=resend请求参数:
配送员存入后,用户长时间(如12小时,具体时间可在智能柜管理系统配置)未取,通知电商系统,电商系统可短信或其他形势通知用户msgtype=timeout请求参数:
配送员存入或用户取出时超过两分钟未关门,通知电商系统,电商系统可短信或其他形势通知用户或运维人员msgtype=unclose请求参数:
柜子出现断网等异常情况,通知电商系统,电商系统可短信或其他形势通知运维人员msgtype=boxwarn请求参数:
短信由柜子系统发送时不调用此API,短信由电商系统发送时才调用此APImsgtype=vcode
目前有两种发卡方式,流程基本一致,推荐使用方式1
用户只绑定一张卡用于刷卡取件,该卡仅用于取件不用于充值
电商系统卡表必要字段
流程
订单信息导入时将卡面号,卡内号一起发给柜管理系统柜管理系统不做补卡、换卡、挂失操作
该卡同时用于充值及取件
上海的例子
数据来自国家统计局2017-上海
其他城市参考国家统计局2017-全部
若还需要其他API,联系柜管理系统开发商
电商对接API参考文档2.2.2
存取简易流程
注意事项
远程存取
条形码内容格式
物品包裹上条形码内容用完整订单号,格式CODE128
单订单多个格子
电商系统要考虑用户单个订单买了很多东西,存入多个格子的情况
sign计算
测试apikey=aac36fc7a9354e06adb9c3eef7fe8b56
测试apisecret=989cd798a81d475c8ad6f3ab39347db0
签名计算方法:参数按key名称顺序排序+apisecret,获得结果再用MD5加密。
如:网点查询API
sign = MD5(apikey+city+district+nonce+apisecret);
注意:1、sign值小写,2、所用编码UTF-8
demo
d0ef059237133cd0bda46fb4a3ad5390 = md5(aac36fc7a9354e06adb9c3eef7fe8b564a742e5037cd4054988ae6b7e8757420989cd798a81d475c8ad6f3ab39347db0)
get调用
post调用
获取apikey和apisecret
登录管理后台,在“公司信息设置”中查看
设置回调网址
登录管理后台,在“公司信息设置”中设置
智能柜系统端提供
智能柜系统提供的API由电商调用,支持HTTP、HTTPS GET、POST方式调用,参数格式为application/x-www-form-urlencoded
订单信息导入
说明:电商端生成订单后通知智能柜服务器端
URL :http://api.usmartbox.com/ec/ordercreate.json
https://api.usmartbox.com/ec/ordercreate.json
智能柜系统提供的API都支持http、https两种方式调用
请求参数:
cardfaceno和cardno用于用户刷卡取件,若不需要用户刷卡取件,这两项可以为空
返回结果:
返回状态码说明
网点查询
说明:根据城市及区号查询下属网点
URL :http://api.usmartbox.com/ec/branch.json
请求参数:
返回结果:
返回字段说明
返回状态码说明
柜子查询
说明:根据城市及区号及网点编号查询下属柜子
URL :http://api.usmartbox.com/ec/box.json
请求参数:
返回结果:
返回字段说明
返回状态码说明
网点柜子查询
说明:根据城市及区号查询下属网点及柜子
URL :http://api.usmartbox.com/ec/branchbox.json
请求参数:
返回结果:
返回字段说明
返回状态码说明
查询柜子信息
http://api.usmartbox.com/ec/boxinfo.json
请求参数:
返回结果
正常返回:
异常返回:
返回字段说明
返回状态码说明
查询所有格子状态
http://api.usmartbox.com/ec/grid.json
请求参数:
返回结果
正常返回:
异常返回:
返回字段说明
返回状态码说明
配送员信息查询
说明:查询所有配送员信息
URL :http://api.usmartbox.com/ec/courier.json
请求参数:
返回结果:
返回字段说明
返回状态码说明
查询配送员可用的格子功能及大小
http://api.usmartbox.com/ec/boxdetail.json
请求参数:
返回结果
正常返回:
异常返回:
返回字段说明
返回状态码说明
远程存
http://api.usmartbox.com/ec/cun.json
请求参数:
返回结果
正常返回:
异常返回:
返回字段说明
返回状态码说明
查询订单投递详细
http://api.usmartbox.com/ec/cunr.json
请求参数:
返回结果 正常返回:
异常返回:
返回字段说明
返回状态码说明
远程取
说明: 开柜成功后柜管理系统会调用用户取出时通知电商平台API通知电商系统
URL :http://api.usmartbox.com/ec/qu.json
请求参数:
返回结果:
返回字段说明
返回状态码说明
查询取件状态
http://api.usmartbox.com/ec/qur.json
请求参数:
返回结果 正常返回:
异常返回:
返回字段说明
返回状态码说明
电商端提供
电商端提供的API由智能柜端通过HTTP、HTTPS POST方式调用
电商端接收成功后返回{"r" : "000000"},若没有返回{"r" : "000000"},智能柜系统会在3分钟后再次调用,若仍然没返回{"r" : "000000"},系统30分钟后再调用一次,之后不再调用。
在后台配置回调地址如:
http://api.dianshang.com/api
https://api.dianshang.com/api
配送员存入时通知电商平台
msgtype=cun
请求参数:
返回结果:
用户取出时通知电商平台
msgtype=qu
请求参数:
返回结果:
根据订单号查询收件人手机号及卡号
柜管理系统会先查询本地数据,若未能查到则调用该API查询用户手机号及卡号,卡号用于用户刷卡取件,没有可以不返回
msgtype=phone
请求参数:
返回结果:
重发取货密码
发送取货密码后用户未能成功接收,或接收后删除了短信,系统后台可重发一条短信
msgtype=resend
请求参数:
返回结果:
超时未取通知
配送员存入后,用户长时间(如12小时,具体时间可在智能柜管理系统配置)未取,通知电商系统,电商系统可短信或其他形势通知用户
msgtype=timeout
请求参数:
返回结果:
未关门通知
配送员存入或用户取出时超过两分钟未关门,通知电商系统,电商系统可短信或其他形势通知用户或运维人员
msgtype=unclose
请求参数:
返回结果:
柜子异常通知
柜子出现断网等异常情况,通知电商系统,电商系统可短信或其他形势通知运维人员
msgtype=boxwarn
请求参数:
返回结果:
柜子管理员登录短信验证码
短信由柜子系统发送时不调用此API,短信由电商系统发送时才调用此API
msgtype=vcode
请求参数:
返回结果:
给用户发卡及刷卡取件
目前有两种发卡方式,流程基本一致,推荐使用方式1
方式1:卡号和原账号绑定
用户只绑定一张卡用于刷卡取件,该卡仅用于取件不用于充值
电商系统卡表必要字段
流程
订单信息导入时将卡面号,卡内号一起发给柜管理系统
柜管理系统不做补卡、换卡、挂失操作
方式2:卡号作为新账号使用
该卡同时用于充值及取件
电商系统卡表必要字段
流程
订单信息导入时将卡面号,卡内号一起发给柜管理系统
柜管理系统不做补卡、换卡、挂失操作
城市及区编号
上海的例子
数据来自国家统计局2017-上海
其他城市参考国家统计局2017-全部
其他
若还需要其他API,联系柜管理系统开发商