Shop APIs

1.Background

The SUNMI Store Open Platform structure consists of 2 different units: merchant and store. Merchant is the basic unit to use the open platform. Users will be able to create mutilevels of stores to which the equipments belong. All products, membership information and face information from the equipments will be saved to the corresponding store. Additionally, if there are cooperation with other software service, a shop-to-shop mapping is needed first. After the mapping is established, the software service will be able to use the open store service.
The open platform supports 2 ways of creating the mapping: either the software service provide the API to create the mapping or the open platform will. The details of it will be provided in chapter 2.
All devices and data are aggregated based on the stores in SUNMI Store, which means that all devices are “bound” to a specified store. Meanwhile, users’ operation on devices and data are also based on stores. 
As shown below, there will be a multilevel shop system under 1 merchant. In this system, all data and device belongs to a specific shop.

If not specified, the parameter used to identify the store should be included in the parameters for all requests. Please see the table below:

parameterrequiredtypedescription
shop_idyesstringthe unique identifier for the shop in the saas provider

Note: the parameter shop_id is the unique identifier of a shop on the SaaS provider. Once it is determined, SUNMI Store open platform will use this ID for all request. Please refer to chapter 2 on how to map the shop to this unique identifier on SUNMI Store.

2. Mapping the shops

Before doing actual business on SUNMI store, the shop must on the saas provider must map themselves to the SUNMI store open platform. By mapping the shops to the correct shop_id, SUNMI store open platform will be able to recognize the shop to operate on.

There are currently 2 ways to do the mapping. The first will be requesting SUNMI store open platform API and the second one is requesting the API provided by the saas provider. User can do it either way.

2.1 Requesting the saas provider API

When users choose to do the mapping by requesting the saas provider API, they must be provided with the contents below:

  • The identifier of the shop, like the shop number, username and password
  • The HTTP API for the saas provider to validate the information above

After getting the information above, users can click the button 对接ERP to start the mapping.

Then the user can select the SaaS provider to do the mapping on the page below.

This image has an empty alt attribute; its file name is image2019-10-19_16-42-16.png

After clicking the button 保存 (Save), SUNMI Store will call the validation API provided by the SaaS provider to check if the information is valid. After the validation is passed, SUNMI Store open platform will record the shop information and the shop ID the user logged in with.

This image has an empty alt attribute; its file name is image2019-10-19_16-46-26.png

For all the request after, if the user pass the shop_id parameter in the request, it will automatically be done on the shop with this ID.

2.1.2 Saas Provider API Example

API description: this API is the request by by SUNMI Store open platform to validate the data provided by the user on SUNMI Store open platform to do the shop mapping.

For different saas provider, the identifier of a shop can be different and the way to validate the data should be discussed for each distinct saas provider. The example below use the shop id and the verification code as the identifier.

API link: https://example.SaaS.com/api/verifyShop (for reference only)

API parameters:

parameter requiredtypedescription
shop_idyesstringthe identifier for a shop in saas platform
verify_codeyesstringthe verification code for that shop id

Return body: (passed)

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

Return body: (error)

{
  code:0
  msg: "invalid verify code"
  data: {}
}

2.2 Requesting the open platform API

User can also do the shop mapping by requesting the SUNMI store open platform API.

First of all, user needs to register an account and create a merchant and a shop on SUNMI Store platform or SUNMI Assistant App. After creation, the user can obtain the API key by clicking on the menu on the left side: 基础数据 (basic data) → 门店管理 (store management) → 查看店铺信息 (check store info) to pop out the page below.

This image has an empty alt attribute; its file name is image2019-10-19_16-54-11.png
This image has an empty alt attribute; its file name is image2019-10-19_16-56-3.png

Click the 获取对接凭证 (get API key) to obtain the API key and the unique shop ID created by SUNMI Store system for the shop. To ensure the effectiveness and safety of the information, the interface voucher is valid for 24 hours, and a new API key can be obtained if the former one expired.

User can input the above two information to the saas provider shop mapping page to conduct verification through the shop mapping API provided by SUNMI Store open platform. For details, please refer to the API in chapter 4.

3. Mapping APIs

3.1 API Specifications

3.1.1 Protocol

All Open APIs are HTTP request with POST method only.

content-typeapplication/x-www-form-urlencoded
return data formatJSON
character encodingutf-8
signatureMD5
signing rulessee authentication

3.1.2 Signing rules

See Authentication

3.1.3 Common parameters

parameterrequiredtypedescription
app_idyesstringunique identifier provided by SUNMI store open platform
randomyesstring6-10 digits random string with numbers and alphabets.
timestampyesintcurrent 10 digit unix timestamp
sign yesstringsee 3.1.2

3.2 API list

API addressdescription
/shop/bindcreate a shop mapping
/shop/unbinddelete a shop mapping
/shop/updateupdate a shop mapping

3.3 API Details

3.3.1 Create a shop mapping

API description: users can create a shop mapping between SUNMI store open platform and the saas platform by calling this API.

API address: /shop/bind

Parameters:

parameterrequiredtypedescription
shop_idyesstringthe ID of the shop provided by the saas provider
shop_nameyesstringthe name of a shop
sunmi_shop_noyesstringthe shop number provided by the open platform.
sunmi_shop_keyyesstringthe API key mentioned in chapter 2.2
company_idyes stringThe unique ID of the merchant
company_nameyesstringthe name of a merchant
contact_personyesstringthe name of the contact person
phoneyesstring the phone number of the contact person
industry_idnointthe industry number of a shop
industry_namenostringthe industry name of a shop
provincenostringthe province of the shop’s location
citynostringthe city of the shop’s location
districtnostringthe disctrict of the shop’s location
addressnostring the address of the shop’s location
mailnostringthe mail address of the shop
formatnointStore format: 0 – None; 1 – pay before having meal; 2 – pay after having meal. 0 by default.
statusnointStore status: 1 – enabled; 2 – disabled; 1 by default

Return value:

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

Error:

Error codedescription
5000database error
5032invalid shop_id
5041invalid saas provider
5042shop already mapped
5043API key error

3.2.2 Delete a shop mapping

API description: users can delete a shop mapping between SUNMI store open platform and the saas platform by calling this API.

API address: /shop/unbind

Parameter:

parameterrequiredtypedescription
shop_idyesstringthe shop_id of the shop to be unmapped

Return value: 

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

Error:

Error codedescription
5032invalid shop_id
5041invalid saas provider
5000database error

3.2.3 Update a shop mapping

API description: users can update a shop mapping between SUNMI store open platform and the saas platform by calling this API. (Currently the contact name and contact phone cannot be changed)

API address: /shop/bind

Parameter:

parameterrequiredtypedescription
shop_idyesstringthe ID of the shop provided by the saas provider
shop_nameyesstringthe name of a shop
company_nameyesstringthe name of a merchant
industry_idnointthe industry number of a shop
industry_namenostringthe industry name of a shop
provincenostringthe province of the shop’s location
citynostringthe city of the shop’s location
districtnostringthe disctrict of the shop’s location
addressnostring the address of the shop’s location
mailnostringthe mail address of the shop
formatnointStore format: 0 – None; 1 – pay before having meal; 2 – pay after having meal. 0 by default.
statusnointStore status: 1 – enabled; 2 – disabled; 1 by default

Return value:

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

Error code:

error codedescription
5032invalid shop_id
5041invalid saas provider
5000database error

4. Merchant Mappings

For chain-stores, users need to manage multiple stores, the devices in stores and the data generated correspondingly. SUNMI Store open platform and the cooperative SaaS platform should create merchants mapping.

The API for mapping merchants are still developing

If there is merchant level setting in the cooperative SaaS platform, then when calling bindShop, the user can pass merchant ID and merchant name which can be used as the key to bind the merchant and the store for the interface (for aligning merchant) to come.

5. Appendix

Authentication

1.Background

Authentication is designed to ensure the security of all Open APIs of SUNMI store Open Platform. All HTTP Request in the SUNMI store Open Platform will be authenticated by the method described below. The content below describes how to pass the Sunmi store authentication and use its service.

2. Specification

2.1 Protocol

All open API in SUNMI store open platform uses HTTPS protocol with POST method.

2.2 Sign rules

SUNMI store open platform will distribute the following to all who uses our API:

  • app_id: the unique identifier of a user ( for some special API, the app_id can be skipped)
  • secret_key: the signing key of the user

The sign of the HTTP request will be generated from the parameters with the following rules:

  1. There must be a parameter named ‘random’, it is a random string combination of number and alphabets with the length of 6 to 10 digits.
  2. There must be a parameter named ‘timestamp’, it is the current 10-digit unix timestamp, for details please visit: https://tool.chinaz.com/tools/unixtime.aspx
  3. There must be a parameter named ‘app_id’
  4. Sort all parameter in the key’s alphabetic order. Create a string which concatenate all key-value pair in such order.
  5. Concatenate the user’s secret_key at the tail of the string. For details, please read the example
  6. use the MD5 signature of the string
  7. Convert the MD5 sign to all caps.

Example:

Suppose the parameter of the request is the following:

product_id: 389238
user_id: 29389
content: newproductmask
environment: test

Then, by the rules above, we can generate our sign below:

str1 = "app_id=2039dds&content=newproductmask&environment=test&product_id=389238&random=289192×tamp=1593029283&user_id=29389;
str2 = str1 + "&key=kdsofkdsnflke9382938k";
sign = MD5(str2).upper();

By the code above, our final request will contains the parameters below:

app_id:2039dds
product_id: 389238
user_id: 29389
content: newproductmask
environment: test
sign: IDKNFLK392038KDS932K
timestamp: 1593029283
random:289192

Sunmi Store Open Platform will check if the sign is valid, if the sign is invalid then it will return error code: 5090.
It will then check if the timestamp is within the reasonable time window, if the request is outdated, it will return error code: 5091.

3. Authentication Procedure

SUNMI Store Cloud Platform will conduct authentication in the following sequence. 

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 Code

Error CodeReason
0success
5090invalid sign
5091timestamp outdated