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