Product APIs – Sunmi Developer Docs

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.

ESL and other IoT devices are directly attached to the store’s products, prices and strategies, thus a basic product database framework is preserved in SUNMI Store. For data sources, users can choose either to edit on the page of SUNMI Store or to deal with the data on the third-party SaaS provider.

This document describes how to interchange the product information of the third-party SaaS provider, including how to synchronize the information (the merchant’s products and prices) between SaaS system and SUNMI Store in real-time after the initial interchange of product data.

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-Type	application/x-www-form-urlencoded
return type	JSON
encoding	UTF-8
signing algorithms	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 Product mapping

3.1.1 Parameters

The following parameters are for open platform APIs. The saas providers will need to provide their product properties list to create a mapping between their system and open platform’s system

parameter	type	description	required	saas system parameters
id	string	the id in sunmi database	yes
seq_num	string	product sequence number	no
bar_code	string	product bar code	no
name	string	product name	yes
alias	string	product alias	no
price	double	current product price	yes
promote_price	double	product promotion price	no
member_price	double	membership price	no
spec	string	specs for the product	no
unit	string	unit for the product	no
level	string	level of the product	no
area	string	area of the product	no
brand	string	brand of the product	no
qr_code	string	qr code url for the product	no
expire_time	int	product expire time	no

3.1.2 Create New Product

API description：This API is used after a saas system had created a new product to inform the open platform system about the change.

This API is for creating new products only, if the product ID exists, then this ID will be added into the exist_list. If the required parameter is not passed, then the id will be put into invalid_list and returned.

API address：/product/create （just for reference）

parameters：

parameter	required	type	description
shop_id	yes	string	the identifier of the shop in open platform
product_list	yes	array	array of product

product parameter：

parameter	required	type	description
id	yes	string	unique identifier of the product
seq_num	no	string	product sequence number
bar_code	no	string	product bar code
name	yes	string	product name
alias	no	string	product alias
price	no	double（non-negative ,2digit precision）	current selling price
promote_price	no	double（ non-negative ,2digit precision ）	promote price
member_price	no	double（ non-negative ,2digit precision ）	membership price
spec	no	string	product specs
unit	no	string	product unit
level	no	string	product level
area	no	string	product area
brand	no	string	product brand
qr_code	no	string	product qr code url
expire_time	no	int	product expire time

Return value：

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

Error list

Error code	description
5000	database error
5041	invalid saas provider
5015	invalid product

3.2.3 Update New Product

API description ： This API is used after a saas system had udpate a new product to inform the open platform system about the change.

Note that the update API will only update the existing product. If there are no such product, the product id will be returned in the not_exist_list.

Update API will only modify the existing properties of a product, if there are no such property in the system, then it will do nothing.

API address：/product/update（for reference only）

Parameter：

parameter	required	type	description
shop_id	yes	string	the identifier of a shop
product_list	yes	array	the list of product to be updated

product parameter：

parameter	required	type	description
id	yes	string	ID of the product
seq_num	no	string	sequence number of the product
bar_code	no	string	bar code of the product
name	no	string	name of the product
alias	no	string	alias of the product
price	no	double（ non-negative ,2digit precision ）	current price
promote_price	no	double（ non-negative ,2digit precision ）	promotion price
member_price	no	double（ non-negative ,2digit precision ）	membership price
spec	no	string	spec of the product
unit	no	string	unit of the product
level	no	string	level of the product
area	no	string	area of the product
brand	no	string	brand of the product
qr_code	no	string	QR code url of the product
expire_time	no	int	expiration time of the product

Return value:

{
    "code": 0,
    "msg": "succeed",
    "data": {
        "not_exist_list": [
            "5"
        ],
        "invalid_list": []
    }
}

Errors:

error code	description
5000	database error
5041	invalid saas provider
5015	invalid product

3.2.4 Delete Product

API description ： This API is used after a saas system had udpate a new product to inform the open platform system about the change.

The delete API will only delete the existing product in the open platform, if the open platform cannot match the product id, it will add this id to the not_exist_list and return.

API address：/product/delete（for reference only）

Parameters：

parameter	required	type	description
shop_id	yes	string	id of the shop
product_key_list	yes	list	list of product id to be deleted

Return value：

{
    "code": 0,
    "msg": "succeed",
    "data": {
        "not_exist_list": [
            "100"
        ]
    }
}

Error:

Error code	Description
5000	database error
5041	invalid saas provider
5015	invalid product

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": "succeed",
    "data": {}
}

4.2 Error Code List

Please Refer to the Error Code List

５ Open API from the saas provider

In the process of creating product mapping, SUNMI store open platform might request the saas provider to provide the following API:

5.1 Get all products Information List

API description ： This API is used for SUNMI store open platform to get all product information from the saas provider. Note that for different saas provider the return data structure can be different.

API address：https://example.SaaS.com/api/getProductList（for reference only）

Parameters：

parameter	required	type	description
shop_id	yes	string	id of the shop
page_num	yes	int	current page number
page_size	yes	int	number of items returned per request

Return value：

{
    "code": 0,
    "msg": "succeed",
    "data": {
        "total": 2,
        "product_list": [
            {
                "name": "example_product",
                "seq_num": "28929380903",
                "price": 10.00,
            }, ...
        ]
    }
}

6 Examples

This chapter offers some examples for creating the product mapping.

The API below requires the shop mapping done to work. For shop mappings please see shop API

The sample paramater we use (we have skipped the sign, random, etc. parameters for reader’s convenience)：

app_id	secret_key	shop_id
APPID6917LTY	tokenlty123	7948

As shown below, after the initial shop mapping, there are not products in the list.

6.1 Example to create new product

6.1.1 Success example

After successfulling creating the shop binding, user will need to call product/create to create product on open platform

Parameters：

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″}]

Return value：

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

After refreshing the page, we can see that we successfully created a product.

Click Details for the product detail.

6.1.2 Failed Example: product already existed

Resend the same request in 6.1.1, we can find the product_id in the exist list, telling us this product already existed

Parameters：

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″}]

Return value：

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

6.1.3 Failed Example: invalid JSON

In this example we put an invalid JSON in the request body

Parameter:

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″}]

Return value:

{
    "code": 1,
    "msg": "product_list: JSON.parse error"
}

6.1.4 Failed Example: missing required field

In this request, the request body is missing parameter id

Parameters：

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″}]

Return value：

{
    "code": 1,
    "msg": "invalid saas product info"
}

6.2 Example to update an existing product

6.2.1 Success example – update the existing product

Requesting the product/update API to update the price of a product

Parameters：

app_id	APPID6917LTY
shop_id	7948
product_list	[{“id”:1, “price”:”3.5″}]

Return value：

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

In the sunmi store page, we can see that the price has already been changed and the update time is recorded.

before

after

6.2.2 Success example – create a new product

The update API can also be used to create a product that doesn’t exist.

Parameters：

app_id	APPID6917LTY
shop_id	7948
product_list	[{“id”:2, “name”:”Non-Exist Product”,”seq_num”:”nonexist1″,”price”:”58.2″}]

Return value：

{
    "data": {
        "not_exist_list": [
            "2"
        ],
        "invalid_list": []
    },
    "code": 0,
    "msg": "succeed"
}

The return value shows that the product with id “2” does not exist, so it created an item with product id 2.

before

after

6.2.3 Failed Example: invalid JSON

In this example we put an invalid JSON in the request body

Parameters：

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″}]

Return value：

{
    "code": 1,
    "msg": "product_list: JSON.parse error"
}

6.2.4 Failed Example: missing required field

In this request, the request body is missing parameter id

Parameters：

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″}]

Return value：

{
    "code": 1,
    "msg": "invalid saas product info"
}

6.3 Example to delete an existing product

6.3.1 Success example

Requesting product/delete API to delete an existing product.

Parameters：

app_id	APPID6917LTY
shop_id	7948
product_key_list	[2]

Return value：

{
    "data": {
        "not_exist_list": []
    },
    "code": 0,
    "msg": "succeed"
}

In the product list, we can see that the product has already been deleted.

before

after

6.3.2 Failed Example: invalid product

In this request we tried to delete a product that does not exist

Parameters：

app_id	APPID6917LTY
shop_id	7948
product_key_list	[3]

Return value：

{
    "data": {
        "not_exist_list": [
            "3"
        ]
    },
    "code": 0,
    "msg": "succeed"
}