商米开发者文档

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_code	string	一级分类编号
26	category_level1_name	string	一级分类名称
27	category_level2_ code	string	二级分类编号
28	category_level2_name	string	二级分类名称
29	category_level3_ code	string	三级分类编号
30	category_level3_name	string	三级分类名称
31	category_level4_ code	string	四级分类编号
32	category_level4_name	string	四级分类名称
33	category_level5_ code	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″,“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": "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″,“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": "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"
         ]
     }
 }