商米开发者文档

1 背景介绍

商米数字店铺（SUNMI Store）是商米提供的围绕商户店铺中物联网设备基础上的店铺管理系统。

商米数字店铺作为一个开放平台，支持与第三方SaaS厂商进行各种数据的对接，包括商品信息对接，交易信息对接，会员体系对接等。

基于商米提供的多种物联网设备，可以帮助商户提高数字化程度，基于这些数字化信息，比如人流分析和统计信息，再加上SaaS导入的订单信息，就可以做多维度的分析和报表。

本文描述的是与第三方SaaS厂商进行订单信息对接，确保商米数字店铺的商户可以从SaaS尽可能实时的获取订单信息，用于后续处理和BI分析。

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	签名信息，详见2.2

3 开放API接口

3.1 订单库对接

3.1.1 订单字段属性

以下属性均为商米店铺订单属性，仅用来做解释说明用。请SaaS厂商提供自己的订单属性清单，并与商米拉取SaaS系统中的订单属性保持一致

下列属性为商米数字店铺订单为例子的基本属性，对于具体品类的订单，还会有其他字段。

订单字段(order)

参数分组	商米数字平台订单参数	类型	说明	必填	唯一	SaaS合作方订单参数	参数说明
订单基础信息	order_id	string	订单号	●	●		对接时唯一订单标识，SaaS订单号
	order_type	int	交易类型	●			标识正常销售，退货等类型 （1-正常销售、 2-退货， 3-换货, 4-挂单，5-报表 , 6 -付款失败，7-取消，8 -其他 ）
	order_time	int	交易时间	●			交易时间戳， 用于收银审计等业务
	order_start_time	int	交易开始时间				如果记录交易开始时间， 可用于收银审计等业务
	purchase_amount	double(精确到小数点后两位）	合计应收金额	●			
	discount_amount	double(精确到小数点后两位）	合计折扣金额	●			
	received_amount	double(精确到小数点后两位）	实收金额	●			
	payment_type	int	付款方式	●			1-现金、2-支付宝、3-微信、4-QQ钱包、5-京东钱包、6-银行卡刷卡、7-银联二维码、8-其他
	customer_count	int	购买人数/就餐人数				若无默认给1
收银设备信息	device_sn	string	交易产生的设备序列号	●			
	software_name	string	交易SaaS软件名称				
	software_spec	string	交易SaaS软件规格				
	hardware_name	string	交易SaaS硬件名称				
	hardware_spec	string	交易SaaS硬件规格				
	cashier_id	string	收银员				
	cashier_desk	string	收银台				
	shop_assistant_id	string	营业员				
订单来源平台信息	order_source	int	订单来源				1-线下、 2-线上 （默认为线下订单）
会员信息	member_id	string	会员卡号				
	ali_id	string	支付宝AliId 				
	wechat_open_id	string	微信OpenId				
	member_points	double	会员积分 				
卡券信息	coupon_id	string	卡券号				
	coupon_source	int	卡券来源				1-商家自建，2-支付宝， 3-微信， 4-其他
小票信息	receipt_id	string	小票号				
	sunmi_receipt_id	string	商米小票唯一识别号				
商品信息	product_list	string（内容为array[product]）	商品列表	● 			具体字段见下表

商品字段(product)

商米数字平台订单商品参数	类型	说明	必填	唯一	SaaS合作方商品参数	参数说明
id	string	商品编号	●			
name	string	商品名称	●			
seq_num	string	商品店铺内部编码				
bar_code	string	商品国际条码				
spec	string	商品规格	●			
unit	string	商品计量单位				
quantity	double(精确到小数点后三位）	销售数量	●			
stock_quantity	double(精确到小数点后三位）	库存数量				
category_id	string	品类编号				
category_name	string	品类名称				
original_price	double(精确到小数点后两位）	商品标价（单价标价）	●			
present_price	double(精确到小数点后两位）	商品实际销售价格	●			
promote_amount	double(精确到小数点后两位)	商品销售优惠金额	●			
subtotal_amount	double(精确到小数点后两位)	商品小计总额（实收）	●			

商品字段(product 附加业态字段)

商米数字平台订单商品附加参数	类型	说明	必填	唯一	SaaS合作方商品参数	参数说明
color	string	颜色代码				
size	string	尺寸代码				

3.1.2 创建订单推送接口 

接口说明：本接口用于SaaS厂商对订单进行创建，推送通知到我方，商米数字店铺会根据SaaS厂商推送的订单，保存对应订单，商米数字店铺前端设备提供对应的订单显示及查看。

接口链接：/order/create

接口版本：v2.0

接口参数：

参数名称	是否必须	类型	说明	示例
sunmi_shop_no	否	string	商米数字店铺平台唯一编号	100939070408
shop_id	否	string	店铺在SaaS体系下的唯一标识（在v2.0及以后版本可使用sunmi_shop_no替代，作为门店唯一标识即可，如果没有shumi_shop_no，可以使用company_id加shop_id作为门店唯一标识）	10001
order_list	是	string（内容为array）	创建订单对象列表	[ { “order_id”: “d12324b545a5678”, “order_type”: 1, “order_time”: 1583246199, “order_start_time”: 1568875091, “purchase_amount”: 100, “discount_amount”: 20, “received_amount”: 80, “payment_type”: 1, “customer_count”: 2, “order_status”: 1, “device_sn”: “SS123LTY6917”, “software_name”: “SUNMI”, “software_spec”: “app”, “hardware_name”: “hw”, “hardware_spec”: “hws”, “order_source”: 1, “member_id”: 123456, “product_list”: [ { “name”: “p_name”, “seq_num”: “abc”, “id”: 5, “price”: 10, “quantity”: 3, “color”: “red”, “size”: “larse” } ], “cashier_id”: “cachier123”, “cashier_desk”: 123, “shop_assistant_id”: 666, “ali_id”: 13111115555, “wechat_open_id”: “wechat123”, “member_points”: 156, “coupon_id”: 123, “coupon_source”: 1, “receipt_id”: “rcn12333333”, “sunmi_receipt_id”: “sunmi666” } ]

请求示例： 

  'method': 'POST',
  'url': 'https://store.uat.sunmi.com/openapi/order/create',
  'headers': {
    'Content-Type': 'application/x-www-form-urlencoded'
  },
  formData: {
    'shop_id': '10001',
    'app_id': 'I4VI99A0JDS21',
    'timestamp': '1581662687',
    'random': '5dsf6698',
    'sign': 'E3CC30458CBDC74E7D959E24B56732F6',
    'order_list': '[{
      "order_id": "d12324b545a5678",
      "order_type": 1,
      "order_time": 1583246199,
      "order_start_time": 1568875091,
      "purchase_amount": 100,
      "discount_amount": 20,
      "received_amount": 80,
      "payment_type": 1,
      "customer_count": 2,
      "order_status": 1,
      "device_sn": "SS123LTY6917",
      "software_name": "SUNMI",
      "software_spec": "app",
      "hardware_name": "hw",
      "hardware_spec": "hws",
      "order_source": 1,
      "member_id": 123456,
      "product_list": [{
          "name": "p_name",
          "seq_num": "abc",
          "id": 5,
          "price": 10,
          "quantity": 3,
          "color": "red",
          "size": "larse"
       }],
      "cashier_id": "cachier123",
      "cashier_desk": 123,
      "shop_assistant_id": 666,
      "ali_id": 13111115555,
      "wechat_open_id": "wechat123",
      "member_points": 156,
      "coupon_id": 123,
      "coupon_source": 1,
      "receipt_id": "rcn12333333",
      "sunmi_receipt_id": "sunmi666"
    }],
 }

返回值： 

{
    "code": 0,
    "msg": "succeed",
    "data": {
        "exist_list": ["12325456778"],
        "invalid_list": []
    }
}

错误列表:

错误代码	错误原因
5041	非法SaaS厂商
5047	非法订单

4 返回值检查

4.1 返回错误分类

作为HTTP消息返回，如果消息签名认证失败，HTTP消息会返回 401等作为提示。 如果消息签名认证通过，则进入业务层处理，此次HTTP请求返回200 OK。

具体业务层面的操作返回JSON值在消息体中。常见的消息返回类型为：

{
    "code": 0,
    "msg": "succeed",
    "data": {}
}

4.2 返回错误代码列表

参考 《错误代码列表》文档。

5 订单库对接示例