订单库接口

1 背景介绍

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

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

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

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

2 接口规范

2.1 协议说明

对接的openAPI接口目前只开放HTTPS方式,所有的消息一律采用POST方式。

注:消息体大小不得超过1M,超过1M的请求,直接拒绝!

Content-Typeapplication/x-www-form-urlencoded
数据格式返回为JSON格式
字符编码UTF-8字符编码
签名算法MD5
签名规则参考2.2 签名规则

2.2 签名规则

参考《鉴权认证》文档。

2.3 公共参数

参数名必填类型说明
app_idstring唯一标识接入身份,联系商米数字店铺提供
randomstring随机字符串,由数字和字母组成,长度范围为6-10位
timestampint当前的unix timestamp,精度到秒级,10位数字
signstring签名信息,详见2.2

3 开放API接口

3.1 订单库对接

3.1.1 订单字段属性

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

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

订单字段(order)

参数分组商米数字平台订单参数类型说明必填唯一SaaS合作方订单参数参数说明
订单基础信息order_idstring订单号对接时唯一订单标识,SaaS订单号
order_typeint交易类型标识正常销售,退货等类型 (1-正常销售、 2-退货, 3-换货, 4-挂单,5-报表, 6 -付款失败,7-取消,8 -其他)
order_timeint交易时间交易时间戳,用于收银审计等业务
order_start_timeint交易开始时间如果记录交易开始时间, 可用于收银审计等业务
purchase_amountdouble(精确到小数点后两位)合计应收金额
discount_amountdouble(精确到小数点后两位)合计折扣金额
received_amountdouble(精确到小数点后两位)实收金额
payment_typeint付款方式1-现金、2-支付宝、3-微信、4-QQ钱包、5-京东钱包、6-银行卡刷卡、7-银联二维码、8-其他
customer_countint购买人数/就餐人数若无默认给1
收银设备信息device_snstring交易产生的设备序列号
software_namestring交易SaaS软件名称
software_specstring交易SaaS软件规格
hardware_namestring交易SaaS硬件名称
hardware_specstring交易SaaS硬件规格
cashier_idstring收银员
cashier_deskstring收银台
shop_assistant_idstring营业员
订单来源平台信息order_sourceint订单来源1-线下、 2-线上 (默认为线下订单)
会员信息member_idstring会员卡号
ali_idstring支付宝AliId


wechat_open_idstring微信OpenId
member_pointsdouble会员积分


卡券信息coupon_idstring卡券号
coupon_source int卡券来源1-商家自建,2-支付宝, 3-微信, 4-其他
小票信息receipt_idstring小票号
sunmi_receipt_idstring商米小票唯一识别号
商品信息product_liststring(内容为array[product])商品列表

具体字段见下表

商品字段(product)

商米数字平台订单商品参数类型说明必填唯一SaaS合作方商品参数参数说明
idstring商品编号
namestring商品名称 
seq_numstring商品店铺内部编码


bar_codestring商品国际条码
specstring商品规格
unitstring商品计量单位
quantitydouble(精确到小数点后三位)销售数量
stock_quantitydouble(精确到小数点后三位)库存数量
category_idstring品类编号 
category_namestring品类名称
original_pricedouble(精确到小数点后两位)商品标价(单价标价)
present_pricedouble(精确到小数点后两位)商品实际销售价格
promote_amountdouble(精确到小数点后两位)商品销售优惠金额
subtotal_amountdouble(精确到小数点后两位)商品小计总额(实收)

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

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

3.1.2 创建订单推送接口 

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

接口链接:/order/create

接口版本:v2.0

接口参数

参数名称是否必须类型说明示例
sunmi_shop_no string 商米数字店铺平台唯一编号(v2.0之后为必填项) 100939070408
shop_idstring 店铺在SaaS体系下的唯一标识(此参数为后向兼容v2.0之前版本的字段,在v2.0及以后版本使用sunmi_shop_no替代,作为门店唯一标识即可) 10001
order_liststring(内容为array)创建订单对象列表 [
{
“order_id”: “d12324b545a5678”,
“order_type”: 1,
“order_time”: 1583246199,
“order_start_time”: 1568875091,
“purchase_amount”: 100,
“discount_rate”: 80,
“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_rate": 80,
      "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 订单库对接示例