Product 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.

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-Typeapplication/x-www-form-urlencoded
return typeJSON
encodingUTF-8
signing algorithmsMD5
signing rulessee chapter 2.2

2.2 Signing rules

see Authentication

2.3 common parameter

parameterrequiredtypedescription
app_idyesstringunique identifier provided by SUNMI store open platform
randomyesstring6-10 digit random string with number and alphabets
timestampyesint10 digit current unix timestamp
signyesstringsee 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
id string Database ID Yes
seq_num string Product ID, User-defined   
bar_code string Barcode   
name string Name Yes
alias string Alias   
price double Price Yes
promote_price double Promotion Price   
member_price double Member Price   
spec string Specification   
unit string Unit   
level string Level   

extra_price_info

Parameter Type Description Required
custom_price1 float64 Custom Price 1   
custom_price2 float64 Custom Price 2   
custom_price3 float64 Custom Price 3   
custom_price1_description string Custom Price 1 Description   
custom_price2_description string Custom Price 2 Description   
custom_price3_description string Custom Price 3 Description   
promote_start_date datetime Promotion Start Date   
promote_end_date datetime Promotion End Date   
member_promote_start_date datetime Member Promotion Start Date   
member_promote_end_date datetime Member Promotion End Date   
member_point float64 Member Point   
promote_reason string Promotion Reason   
promote_flag int Promotion Flag   

extra_info:

Parameter Type Description Required
pack_size int Pack Size   
stock float64 Stock   
safety_stock float64 Safety Stock   
daily_mean_sales float64 Daily Mean Sales   
today_sales_qty float64 Today Sales   
cumulated_sales_qty float64 Cumulative Sales   
on_order_qty float64 On Order Qty   
shelf_qty float64 Shelf Qty   
shelf_code string Shelf Code   
shelf_tier string Shelf Tier   
shelf_column string Shelf Column   
display_location string Shelf Location   
supprlier_code string Supplier Code   
supplier_name string Supplier   
manufacturer string Manufacturer   
manufacturer_address string Manufacturer Address   
expiry_date datetime Expiry Date   
storage_life string Storage life   
shelf_life int Shelf Life   
ingredient_table string Ingredient List   
fresh_item_code string Fresh Item Code   
supervised_by string Supervision Org   
supervision_hotline string Supervision Hotline  
pricing_staff string Pricing Staff  
category_level1_id int category_level1_id   
category_level2_id int category_level2_id   
category_level3_id int category_level3_id   
category_level4_id int category_level4_id   
category_level5_id int category_level5_id   
category_level1_name string category_level1_name   
category_level2_name string category_level2_name   
category_level3_name string category_level3_name   
category_level4_name string category_level4_name   
category_level5_name string category_level5_name   

extra_custom_info

Parameter Type Description Required
custom_text1 string Custom Text 1   
custom_text2 string Custom Text 2   
custom_text3 string Custom Text 3   
custom_text4 string Custom Text 4   
custom_text5 string Custom Text 5   
custom_text6 string Custom Text 6   
custom_text7 string Custom Text 7   
custom_text8 string Custom Text 8   
custom_text9 string Custom Text 9   
custom_text10 string Custom Text 10   
custom_text11 string Custom Text 11   
custom_text12 string Custom Text 12   
custom_text13 string Custom Text 13   
custom_text14 string Custom Text 14   
custom_text15 string Custom Text 15   
custom_text16 string Custom Text 16   
custom_text17 string Custom Text 17   
custom_text18 string Custom Text 18   
custom_text19 string Custom Text 19   
custom_text20 string Custom Text 20   
custom_int1 int Custom Int 1   
custom_int2 int Custom Int 2   
custom_int3 int Custom Int 3   
custom_int4 int Custom Int 4   
custom_int5 int Custom Int 5   
custom_dec1 float64 Custom Decimal 1   
custom_dec2 float64 Custom Decimal 2   
custom_dec3 float64 Custom Decimal 3   
custom_dec4 float64 Custom Decimal 4   
custom_dec5 float64 Custom Decimal 5   
others string Others   

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
sunmi_shop_no Yes string the identifier of the shop in open platform (in the 2.0 product APIs)
shop_id No string the identifier of the shop in open platform (in the old version APIs), it is replaced by sunmi_shop_no
product_list yes array  array of product

For the product parameters, please refer to 3.1.1.

Return value: 

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

Error list

Error codedescription
5000database error
5041invalid saas provider
5015invalid 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
sunmi_shop_no Yes string the identifier of the shop in open platform (in the 2.0 product APIs)
shop_id No string the identifier of the shop in open platform (in the old version APIs), it is replaced by sunmi_shop_no
product_list yes array  array of product

For the product parameters, please refer to 3.1.1.

Return value:

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

Errors:

error codedescription
5000database error
5041invalid saas provider
5015invalid 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
sunmi_shop_no Yes string the identifier of the shop in open platform (in the 2.0 product APIs)
shop_id No string the identifier of the shop in open platform (in the old version APIs), it is replaced by sunmi_shop_no
product_list yes array  array of product

Return value: 

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

Error:

Error codeDescription
5000database error
5041invalid saas provider
5015invalid 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

5 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_idsecret_keyshop_id
APPID6917LTYtokenlty1237948

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

5.1 Example to create new product

5.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_idAPPID6917LTY
shop_id7948
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.

5.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_idAPPID6917LTY
shop_id7948
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"
}

5.1.3 Failed Example: invalid JSON

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

Parameter:

app_idAPPID6917LTY
shop_id7948
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"
}

5.1.4 Failed Example: missing required field

In this request, the request body is missing parameter id

Parameters:

app_idAPPID6917LTY
shop_id7948
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"
}

5.2 Example to update an existing product

5.2.1 Success example – update the existing product

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

Parameters:

app_idAPPID6917LTY
shop_id7948
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

5.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_idAPPID6917LTY
shop_id7948
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

5.2.3 Failed Example: invalid JSON

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

Parameters:

app_idAPPID6917LTY
shop_id7948
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"
}

5.2.4 Failed Example: missing required field

In this request, the request body is missing parameter id

Parameters:

app_idAPPID6917LTY
shop_id7948
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"
}

5.3 Example to delete an existing product

5.3.1 Success example

Requesting product/delete API to delete an existing product.

Parameters:

app_idAPPID6917LTY
shop_id7948
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

5.3.2 Failed Example: invalid product

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

Parameters:

app_idAPPID6917LTY
shop_id7948
product_key_list[3]

Return value:

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