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 can help the user to digitize their shop. Based on the data from their shop such as face recognition and customer statistics along with the order info from saas provider, user could analyze their shops better.
This document describes how to exchange data with the third party saas provider to make sure SUNMI store open platform can get the order information from saas provider as soon as possible to do analysis.
2. API Specification
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-Type | application/x-www-form-urlencoded |
|---|---|
| return type | JSON |
| encoding | UTF-8 |
| signing algorithm | MD5 |
| signing rules | see chapter 2.2 |
2.2 Signing rules
see Authentication
2.3 Common parameter
| parameter | required | type | description |
|---|---|---|---|
| app_id | yes | string | unique identifier provided by SUNMI store open platform |
| random | yes | string | 6-10 digit random string with number and alphabets |
| timestamp | yes | int | 10 digit current unix timestamp |
| sign | yes | string | see chapter 2.2 |
3 APIs
3.1 Order APIs
3.1.1 Parameters
The following parameters are all for SUNMI store open platform and is used to explain APIs. Saas providers must provide the parameter of their own to make sure the order can be synced to open platform.
The parameters in the order below are the basics properties of an order, there will be more properties in real orders.
Order
| parameter | type | required | unique | description |
|---|---|---|---|---|
| order_no | string | ● | ● | the unique identifier of an order |
| order_type | int | ● | type of an order（1- normal order、 2- canceled， 3-exchanged for new product, 4- suspend，5-报表） | |
| order_time | int | ● | order timestamp | |
| order_start_time | int | the start time of an order | ||
| purchase_amount | double (2 digit precision) | ● | ||
| discount_amount | double (2 digit precision) | ● | ||
| received_amount | double (2 digit precision) | ● | ||
| payment_type | int | ● | 1-cash、2-alipay、3-wechat pay、4-QQpay、5-JD wallet、6-credit card、7-unionpay QR code、8-other | |
| customer_count | int | default 1 | ||
| device_sn | string | ● | ||
| software_name | string | |||
| software_spec | string | |||
| hardware_name | string | |||
| hardware_spec | string | |||
| cashier_no | string | |||
| cashier_disk | string | |||
| shop_assistant_no | string | |||
| order_source | int | 1-offline、 2-online (default offline) | ||
| member_no | string | |||
| ali_id | string | |||
| wechat_open_id | string | |||
| member_points | double | |||
| coupon_no | string | |||
| coupon_source | int | 1-shop，2-alipay， 3-wechat pay， 4-other | ||
| receipt_no | string | |||
| sunmi_receipt_no | string | |||
| product_list | array[product] | ● | see the list below |
product
| parameter | type | description | required |
|---|---|---|---|
| name | string | name of the product | ● |
| seq_num | string | sequence number of the product | |
| bar_code | string | bar code of the product | |
| spec | string | spec of the product | ● |
| unit | string | unit of the product | |
| quantity | double (3 digit precision) | sell quantity | ● |
| stock_quantity | double (3 digit precision) | stock quantity | |
| original_price | double (2 digit precision) | original price | ● |
| present_price | double (2 digit precision) | current price | ● |
| promote_amount | double (2 digit precision) | promotion price | ● |
| subtotal_amount | double (2 digit precision) | subtotal of this product | ● |
product additional properties for specific product
| parameter | type | description | required |
|---|---|---|---|
| color | string | code for color | |
| size | string | code for size |
3.1.2 Update order
API description: By requesting this API, the saas provider can notify the SUNMI store open platform that there is a new order in their system.
API address：/order/update（this is for reference, the detail of this API for each saas provider will be different and needed to be discussed）
Parameters：
| parameter | required | type | description |
|---|---|---|---|
| shop_id | yes | string | The identifier of the shop in open platform |
| order_list | yes | array | the list of order needed to be update |
Return value：
{
code: 0,
msg: "succeed",
data: {
"invalid_list": [
"CN0000938",
"CN0000939"
]
}
}Errors:
| Error code | Description |
| 5041 | invalid saas provider |
| 5047 | invalid order |
4 Return value
4.1 Error type
Error types will be returned in HTTP response. If the sign is invalid, then the http status code 401 will be returned.
If the sign is valid, then it will return HTTP status code 200 whatsoever, the error will be returned in the HTTP response body. The structure of our response body is normally:
{
code：0
msg: "success"
data: {}
} 4.2 Error list
see Error List
