电商对接API参考文档2.2.2

存取简易流程

存取流程

注意事项

远程存取

  1. 远程存超时时间为30秒，开发时务必注意，该API调用后最长30秒后才会返回
  2. 远程存时，系统返回超时或其他情况(如自身手机网络异常没有获得返回值)导致无法判断是否已存入成功时，可调用查询订单投递详细查看是否已经存入，若已经存入配送员可继续存其他包裹，若没存入配送员需重新存入该包裹
  3. 远程取超时时间为30秒，开发时务必注意，该API调用后最长30秒后才会返回
  4. 远程取时，系统返回超时或其他情况(如自身手机网络异常没有获得返回值)导致无法判断是否已取出成功时，可调用查询取件状态查看是否成功取出

条形码内容格式

物品包裹上条形码内容用完整订单号，格式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)

md5

get调用

http://api.usmartbox.com/ec/branch.json?apikey=aac36fc7a9354e06adb9c3eef7fe8b56&nonce=4a742e5037cd4054988ae6b7e8757420&city=&district=&sign=d0ef059237133cd0bda46fb4a3ad5390

post调用

demo

获取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两种方式调用
请求参数:

keyname 必选 说明
apikey true key
cardfaceno false 卡面号(印刷在卡表面的编号)
cardno false 卡内芯片号(取IC卡号前10位)
nonce true 32位随机数
orderid true 订单号(条形码上内容)
phone true 收件人手机号
sign true 用于校验

cardfaceno和cardno用于用户刷卡取件，若不需要用户刷卡取件，这两项可以为空
返回结果： 

{"r" : "000000"}

返回状态码说明

状态码 说明
000000 操作成功
999999 系统内部异常
000021 订单号重复
000023 签名串错误
000024 apikey异常

网点查询

说明：根据城市及区号查询下属网点

URL ：http://api.usmartbox.com/ec/branch.json

请求参数:

keyname 必选 说明
apikey true key
city false 城市编号 参考城市及区编号
district false 区号编号
nonce true 32位随机数
sign true 用于校验

返回结果：

{
    "r": "000000",
    "list": [
        {
            "city": "310100",
            "dtname": "浦东新区",
            "branchno": "00001-310115-0001",
            "lon": "121.533704",
            "name": "测试网点",
            "district": "310115",
            "lat": "31.231365"
        }
    ]
}

返回字段说明

返回值字段 字段类型 字段说明
r string 返回状态码
list arr 数组
city string 城市编号
dtname string 区名
branchno string 网点编号
lon string 网点经度
name string 网点名称
district string 区编号
lat string 网点纬度

返回状态码说明

状态码 说明
000000 操作成功
999999 系统内部异常
000023 签名串错误
000024 apikey异常

柜子查询

说明：根据城市及区号及网点编号查询下属柜子

URL ：http://api.usmartbox.com/ec/box.json

请求参数:

keyname 必选 说明
apikey true key
branchno false 网点编号
city false 城市编号 参考城市及区编号
district false 区号编号
nonce true 32位随机数
sign true 用于校验

返回结果：

{
    "r": "000000",
    "list": [
        {
            "city": "310100",
            "lon": "121.533704",
            "location": "测试柜子地址",
            "boxno": "00001-310115-0001-01",
            "district": "310115",
            "lat": "31.231365"
        }
    ]
}

返回字段说明

返回值字段 字段类型 字段说明
r string 返回状态码
list arr 数组
city string 城市编号
lon string 柜子经度
location string 柜子地址
boxno string 柜子编号
district string 区编号
lat string 柜子纬度

返回状态码说明

状态码 说明
000000 操作成功
999999 系统内部异常
000023 签名串错误
000024 apikey异常

网点柜子查询

说明：根据城市及区号查询下属网点及柜子

URL ：http://api.usmartbox.com/ec/branchbox.json

请求参数:

keyname 必选 说明
apikey true key
city false 城市编号 参考城市及区编号
district false 区号编号
nonce true 32位随机数
sign true 用于校验

返回结果：

{
    "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"
        }
    ]
}

返回字段说明

返回值字段 字段类型 字段说明
r string 返回状态码
list arr 网点数组
city string 城市编号
dtname string 区名
branchno string 网点编号
name string 网点名称
lat string 网点纬度
lon string 网点经度
district string 区编号
boxlist arr 柜子数组
boxno string 柜子编号
lat string 柜子纬度
lon string 柜子经度
location string 柜子地址

返回状态码说明

状态码 说明
000000 操作成功
999999 系统内部异常
000023 签名串错误
000024 apikey异常

查询柜子信息

http://api.usmartbox.com/ec/boxinfo.json

请求参数:

参数名 说明 参数值举例
apikey key aac36fc7a9354e06adb9c3eef7fe8b56
boxno 柜子编号 00000-110101-0001-01
nonce 随机数 23be03cbccaf4d7a8fd1e8d704d7b81b
sign 签名，用于校验 32位

返回结果
正常返回：

{
  "city": "110100",
  "lon": "1",
  "location": "测试网点",
  "boxno": "00000-110101-0001-01",
  "district": "110101",
  "lat": "2"
}

异常返回：

{
    "r": "000023"
}

返回字段说明

返回值字段 字段类型 字段说明
r string 返回状态码
city string 城市编号
district string 区编号
boxno string 柜子编号
lat string 柜子纬度
lon string 柜子经度
location string 柜子地址

返回状态码说明

状态码 说明
000000 操作成功
999999 系统内部异常
000023 签名串错误
000024 apikey异常

查询所有格子状态

http://api.usmartbox.com/ec/grid.json

请求参数:

参数名 说明 参数值举例
apikey key aac36fc7a9354e06adb9c3eef7fe8b56
boxno 柜子编号 00001-310115-0001-01
nonce 随机数 23be03cbccaf4d7a8fd1e8d704d7b81b
sign 签名，用于校验 32位

返回结果
正常返回：

{
    "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
        }
    ]
}

异常返回：

{
    "r": "000023"
}

返回字段说明

返回值字段 字段类型 字段说明
r string 返回状态码
list arr 格子列表
gridno string 完整格号
status int 格子状态 1空闲 3待存 4存入
showgridno string 格号，显示给客户

返回状态码说明

状态码 说明
000000 操作成功
999999 系统内部异常
000023 签名串错误
000024 apikey异常

配送员信息查询

说明：查询所有配送员信息

URL ：http://api.usmartbox.com/ec/courier.json

请求参数:

keyname 必选 说明
apikey true key
nonce true 32位随机数
sign true 用于校验

返回结果：

{
  "r": "000000",
  "list": [
    {
      "buname": "配送",
      "butype": 1,
      "phone": "13812345678",
      "userName": "配送员1"
    },
    {
      "buname": "配送",
      "butype": 1,
      "phone": "13812345679",
      "userName": "配送员2"
    }
  ]
}

返回字段说明

返回值字段 字段类型 字段说明
r string 返回状态码
list arr 配送员数组
cname string 姓名
phone string 手机号
butype string 业务类型
buname string 业务名称

返回状态码说明

状态码 说明
000000 操作成功
999999 系统内部异常
000023 签名串错误
000024 apikey异常

查询配送员可用的格子功能及大小

http://api.usmartbox.com/ec/boxdetail.json

请求参数:

参数名 说明 参数值举例
apikey key aac36fc7a9354e06adb9c3eef7fe8b56
boxno 柜子编号 00001-210202-0001-01
nonce 随机数 23be03cbccaf4d7a8fd1e8d704d7b81b
phone 配送员手机号 13812345678
sign 签名，用于校验 32位

返回结果
正常返回：

{
    "r": "000000",
    "list": [
        {
            "buname": "默认业务",
            "list": [
                {
                    "func": 1,
                    "sizeList": [
                        {
                            "size": 2,
                            "idle": 10,
                            "name": "中格"
                        }
                    ],
                    "name": "普通"
                }
            ],
            "butype": 1
        }
    ]
}

异常返回：

{
    "r": "000023"
}

返回字段说明

返回值字段 字段类型 字段说明
r string 返回状态码
buname string 业务名称
butype int 业务类型
func int 格子功能 目前1常温2保鲜
size int 格子大小 1小格 2中格 3大格
idle int 格子空闲数量

返回状态码说明

状态码 说明
000000 操作成功
999999 系统内部异常
000023 签名串错误
000024 apikey异常
110009 传入的手机号不是配送员

远程存

http://api.usmartbox.com/ec/cun.json

请求参数:

参数名 说明 参数值举例
apikey key aac36fc7a9354e06adb9c3eef7fe8b56
boxno 柜子编号 00001-210202-0001-01
butype 业务类型 1
func 格子功能 目前1常温2冷藏 1
kphone 配送员手机号 13812345678
nonce 随机数 23be03cbccaf4d7a8fd1e8d704d7b81b
orderid 订单号 173817299734626304
phone 收货人手机号 13812345678
size 格子大小 2
sign 用于校验 32位字符串

返回结果

正常返回:

{
    "r": "000000",
    "gridno": "00001-310115-0001-01-0004",
    "showgridno": "04",
    "opencode": "38737660",
    "seqid": "327957388306939904"
}

异常返回:

{"r":"000024"}

返回字段说明

返回值字段 字段类型 字段说明
r string 返回状态码
gridno string 打开的格子完整编号
showgridno string 打开的格子编号,用于显示
opencode string 取出密码
seqid string 流水号

返回状态码说明

状态码 说明
000000 操作成功
999999 系统内部异常
000013 参数错误
000020 操作超时
000023 签名串错误
000024 apikey异常
110009 传入的手机号不是配送员
120006 在butype、func、size条件下没有空闲的格子，建议更换条件再试
120010 柜子暂停使用,当前不能存
120024 格子打开失败
120025 柜子不在线，稍后再试
120026 柜子当前版本不支持

查询订单投递详细

http://api.usmartbox.com/ec/cunr.json

请求参数：

keyname 必选 说明
apikey true key
nonce true 32位随机数
orderid true 订单号
sign true 用于校验

返回结果 正常返回:

{
    "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"}

返回字段说明

返回值字段 字段类型 字段说明
r string 返回状态码
status int 1已存入柜子;2用户取走;3快递员取出;4系统复原
gridno string 完整格号
showgridno string 格号，用于显示给客户
location string 柜子地址
starttime string 存入时间
endtime string 取走时间 (没取的话没这个key)

返回状态码说明

状态码 说明
000000 操作成功
999999 系统内部异常
000023 签名串错误
000024 apikey异常
120020 尚未存入柜子

远程取

说明： 开柜成功后柜管理系统会调用用户取出时通知电商平台API通知电商系统
URL ：http://api.usmartbox.com/ec/qu.json
请求参数：

keyname 必选 说明
apikey true key
gridno true 完整格号
nonce true 随机数
opencode true 取货密码
seqid true 流水号
sign true 用于校验

返回结果：

{"r" : "000000","showgridno":"04"}
{"r" : "000023"}

返回字段说明

返回值字段 字段类型 字段说明
r string 返回状态码
nonce string 随机数 随机数和完整的格号一起可以查询开柜结果
showgridno string 用于显示的格号

返回状态码说明

状态码 说明
000000 操作成功
999999 系统内部异常
000013 参数错误
000023 签名串错误
000024 apikey异常
120009 格号不正确
120008 取货码错误
120017 格子不在使用状态，请确认是否已取
120025 柜子不在线，稍后再试
120026 柜子当前版本不支持

查询取件状态

http://api.usmartbox.com/ec/qur.json

请求参数：

keyname 必选 说明
apikey true key
nonce true 32位随机数
gridno true 完整格号
seqid true 流水号
sign true 用于校验

返回结果 正常返回:

{"r":"000000","status":"2"}

异常返回:

{"r":"000023"}

返回字段说明

返回值字段 字段类型 字段说明
r string 返回状态码
status string 1未取走;2用户取走;3快递员取出;4系统复原

返回状态码说明

状态码 说明
000000 操作成功
000013 参数错误
999999 系统内部异常
000023 签名串错误
000024 apikey异常

电商端提供

电商端提供的API由智能柜端通过HTTP、HTTPS POST方式调用
电商端接收成功后返回{"r" : "000000"}，若没有返回{"r" : "000000"}，智能柜系统会在3分钟后再次调用，若仍然没返回{"r" : "000000"}，系统30分钟后再调用一次，之后不再调用。
在后台配置回调地址如:
http://api.dianshang.com/api
https://api.dianshang.com/api

配送员存入时通知电商平台

msgtype=cun

请求参数:

参数名 说明 参数值举例
apikey key aac36fc7a9354e06adb9c3eef7fe8b56
gridno 完整格号 00001-320296-0001-01-0016
location 柜子地址 市政府负一层A号柜
msgtype 通知类型 cun
nonce 随机数 23be03cbccaf4d7a8fd1e8d704d7b81b
opencode 取货码，可发给用户 1234
orderid 订单号 20160530143038505204
seqid 存取流水号 158574350541258752
showgridno 格号，显示给客户 16
time 存入时间 2016-09-09 12:23:34
sign 用于校验 32位

返回结果：

{"r" : "000000"}

用户取出时通知电商平台

msgtype=qu
请求参数:

参数名 说明 参数值举例
apikey key aac36fc7a9354e06adb9c3eef7fe8b56
gridno 完整格号 00001-320296-0001-01-0016
msgtype 通知类型 qu
nonce 随机数 23be03cbccaf4d7a8fd1e8d704d7b81b
orderid 订单号 20160530143038505204
seqid 存取流水号 158574350541258752
time 取出时间 2016-09-09 12:25:34
type 类型 1用户取走2快递员取出3系统复原 1
sign 用于校验 32位

返回结果：

{"r" : "000000"}

根据订单号查询收件人手机号及卡号

柜管理系统会先查询本地数据,若未能查到则调用该API查询用户手机号及卡号，卡号用于用户刷卡取件，没有可以不返回
msgtype=phone
请求参数:

参数名 说明 参数值举例
apikey key aac36fc7a9354e06adb9c3eef7fe8b56
msgtype 通知类型 phone
nonce 随机数 23be03cbccaf4d7a8fd1e8d704d7b81b
orderid 订单号(条形码上内容) 20160530143038505204
sign 用于校验 32位

返回结果：

{
    r : '000000',
    cardfaceno:'0000001',
    cardno:'0057947563',
    phone:'13812345678',
}

重发取货密码

发送取货密码后用户未能成功接收，或接收后删除了短信，系统后台可重发一条短信
msgtype=resend
请求参数:

参数名 说明 参数值举例
apikey key aac36fc7a9354e06adb9c3eef7fe8b56
gridno 完整格号 00001-320296-0001-01-0016
location 柜子地址 市政府负一层A号柜
msgtype 通知类型 resend
nonce 随机数 23be03cbccaf4d7a8fd1e8d704d7b81b
opencode 取货码，可发给用户 1234
orderid 订单号 20160530143038505204
showgridno 格号，显示给客户 16
sign 用于校验 32位

返回结果：

{"r" : "000000"}

超时未取通知

配送员存入后，用户长时间（如12小时，具体时间可在智能柜管理系统配置）未取，通知电商系统，电商系统可短信或其他形势通知用户
msgtype=timeout
请求参数:

参数名 说明 参数值举例
apikey key aac36fc7a9354e06adb9c3eef7fe8b56
gridno 完整格号 00001-320296-0001-01-0016
hours 超时时间,单位小时 12
location 柜子地址 市政府负一层A号柜
msgtype 通知类型 timeout
nonce 随机数 23be03cbccaf4d7a8fd1e8d704d7b81b
opencode 取货码，可发给用户 1234
orderid 订单号 20160530143038505204
showgridno 格号，显示给客户 16
sign 用于校验 32位

返回结果：

{"r" : "000000"}

未关门通知

配送员存入或用户取出时超过两分钟未关门，通知电商系统，电商系统可短信或其他形势通知用户或运维人员
msgtype=unclose
请求参数:

参数名 说明 参数值举例
apikey key aac36fc7a9354e06adb9c3eef7fe8b56
boxno 柜号 00001-320296-0001-01
branchname 网点名 市政府
location 柜子地址 市政府负一层A号柜
msgtype 通知类型 unclose
nonce 随机数 23be03cbccaf4d7a8fd1e8d704d7b81b
phone 配置在后台的运维人员手机号 13812345678,13812345679 若配置了多个运维人员则返回多个手机号,逗号隔开
showgridno 格号，显示给客户 16
type 操作类型 1配送员存、2用户取、3配送员取
uphone 操作人员手机号 13812345679
sign 用于校验 32位

返回结果：

{"r" : "000000"}

柜子异常通知

柜子出现断网等异常情况，通知电商系统，电商系统可短信或其他形势通知运维人员
msgtype=boxwarn
请求参数:

参数名 说明 参数值举例
apikey key aac36fc7a9354e06adb9c3eef7fe8b56
boxno 柜号 00001-320296-0001-01
branchname 网点名 市政府
location 柜子地址 市政府负一层A号柜
msgtype 通知类型 boxwarn
nonce 随机数 23be03cbccaf4d7a8fd1e8d704d7b81b
phone 配置在后台的运维人员手机号 13812345678,13812345679 若配置了多个运维人员则返回多个手机号,逗号隔开
warndesc 警告描述 网络可能存在异常
warntype 警告类型 1 网络异常
sign 用于校验 32位

返回结果：

{"r" : "000000"}

柜子管理员登录短信验证码

短信由柜子系统发送时不调用此API，短信由电商系统发送时才调用此API
msgtype=vcode

请求参数:

参数名 说明 参数值举例
apikey key aac36fc7a9354e06adb9c3eef7fe8b56
boxno 柜子编号 00001-320296-0001-01
msgtype 通知类型 vcode
nonce 随机数 23be03cbccaf4d7a8fd1e8d704d7b81b
phone 管理员手机号 13812042761
vcode 验证码 123456
sign 用于校验 32位

返回结果：

{"r" : "000000"}

给用户发卡及刷卡取件

目前有两种发卡方式,流程基本一致,推荐使用方式1

方式1:卡号和原账号绑定

用户只绑定一张卡用于刷卡取件，该卡仅用于取件不用于充值

电商系统卡表必要字段

字段 说明
cardfaceno 卡面号
cardno 卡内芯片号(刷卡取件时用)
pwd 密码

流程

  1. 确定卡编号规则 如NO00001到NO99999
  2. 根据规则制卡,卡编号印刷到卡表面
  3. 通过电商提供的系统录入数据,并将密码和金额贴到卡上。此步骤需要读卡获得卡内芯片号,录入的数据包括cardfaceno,cardno,pwd
  4. 发给用户(卡+密码)
  5. 用户登录后输入卡面号、密码绑定

订单信息导入时将卡面号,卡内号一起发给柜管理系统
柜管理系统不做补卡、换卡、挂失操作

方式2:卡号作为新账号使用

该卡同时用于充值及取件

电商系统卡表必要字段

字段 说明
cardfaceno 卡面号
cardno 卡内芯片号(刷卡取件时用)
pwd 密码
amount 金额

流程

  1. 确定卡编号如NO00001到NO99999
  2. 根据规则制卡,卡编号印刷到卡表面
  3. 通过电商提供的系统录入数据,并将密码和金额贴到卡上。此步骤需要读卡获得卡内芯片号,录入的数据包括cardfaceno,cardno,pwd,amount
  4. 发给用户(卡+密码)
  5. 用户根据卡号密码登录

订单信息导入时将卡面号,卡内号一起发给柜管理系统
柜管理系统不做补卡、换卡、挂失操作

城市及区编号

上海的例子

名称 编号
上海市 310100
黄浦区 310101
徐汇区 310104
长宁区 310105
静安区 310106
普陀区 310107
虹口区 310109
杨浦区 310110
闵行区 310112
宝山区 310113
嘉定区 310114
浦东新区 310115
金山区 310116
松江区 310117
青浦区 310118
奉贤区 310120
崇明区 310151

数据来自国家统计局2017-上海

其他城市参考国家统计局2017-全部

其他

若还需要其他API，联系柜管理系统开发商