Order APIs

1 Background

SUNMI Store system is a store management system provided by SUNMI for merchants based on the IoT devices in stores.

As an open platform, SUNMI Store can do data interchange for third-party SaaS providers, including the interchange of product information, transaction information and membership system.

Multiple SUNMI IOT device will help customers digitalize their shop. Based on these data, such as passenger flow and statistic info, combined with the saas order, SUNMI will be able to create a multi-dimensional analysis and chart.

This document describes how to syncronize the order information with the Saas provider to make sure our customer can obtain data as soon as possible for future process or BI analysis

2 API Specifications

2.1 Protocol

All APIs use HTTPS Protocol with POST method

Note: The size of the request body should be no more than 1 MB. If this size is exceeded, open platform will deny it.

Content-Typeapplication/x-www-form-urlencoded
return type JSON
encodingUTF-8
signing algorithmsMD5
signing rulessee chapter 2.2

2.2 Signing rules

see Authentication

2.3 Common Parameters

parameterrequiredtypedescription
app_idyesstringunique identifier provided by SUNMI store open platform
randomyesstring6-10 digit random string with number and alphabets
timestampyesint10 digit current unix timestamp
signyesstring see chapter 2.2

3 APIs

3.1 ORDER APIs

3.1.1 Order properties

Properties shown below are SUNMI order properties. Those are just for demonstration. Saas providers will need to provide their properties list to SUNMI.

The table below is the basic properties of an order. For specific orders, there will be more properties

order

groupparametertypedescriptionrequireduniquedescription
order basic infoorder_idstringorder idunique order id from saas provider
order_typeintorder typetype of the order ( 1-normal 2-refund 3-exchange 4-on hold 5-list 6-payment failed 7-canceled 8-etc
order_timeintorder timeorder timestamp
order_start_timeintorder start timestart time of the order
purchase_amountdouble(2-digit precision)total price
discount_amountdouble(2-digit precision)discount
received_amountdouble(2-digit precision) actual amount get
payment_typeintpayment type1-cash 2-alipay 3-wechat 4-qq 5-JD 6-debit cart 7-union pay QR code 8-etc
customer_countintcustomer countdefault 1
device infodevice_snstringdevice sn
software_namestringsoftware name
software_specstringsoftware specification
hardware_namestringhardware name of saas provider
hardware_specstringhardware specification
cashier_idstringcashier id
cashier_deskstringcashier desk
shop_assistant_idstringshop assistant id
order source infoorder_sourceintorder source1-offline 2-online (default 1)
membership infomember_idstringmember id
ali_idstringalipay id

wechat_open_idstringwechat open id
member_pointsdoublepoints

coupon infocoupon_idstringcoupon id
coupon_source intcoupon source1-
receipt inforeceipt_idstringreceipt id
sunmi_receipt_idstringsunmi receipt id
product infoproduct_liststring(form array[product])product list

see below

Product

parametertypedescriptionrequiredunique
idstringproduct id
namestringproduct name
seq_numstringproduct sequence number


bar_codestringbar code
specstringproduct spec
unitstringproduct unit
quantitydouble(3-digit precision)product quantity
stock_quantitydouble(3-digit precision)stock
category_idstringcategory id
category_namestringcategory name
original_pricedouble(2-digit precision)original price
present_pricedouble(2-digit precision)actual price
promote_amountdouble(2-digit precision)discount
subtotal_amountdouble(2-digit precision)subtotal

Additional parameters

additional parameterstypedescriptionrequiredunique
colorstringcolor code
sizestringsize code

3.1.2 Create order API

Description: This API is used for Saas provider to notify SUNMI when a new order is created. SUNMI store will save a copy of order in the database and provide some visualization of such order.

API Address:/order/create

API version:v2.0

Parameter

parameterrequiredtypedescriptionexample
sunmi_shop_no nostringSunmi shop number 100939070408
shop_idnostringsunmi shop id (used for version before v2.0. After v2.0, please use sunmi_shop_no10001
order_listyesstring(form of array)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”
}
]

Exmaple: 

  '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"
    }],
 }

Return value: 

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

Error Code:

error codeReason
5041invalid saas provider
5047illegal order

4 Return Value

4.1 Error types

Return value will be returned as part of the http response. If the sign validation failed, an HTTP code 401 will be returned. Otherwise, a http code of 200 will be returned

Rest of the error will be returned in the json response, normal response type will be:

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

4.2 Error codes

See error codes

5 Examples