1 背景介绍
商米数字店铺作为一个开放平台,支持与第三方软件进行各种对接,包括设备层面智能摄像机、电子价签的对接,数据层面的商品信息、交易信息对接等。
电子价签等物联网设备需要对接店铺的商品,价格以及策略等信息,所以在数字店铺系统内保存了一个基本的商品库。
对于商品数据来源,用户既可以选择直接在数字店铺的页面进行编辑,也可以选择与第三方软件进行数据打通。
2 接口规范
2.1 协议说明
对接的openAPI接口目前只开放HTTPS方式,所有的消息一律采用POST方式。
注:消息体大小不得超过1M,超过1M的请求,直接拒绝!
Content-Type | application/x-www-form-urlencoded |
---|---|
数据格式 | 返回为JSON格式 |
字符编码 | UTF-8字符编码 |
签名算法 | MD5 |
签名规则 | 参考2.2 签名规则 |
2.2 签名规则
参考《鉴权认证》文档。
2.3 公共参数
参数名 | 必填 | 类型 | 说明 |
---|---|---|---|
app_id | 是 | string | 唯一标识接入身份,联系商米数字店铺提供 |
random | 是 | string | 随机字符串,由数字和字母组成,长度范围为6-10位 |
timestamp | 是 | int | 当前的unix timestamp,精度到秒级,10位数字 |
sign | 是 | string | 签名信息,详见上文签名规则 |
3 商米提供接口
3.1. 商品字段属性
下面的表格描述了数字店铺开放平台中商品字段的属性,适用于后面所有的新增、修改等接口。
商品字段中预留了一些自定义字段,对接时可以将第三方软件中的特殊字段对应到这些字段上。
商米数字平台商品参数 | 类型 | 说明 | 是否必须 | |
---|---|---|---|---|
1 | id | string | 数据库ID,唯一,页面不可见,可以与商品编号相同 | 是 |
2 | seq_num | string | 商品编号,唯一,也就是网页和APP上显示的商品编号,可以和数据库ID相同 推荐填写,在网页创建和Excel导入中均会用到 | |
3 | name | string | 商品名称 | 是 |
4 | price | double | 价格 ,注意称重商品为斤价还是公斤价 | 是 |
5 | bar_code | string | 条码 | |
6 | alias | string | 别名 | |
7 | unit | string | 单位 | |
8 | spec | string | 规格 | |
9 | level | string | 等级 | |
10 | area | string | 产地 | |
11 | brand | string | 品牌 | |
12 | qr_code | string | 二维码链接 | |
13 | status | string | 商品状态 | |
14 | description | string | 商品描述 | |
15 | promote_price | double | 促销价 | |
16 | promote_price_description | string | 促销价描述 | |
17 | member_price | double | 会员价 | |
18 | member_price_description | string | 会员价描述 | |
19 | extra_info | json | 扩展信息 | |
20 | extra_price_info | json | 其它价格信息 | |
21 | extra_custom_info | json | 自定义信息 |
extra_info:
商米数字平台商品参数 | 类型 | 说明 | 是否必须 | |
---|---|---|---|---|
1 | pack_size | int | 箱规 | |
2 | stock | float64 | 库存 | |
3 | safety_stock | float64 | 安全库存 | |
4 | daily_mean_sales | float64 | 日均销售量 | |
5 | today_sales_qty | float64 | 当日销售量 | |
6 | cumulated_sales_qty | float64 | 累计销售量 | |
7 | on_order_qty | float64 | 在途订单量 | |
8 | shelf_qty | float64 | 陈列量 | |
9 | shelf_code | string | 货架编号 | |
10 | shelf_tier | string | 货架层 | |
11 | shelf_column | string | 货架列 | |
12 | display_location | string | 摆放位置 | |
13 | supplier_code | string | 供应商编号 | |
14 | supplier_name | string | 供应商名称 | |
15 | manufacturer | string | 生产商名称 | |
16 | manufacturer_address | string | 生产商地址 | |
17 | expiry_date | timestamp | 过期日期 | |
18 | storage_life | string | 保质期限 | |
19 | shelf_life | int | 已上架时间 | |
20 | ingredient_table | string | 配料表 | |
21 | fresh_item_code | string | 生鲜商品码 | |
22 | supervised_by | string | 监制单位 | |
23 | supervision_hotline | string | 监督电话 | |
24 | pricing_staff | string | 计价员 | |
25 | category_level1_id | string | 一级分类编号 | |
26 | category_level1_name | string | 一级分类名称 | |
27 | category_level2_id | string | 二级分类编号 | |
28 | category_level2_name | string | 二级分类名称 | |
29 | category_level3_id | string | 三级分类编号 | |
30 | category_level3_name | string | 三级分类名称 | |
31 | category_level4_id | string | 四级分类编号 | |
32 | category_level4_name | string | 四级分类名称 | |
33 | category_level5_id | string | 五级分类编号 | |
34 | category_level5_name | string | 五级分类名称 |
extra_price_info:
商米数字平台商品参数 | 类型 | 说明 | 是否必须 | |
---|---|---|---|---|
1 | custom_price1 | float64 | 自定义价格1 | |
2 | custom_price1_description | string | 自定义价格1描述 | |
3 | custom_price2 | float64 | 自定义价格2 | |
4 | custom_price2_description | string | 自定义价格2描述 | |
5 | custom_price3 | float64 | 自定义价格3 | |
6 | custom_price3_description | string | 自定义价格3描述 | |
7 | promote_start_date | timestamp | 促销开始日期 | |
8 | promote_end_date | timestamp | 促销结束日期 | |
9 | member_promote_start_date | timestamp | 会员促销开始日期 | |
10 | member_promote_end_date | timestamp | 会员促销结束日期 | |
11 | member_point | float64 | 会员积分 | |
12 | promote_reason | string | 促销原因 | |
13 | promote_flag | int | 促销标识 |
extra_custom_info:
商米数字平台商品参数 | 类型 | 说明 | 是否必须 | |
---|---|---|---|---|
1 | custom_text1 | string | 自定义字段1 | |
2 | custom_text2 | string | 自定义字段2 | |
3 | custom_text3 | string | 自定义字段3 | |
4 | custom_text4 | string | 自定义字段4 | |
5 | custom_text5 | string | 自定义字段5 | |
6 | custom_text6 | string | 自定义字段6 | |
7 | custom_text7 | string | 自定义字段7 | |
8 | custom_text8 | string | 自定义字段8 | |
9 | custom_text9 | string | 自定义字段9 | |
10 | custom_text10 | string | 自定义字段10 | |
11 | custom_text11 | string | 自定义字段11 | |
12 | custom_text12 | string | 自定义字段12 | |
13 | custom_text13 | string | 自定义字段13 | |
14 | custom_text14 | string | 自定义字段14 | |
15 | custom_text15 | string | 自定义字段15 | |
16 | custom_text16 | string | 自定义字段16 | |
17 | custom_text17 | string | 自定义字段17 | |
18 | custom_text18 | string | 自定义字段18 | |
19 | custom_text19 | string | 自定义字段19 | |
20 | custom_text20 | string | 自定义字段20 | |
21 | custom_int1 | int | 自定义整数1 | |
22 | custom_int2 | int | 自定义整数2 | |
23 | custom_int3 | int | 自定义整数3 | |
24 | custom_int4 | int | 自定义整数4 | |
25 | custom_int5 | int | 自定义整数5 | |
26 | custom_dec1 | float64 | 自定义小数1 | |
27 | custom_dec2 | float64 | 自定义小数2 | |
28 | custom_dec3 | float64 | 自定义小数3 | |
29 | custom_dec4 | float64 | 自定义小数4 | |
30 | custom_dec5 | float64 | 自定义小数5 | |
31 | others | string | 其他 |
3.2 新建商品
接口说明:第三方对接的软件新建商品后,通过该接口推送通知到我方,商米数字店铺会根据推送的商品信息新建对应商品。
本接口只对应于新增商品接口,如果商品【数据库ID】已经存在,则会将存在的id添加入exist_list,如果商品信息中的必填字段(比如名称)未输入,则将id添加入invalid_list并返回.。
接口链接:/product/create
接口参数:
参数名称 | 是否必须 | 类型 | 说明 | 示例 |
---|---|---|---|---|
sunmi_shop_no | 否 | string | 商米数字店铺平台中门店的唯一编号(v2.0之后为必填项) | 100939070408 |
shop_id | 否 | string | 第三方对接软件中门店的唯一编号(此参数为后向兼容v2.0之前版本的字段,在v2.0及以后版本使用sunmi_shop_no替代,作为门店唯一标识即可) | 10001 |
product_list | 是 | array | 新建商品对象列表 | [{“name”:”cola”,”id”:”1″,”bar_code”:”6958644000259″,”unit”:”bottle”,”price”:”3.5″,”member_price”:”3″,”spec”:”250ml”,”level”:””,”brand”:”coca”}] |
product 参数类型参考前文中【商品字段属性】。
请求示例:
'method': 'POST',
'url': 'https://store.uat.sunmi.com/openapi/product/create',
'headers': {
'Content-Type': 'application/x-www-form-urlencoded'
},
formData: {
'shop_id': '10001',
'app_id': 'I4VI99A0JDS21',
'timestamp': '1581658876',
'random': '5dsf6698',
'sign': 'DDCB590591531D9B85729EE13E9B9095',
'product_list': '[
{
"name": "milk",
"id": "1",
"bar_code": "6958644000259",
"unit": "bottle",
"price": "4.5",
"member_price": "3",
"spec": "250ml",
"level": "",
"brand": "test"
}] '
}
返回值:
{
code:0
msg: "succeed"
data: {
“exist_list”: ["100",
"200"],
"invalid_list:["400",
]}
}
}
错误列表:
错误代码 | 错误原因 |
---|---|
5000 | 数据库错误 |
5041 | 非法对接软件 |
5015 | 非法商品 |
3.3 更新商品
接口说明:第三方对接的软件更新商品后,通过该接口推送通知到我方,商米数字店铺会根据推送的商品信息更新对应商品。如果该商品已经绑定到电子价签上,会触发电子价签的自动更新。
更新接口只会更新商米数字店铺中已经存在的商品,通过数据库ID匹配到的商品,则会进行更新操作, 未匹配到则新增对应商品,这些新增商品的id可以在返回中”not_exist_list”中查看。
更新操作只会修改接收到的商品字段,不存在的字段则保持原有数据不做处理。
接口链接:/product/update
接口版本:v2.0
接口参数:
参数名称 | 是否必须 | 类型 | 说明 | 示例 |
---|---|---|---|---|
sunmi_shop_no | 否 | string | 商米数字店铺平台中门店的唯一编号(v2.0之后为必填项) | 100939070408 |
shop_id | 否 | string | 第三方对接软件中门店的唯一编号(此参数为后向兼容v2.0之前版本的字段,在v2.0及以后版本使用sunmi_shop_no替代,作为门店唯一标识即可) | 10001 |
product_list | 是 | array | 更新商品对象列表 | [{“name”:”milk”,”id”:”1″,”bar_code”:”6958644000259″,”unit”:”bottle”,”price”:”4.5″,”member_price”:”3″,”spec”:”250ml”,”level”:””,”brand”:”test”}] |
product 参数类型参考前文中【商品字段属性】。
请求示例:
'method': 'POST',
'url': 'https://store.uat.sunmi.com/openapi/product/create',
'headers': {
'Content-Type': 'application/x-www-form-urlencoded'
},
formData: {
'shop_id': '10001',
'app_id': 'I4VI99A0JDS21',
'timestamp': '1581658876',
'random': '5dsf6698',
'sign': 'DDCB590591531D9B85729EE13E9B9095',
'product_list': '[
{
"name": "milk",
"id": "1",
"bar_code": "6958644000259",
"unit": "bottle",
"price": "4.5",
"member_price": "3",
"spec": "250ml",
"level": "",
"brand": "test"
}] '
}
返回值:
注意: not_exist_list指的是以前不存在,这次调用update接口完成新增的商品
{
"code": 0,
"msg": "succeed",
"data": {
"exist_list": [
"1"
],
"invalid_list": []
}
}
错误列表:
错误代码 | 错误原因 |
---|---|
5000 | 数据库错误 |
5041 | 非法对接软件 |
5015 | 非法商品 |
3.4 删除商品
接口说明:第三方对接的软件删除商品后,可通过该接口推送通知到我方,商米数字店铺会根据推送的商品信息删除对应商品。
删除接口只会删除商米数字店铺中已经存在的商品,若根据商品数据库ID字段匹配不到,会将不存在的id添加入not_exist_list并返回。匹配到的商品,则会进行删除操作。
接口链接:/product/delete
接口版本:v2.0
接口参数:
参数名称 | 是否必须 | 类型 | 说明 | 示例 |
---|---|---|---|---|
sunmi_shop_no | 否 | string | 商米数字店铺平台中门店的唯一编号(v2.0之后为必填项) | 100939070408 |
shop_id | 否 | string | 第三方对接软件中门店的唯一编号(此参数为后向兼容v2.0之前版本的字段,在v2.0及以后版本使用sunmi_shop_no替代,作为门店唯一标识即可) | 10001 |
product_key_list | 是 | list | 唯一标识商品的属性字段列表 | [1] |
请求示例:
'method': 'POST',
'url': 'https://store.uat.sunmi.com/openapi/product/delete',
'headers': {
'Content-Type': 'application/x-www-form-urlencoded'
},
formData: {
'shop_id': '10001',
'app_id': 'I4VI99A0JDS21',
'timestamp': '1581659359',
'random': '5dsf6698',
'sign': '00E5E55999C3C5BCA85DA3844928A70B',
'product_key_list': '[1]'
}
返回值:
{
"code": 0,
"msg": "succeed",
"data": {
"not_exist_list": [
"1"
]
}
}
错误列表:
错误代码 | 错误原因 |
---|---|
5000 | 数据库错误 |
5041 | 非法对接软件 |
5015 | 非法商品 |
4 返回值检查
4.1 返回错误分类
作为HTTP消息返回,如果消息签名认证失败,HTTP消息会返回 401等作为提示。 如果消息签名认证通过,则进入业务层处理,此次HTTP请求返回200 OK。
具体业务层面的操作返回JSON值在消息体中。常见的消息返回类型为:
{
code:0
msg: "succeed"
data: {}
}
错误列表:
错误代码 | 错误原因 |
---|---|
5000 | 数据库错误 |
5041 | 非法对接软件 |
5015 | 非法商品 |
4.2 返回错误代码
参考《错误代码列表》文档
5 商品库对接示例
本部分提供了商品库对接的接口示例。仅供参考。
以下接口需在成功进行商户店铺对接后方能正常使用。店铺对接相关请参考《商户店铺》文档
本部分示例使用参数如下(接口中与签名校验相关的timestamp、random、sign等参数已省略):
app_id | secret_key | shop_id |
---|---|---|
APPID6917LTY | tokenlty123 | 7948 |
如下图,商户店铺对接后,商米数字店铺的商品库页面无任何商品。

5.1 新建商品
5.1.1 新建商品成功
商户店铺对接成功后,调用product/create接口来增加商品。
请求参数:
app_id | APPID6917LTY |
shop_id | 7948 |
product_list | [{“name”:”\u53ef\u53e3\u53ef\u4e50\/\u704c\u88c5″,”id”:”1″,”seq_num”:”cola58476″,”bar_code”:”6958644000259″,”unit”:”\u7f50″,”price”:”3.2″,”member_price”:”3″,”spec”:”250ml”,”level”:””,”brand”:”\u53ef\u4e50″}] |
返回结果:
{
"code": 0,
"msg": "succeed",
"data": {
"exist_list": [],
"invalid_list": []
}
}
刷新商米数字店铺的商品库页面,可以看到商品库中新增了一条商品

点击详情查看详细信息:

5.1.2 新建商品失败-商品已存在
将6.1.1中的请求再次发送,则接口会返回该商品已存在,并给出已存在的商品id。
请求参数:
app_id | APPID6917LTY |
shop_id | 7948 |
product_list | [{“name”:”\u53ef\u53e3\u53ef\u4e50\/\u704c\u88c5″,”id”:”1″,”seq_num”:”cola58476″,”bar_code”:”6958644000259″,”unit”:”\u7f50″,”price”:”3.2″,”member_price”:”3″,”spec”:”250ml”,”level”:””,”brand”:”\u53ef\u4e50″}] |
返回结果:
{
"code": 0,
"msg": "succeed",
"data": {
"exist_list": [
"1"
],
"invalid_list": []
}
}
5.1.3 新建商品失败-商品列表不是合法JSON字符串
商品列表中插入字符,使得参数不是合法json字符串
请求参数:
app_id | APPID6917LTY |
shop_id | 7948 |
product_list | [{“name”:”\u53ef\u53e3\u53ef\u4e50\/\u704c\u88c5″,,,”id”:”1″,”seq_num”:”cola58476″,”bar_code”:”6958644000259″,”unit”:”\u7f50″,”price”:”3.2″,”member_price”:”3″,”spec”:”250ml”,”level”:””,”brand”:”\u53ef\u4e50″}] |
返回结果:
{
"code": 1,
"msg": "product_list: JSON.parse error"
}
5.1.4 新建商品失败-未提供商品必要字段
在商品列表中,不提供商品必填字段“id”。
请求参数:
app_id | APPID6917LTY |
shop_id | 7948 |
product_list | [{“name”:”\u53ef\u53e3\u53ef\u4e50\/\u704c\u88c5″, |
返回结果:
{
"code": 1,
"msg": "invalid saas product info"
}
5.2 更新商品
5.2.1 更新商品成功-更新已经存在的商品
商户店铺对接成功后,调用product/update接口来更新商品信息(此处以价格为例)。
请求参数:
app_id | APPID6917LTY |
shop_id | 7948 |
product_list | [{“id”:1, “price”:”3.5″}] |
返回结果:
{
"code": 0,
"msg": "succeed",
"data": {
"not_exist_list": [],
"invalid_list": []
}
}
回到商米数字店铺商品库界面,可以发现商品价格已由3.2元变为3.5元,“最后修改时间”已经更新为修改商品价格的时间。
更新前


更新后


5.2.2 更新商品成功-新建不存在的商品
商户店铺对接成功后,调用product/update接口来新建一个不存在商品信息。
请求参数:
app_id | APPID6917LTY |
shop_id | 7948 |
product_list | [{“id”:2, “name”:”Non-Exist Product”,”seq_num”:”nonexist1″,”price”:”58.2″}] |
返回结果:
{
"code": 0,
"msg": "succeed",
"data": {
"not_exist_list": [
"2"
],
"invalid_list": []
}
}
返回值中提示了商品id为“2”的商品原本不存在于商品库中,已采取新建操作。回到商品库,可以看到该商品已经被新建。
更新前

更新后

5.2.3 更新商品失败-商品列表不是合法JSON字符串
商品列表中插入字符,使得参数不是合法json字符串
请求参数:
app_id | APPID6917LTY |
shop_id | 7948 |
product_list | [{“name”:”\u53ef\u53e3\u53ef\u4e50\/\u704c\u88c5″,,,”id”:”1″,”seq_num”:”cola58476″,”bar_code”:”6958644000259″,”unit”:”\u7f50″,”price”:”3.2″,”member_price”:”3″,”spec”:”250ml”,”level”:””,”brand”:”\u53ef\u4e50″}] |
返回结果:
{
"code": 1,
"msg": "product_list: JSON.parse error"
}
5.2.4 更新商品失败-未提供商品必要字段
在商品列表中,不提供商品必填字段“id”。
请求参数:
app_id | APPID6917LTY |
shop_id | 7948 |
product_list | [{“name”:”\u53ef\u53e3\u53ef\u4e50\/\u704c\u88c5″, |
返回结果:
{
"code": 1,
"msg": "invalid saas product info"
}
5.3 删除商品
5.3.1 删除商品成功
商户店铺对接成功后,调用product/delete接口来删除商品信息。
请求参数:
app_id | APPID6917LTY |
shop_id | 7948 |
product_key_list | [2] |
返回结果:
{
"code": 0,
"msg": "succeed",
"data": {
"not_exist_list": []
}
}
回到商品库,可以看到id为2的商品已经被删除。
删除前

删除后

5.3.2 删除商品失败-商品不存在
商户店铺对接成功后,调用product/delete接口来删除一个不存在的商品信息。
请求参数:
app_id | APPID6917LTY |
shop_id | 7948 |
product_key_list | [3] |
返回结果:
{
"code": 0,
"msg": "succeed",
"data": {
"not_exist_list": [
"3"
]
}
}