Shop APIs

1 Introduction

Company and Store are included in the organization structure of SUNMI Store.

A company is the basic organization for a user to use SUNMI Store. All data and devices are attached to the corresponding company. Users can create stores of one to multi-level under one company.

All devices and data generated are organized per store, indicating all devices are “bound” to a specified store and a user can operate on the corresponding devices and data of a store.

If a 3rd party software needs to access to SUNMI devices and services, the alignment of the store on SUNMI Store platform (SUNMI store hereinafter) and the store on the 3rd party software (software store hereinafter), which is the basis of data integration, should be done first.

There are 2 methods to complete the binding:

  • A. The 3rd party software directly creates a company and store through openAPIs, and the binding will be completed automatically;
  • B. The 3rd party software initiates an action to bind an existing SUNMI store.

Please refer to 2.2 for details and choose as needed.

2 Methods and Steps

2.1 Method A

Register a SUNMI account with a mobile number (for clients in mainland China) or an email address (for clients in other areas) in SUNMI Assistant App or on https://store.sunmi.com (The API used to register SUNMI account is under development).

After completing the development (using the “app_id” and “secret_key” provided by SUNMI) of integration and obtaining an account, you can create a store under a company in the 3rd party software using the API “creating a company” and “creating a store”, the “sunmi_company_no” and “sunmi_shop_no” returned can be used as the unique company identifier and store identifier.

A store can be created while adding/binding a device or performing some actions, and the store created using this method will be automatically bound to the corresponding software store.

2.2 Method B

Register a SUNMI account in SUNMI Assistant App or on https://store.sunmi.com and create a company and stores.

After completing the development (using the “app_id” and “secret_key” provided by SUNMI) of integration and creating stores, get sunmi_shop_no and sunmi_shop_key in “Basic Data/Org Management/ Details”. For data effectiveness and safety purpose, the interfacing voucher is valid for 24 hours and can be re-acquired once expired.

Input the content of “app_id” and “secret_key” onto the specified page in the 3rd party software and verify through the binding API provided by SUNMI Store.

Note on shop_id and sunmi_shop_no:

Among the APIs of the current version, sunmi_shop_no is recommended to be used as the only identifier in replacement of shop_id, in order to organize data per store. For APIs of former versions, shop_id is still usable.

The correspondence of shop_id and sunmi_shop_no can be obtained through the API “getting the binding status of software store”.

3 Store Binding APIs

3.1 API Specification

3.1.1 Introduction

The openAPIs for integrating use HTTPS method only, and all messages uses POST method.

Content-Type application/x-www-form-urlencoded
Data Format Data is returned in JSON format
Character Encoding UTF-8
Signature Algorithm MD5
Sign Rules Please refer to openAPI – Authentication

3.1.2 Sign Rules

Please refer to OpenAPI – Authentication.

3.1.3 Common Parameters

Parameter Required Type Description
app_id Yes string The unique ID to identify the one who applies for interfacing. Contact SUNMI Store to get it.
random Yes string A 6-10 digits random character string constituted by numbers and letters.
timestamp Yes int The current unix timestamp (10-digit number) which is accurate to second.
sign Yes string Signature information. Please refer to the sign rules aforementioned for details.

3.2 The List of APIs for Store Binding

API Name API
Binding a SUNMI store /shop/bind
Unbinding a SUNMI store /shop/unbind
Updating the information of a store /shop/update
Creating a company /company/create
Getting the list of companies created in the 3rd party software /company/getList
Getting the information of a company created in the 3rd party software /company/getInfo
Creating a store /shop/create
Getting the list of software stores /shop/getList
Getting the information of a software store /shop/getInfo
Getting the binding status of a software store /shop/getBindInfo

3.3 Introduction to Each API

3.3.1 Binding a SUNMI Store

Description: by calling this API, you can bind a certain software store with a SUNMI store.

Request link: /shop/bind

API Parameters:

ParameterRequiredTypeDescription
shop_idYes string The ID of a software store. The shop_id of the 3rd party software and sunmi_shop_no are one-to-one correspondent. For all APIs of v2.0 and later versions, sunmi_shop_no is recommended to be the store ID. All APIs in which shop_id has been used as a parameter are compatible with later uses with no alteration needed.
company_id Yes string The ID of a company (a company should be one level higher than a store) in the 3rd party (hereinafter software company). The correspondence between a company and a store can be used as a reference to deal with the businesses on company level and the businesses across the stores of a company. If you have a company with more than one store, it is suggested that the company-store structure in the 3rd party software complies with the corresponding company-store structure on SUNMI Store.
shop_name Yes string The software store name.
company_name Yes string Company name.
sunmi_shop_no Yes string SUNMI store’s “Store ID”, which can be obtained in “Basic Data/Org Management/ Details”.
sunmi_shop_key Yes string SUNMI store’s “Store secret key” which can be obtained in “Basic Data/Org Management/ Details”.
contact_person Yes string Contact person.
phone Yes string Contact phone.
industry_id No int The ID indicating which industry the store falls into.
industry_name No string The name of the industry the store falls into.
province No string The province the store located
city No string The city the store located.
district No string The district/county the store located.
address No string Store address.
mail No string Contact email address.
format No int Store format: 0 – none, 1 – pay before dining, 2 – pay after dining. 0 by default.
status No int Store status: 1 – enabled, 2 – stopped. 1 by default.

Sample request:

  "method": "POST",
  "url": "https://store.uat.sunmi.com/openapi/shop/bind",
  "headers": {
    "Content-Type": "application/x-www-form-urlencoded"
  },
  formData: {
    "shop_id": "10096",
    "shop_name": "myShop",
    "sunmi_shop_no": "560279010307",
    "sunmi_shop_key": "MG4LJ5ERHUBDMF5XOOU8",
    "company_id": "10000",
    "company_name": "myCompany",
    "contact_person": "LiLei",
    "phone": "13166668888",
    "app_id": "LMWWQVTW4QGCC",
    "timestamp": 1581383983,
    "random": "5dsf6698",
    "sign": "33C18A18282733A71F998BB5A5E4319D"
  }

Return value:

{
    "code": 0,   /* Please refer to the error list for other errors */
    "msg": "succeed",
    "data": {}
}

Error list:

Error Code Cause
5000 Database error
5032 Illegal store
5041 Illegal 3rd party software
5042 The store in the 3rd party software has been bound
5043 SUNMI store’s “store key” error

3.3.2 Unbinding a SUNMI Store

Description: by calling this API, you can unbind a certain software store from a SUNMI store.

Request link: /shop/unbind

API Parameters:

Parameter Required Type Description
shop_id Yes string The software store ID you provided to SUNMI.
company_id No string The software company ID you provided to SUNMI.
sunmi_shop_no No string The “store nmber” of the SUNMI store.

Sample request:

  "method": "POST",
  "url": "https://store.uat.sunmi.com/openapi/shop/unbind",
  "headers": {
    "Content-Type": "application/x-www-form-urlencoded"
  },
  formData: {
    "shop_id": "10096",
    "app_id": "LMWWQVTW4QGCC",
    "timestamp": 1581383983,
    "random": "5dsf6698",
    "sign": "33C18A18282733A71F998BB5A5E4319D"
  }

Return value:

{
    "code": 0,   /* Please refer to the error list for other errors */
    "msg": "succeed",
    "data": {}
}

Error list:

Error Code Cause
5032 Illegal store
5041 Illegal 3rd party software
5000 Database error

3.3.3 Updating the Information of a Store

Description:

By calling this API, you can synchronize the data of the software store to the SUNMI store (contact person and phone number cannot be updated).

Request link: /shop/update

API parameters:

Parameter   Required   Type   Description
shop_id Yes string The software store ID you provided to SUNMI.
company_id No string The software company ID you provided to SUNMI.
sunmi_shop_no No string The “Store ID” of the SUNMI store.
shop_name No string Software store name.
company_name No string Software company name (if there is a company linked to the store, otherwise it is the store name).
industry_id No int The ID indicating which industry the store falls into.
industry_name No string The name of the industry the store falls into.
province No string The province the store located.
city No string The city the store located.
district No string The district/county the store located.
address No string Store address.
mail No string Contact email address.
format No int Store format: 1 – pay before dining, 2 – pay after dining.
status No int Store status: 1 – enabled, 2 – stopped.

Sample request: 

  "method": "POST",
  "url": "https://store.uat.sunmi.com/openapi/shop/update",
  "headers": {
    "Content-Type": "application/x-www-form-urlencoded"
  },
  formData: {
    "shop_id": "10096",
    "shop_name": "myShopNew",
    "company_name": "myCompanyNew",
    "app_id": "LMWWQVTW4QGCC",
    "timestamp": 1581383983,
    "random": "5dsf6698",
    "sign": "33C18A18282733A71F998BB5A5E4319D"
  }

Return value: 

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

Error list:

Error Code Cause
5032 Illegal store
5041 Illegal 3rd party software
5000 Database error

3.3.4 Creating a Company

Description: By calling this API, you can create a company in SUNMI Store and then create stores (one to multiple levels) under the company.

Request link: /company/create

API parameters:

Parameter Required Type Description Example
username Yes string Company admin account. Currently only the mobile phone number which has been registered in SUNMI Store is supported. The account and password generated through the user management API /user/register can also be used (please refer to User Library). 18625776000
company_name Yes string Company name. company_test
contact_person Yes string Contact person. xs
phone Yes string Contact phone. 13813807411
mail No string Contact email address. lei.li@outlook.com

Sample request:

  'method': 'POST',
  'url': 'https://store.uat.sunmi.com/openapi/company/create',
  'headers': {
    'Content-Type': 'application/x-www-form-urlencoded'
  },
  formData: {
    'app_id': 'APPID6917LTY',
    'timestamp': '1583299191',
    'random': '5dsf6698',
    'sign': 'A9D0BA14993A3222E7C7FB860D0C51A1',
    'company_name': 'company_test',
    'contact_person': 'xs',
    'phone': '13813807411',
    'username': '18625776000'
  }

Return value:

{
    "code": 0,   /* Please refer to the error list for other errors */
    "msg": "succeed",
    "data": {
        "sunmi_company_no": "476934507308"
    }
}

Error list

Error Code Cause
5010 Invalid admin user.
5000 Database error.
5041 Illegal Software
5035 Company name already exists.
5082 rpc call fails.

3.3.5 Getting the Company List Created by the 3rd Party Software

Description: By calling this API, you can check the list of companies which have been created in SUNMI Store through openAPI.

Request link: /company/getList

API version: v2.0

API parameters:

Parameter Required Type Description Example
username Yes string Company admin account. Currently only the mobile phone number which has been registered in SUNMI Store is supported. The account and password generated through the user management API /user/create, which is unavailable for now, can also be used in the future. 18625776000
page_num No (1 by default) int Current page number. 1
page_size No (10 by default) int The number of items on the current page. 10

Sample request:

  'method': 'POST',
  'url': 'https://store.uat.sunmi.com/openapi/company/getList',
  'headers': {
    'Content-Type': 'application/x-www-form-urlencoded'
  },
  formData: {
    'app_id': 'APPID6917LTY',
    'timestamp': '1583299623',
    'random': '5dsf6698',
    'sign': 'EDA422052152701EC2579F97BF068D18',
    'username': '18625776000'
  }

Return value:

{
    "code": 0,   /* lease refer to the error list for other errors */
    "msg": "succeed",
    "data": {
        "total_count": 3,
        "company_list": [
            {
                "sunmi_company_no": "476934507308",
                "username": "18625776000",
                "company_name": "company_test",
                "contact_person": "xs",
                "contact_tel": "13813807411",
                "contact_email": ""
            },
            {
                "sunmi_company_no": "476934506958",
                "username": "18625776000",
                "company_name": "xs_test_01",
                "contact_person": "xs",
                "contact_tel": "13813807411",
                "contact_email": ""
            },
            {
                "sunmi_company_no": "476934506957",
                "username": "18625776000",
                "company_name": "xs_test_02",
                "contact_person": "xs",
                "contact_tel": "13813807411",
                "contact_email": ""
            }
        ]
    }
}

Error list:

Error Code Cause
5000 Database error
5041 Illegal 3rd party software

3.3.6 Getting the company information created by the 3rd party software.

Description: By calling this API, you can check the information of companies which were created in SUNMI Store through openAPI.

Request link: /company/getInfo

API parameter:

Parameter Required Type Description Example
sunmi_company_no Yes string The unique SUNMI company ID. 476934507308

Sample request:

  'method': 'POST',
  'url': 'https://store.uat.sunmi.com/openapi/company/getInfo',
  'headers': {
    'Content-Type': 'application/x-www-form-urlencoded'
  },
  formData: {
    'app_id': 'APPID6917LTY',
    'timestamp': '1583300101',
    'random': '5dsf6698',
    'sign': 'F59845336C9492CE61BF63AA8F84B609',
    'sunmi_company_no': '476934507308'
  }

Return value:

{
    "code": 0,  /* Please refer to the error list for other errors */
    "msg": "succeed",
    "data": {
        "sunmi_company_no": "476934507308",
        "username": "18625776000",
        "company_name": "company_test",
        "contact_person": "xs",
        "contact_tel": "13813807411",
        "contact_email": ""
    }
}

Error list:

Error Code Cause
5000 Database error.
5033 Illegal sunmi company no.
5041 Illegal 3rd party software.

3.3.7 Creating a Store

Description:

By calling this API, you can create a store under a specified company in SUNMI Store by operating in the 3rd party software.

Request link: /shop/create

API parameters:

Parameter Required Type Description
shop_id Yes string The software store ID you provided.
company_id Yes string The software company ID you provided.
shop_name Yes string The software store name.
sunmi_company_no Yes string A unique SUNMI store ID which can be created and acquired through the openAPIs related to company or acquired on the SUNMI Store page Basic Management/Merchant Management.
sunmi_parent_shop_no No string No value needs to be assigned if a store is created directly under the current company, while a value (the parent store number) is needed if the store is created under another store. This parameter is empty by default.
contact_person Yes string Contact person.
phone Yes string Contact phone number.
industry_id No int The ID indicating the industry the store falls into.
industry_name No string The name of the industry the store falls into.
province No string The province the store located.
city No string The city the store located.
district No string The district/county the store located.
address No string Store address.
mail No string Contact email address.
format No int Store format: 0 – none; 1 – pay before dining; 2 – pay after dining. 0 by default.
status No int Store status: 1 – enabled; 2 – stopped; 1 by default.

Sample request:

  'method': 'POST',
  'url': 'http://store.dev.sunmi.com/openapi/shop/create',
  'headers': {
    'Content-Type': 'application/x-www-form-urlencoded'
  },
  formData: {
    'app_id': 'APPID6917LTY',
    'timestamp': '1583301592',
    'random': '5dsf6698',
    'sign': '4C0C0516EC44BE0022BE80CED28E2A45',
    'contact_person': 'xs',
    'phone': '18625776019',
    'sunmi_company_no': '476934507308',
    'company_id': '1000',
    'shop_id': '0001',
    'shop_name': 'shop_test'
  }

Return value:

{
    "code": 0,  /* Please refer to Error List for other errors */
    "msg": "succeed",
    "data": {
        "sunmi_shop_no": "803743210109"
    }
}

Error list:

Error Code Cause
5000 Database error.
5032 Illegal store.
5033 Illegal sunmi company no.
5041 Illegal 3rd party software.
5042 The 3rd party software store has already been bound.

3.3.8 Getting the List of Stores Created in the 3rd Party Software

Description: By calling this API, you can get the list of stores.

Request link: /shop/getList

API parameters:

Parameter Required Type Description Example
sunmi_company_no Yes string The unique ID of a SUNMI store. 476934507308
page_num No (1 by default) int The current page number. 1
page_size No (10 by default) int The number of items on the current page. 10

Sample request:

  'method': 'POST',
  'url': 'https://store.uat.sunmi.com/openapi/shop/getList',
  'headers': {
    'Content-Type': 'application/x-www-form-urlencoded'
  },
  formData: {
    'app_id': 'APPID6917LTY',
    'timestamp': '1583302143',
    'random': '5dsf6698',
    'sign': '98F0E7619590B36E5BA34B94E815A97C',
    'sunmi_company_no': '476934507308'
  }

Return value:

{
    "code": 0,     /* Please refer to Error List for other errors*/
    "msg": "succeed",
    "data": {
        "total_count": 1,
        "shop_list": [
            {
                "saas_shop": {
                    "company_id": "1000",
                    "shop_id": "0001",
                    "company_name": "company_test",
                    "shop_name": "shop_test",
                    "contact_person": "xs",
                    "phone": "13813807411",
                    "mail": "",
                    "industry_id": 0,
                    "industry_name": "",
                    "province": "",
                    "city": "",
                    "district": "",
                    "address": "",
                    "format": 0,
                    "status": 1
                },
                "sunmi_shop": {
                    "sunmi_shop_no": "803743210109",
                    "shop_name": "shop_test",
                    "contact_person": "xs",
                    "phone": "13813807411",
                    "mail": "",
                    "industry_id": 0,
                    "industry_name": "",
                    "province": "",
                    "city": "",
                    "district": "",
                    "address": "",
                    "format": 0,
                    "status": 1
                }
            }
        ]
    }
}

Error list:

Error Code Cause
5041 Illegal 3rd party software.
5000 Database error.
5033 Illegal sunmi company no.
5020 Illegal parameter.

3.3.9 Getting the Store information Created by the 3rd Party Software

Description: By calling this API, you can get the store information.

Request link: /shop/getInfo

API version: v2.0

API parameters:

Parameter Required Type Description Example
sunmi_shop_no Yes string The unique ID of a SUNMI store. 803743210109

Sample request:

  'method': 'POST',
  'url': 'https://store.uat.sunmi.com/openapi/shop/getInfo',
  'headers': {
    'Content-Type': 'application/x-www-form-urlencoded'
  },
  formData: {
    'app_id': 'APPID6917LTY',
    'timestamp': '1583302480',
    'random': '5dsf6698',
    'sign': 'FF37DC3C9563263BB97528AF0E065C9D',
    'sunmi_shop_no': '803743210109 '
  }

Return value:

{
    "data": {
        "saas_shop": {
            "company_id": "1000",
            "shop_id": "0001",
            "company_name": "company_test",
            "shop_name": "shop_test",
            "contact_person": "xs",
            "phone": "13813807411",
            "mail": "",
            "industry_id": 0,
            "industry_name": "",
            "province": "",
            "city": "",
            "district": "",
            "address": "",
            "format": 0,
            "status": 1
        },
        "sunmi_shop": {
            "sunmi_shop_no": "803743210109",
            "shop_name": "shop_test",
            "contact_person": "xs",
            "phone": "13813807411",
            "mail": "",
            "industry_id": 0,
            "industry_name": "",
            "province": "",
            "city": "",
            "district": "",
            "address": "",
            "format": 0,
            "status": 1
        }
    }
}

Error list:

Error Code Cause
5041 Illegal 3rd party software.
5000 Database error.
5032 Illegal store.

3.3.10 Getting the binding status of the store on the 3rd party software

Description: By calling this API, you can check the binding status between a software store and a SUNMI store.

Request link: /shop/getBindInfo

API parameters:

Parameter Required Type Description
shop_id Yes string The software store ID you provided to SUNMI.
company_id No string The software company ID you provided to SUNMI.

Sample request:

  'method': 'POST',
  'url': 'https://store.uat.sunmi.com/openapi/shop/getBindInfo',
  'headers': {
    'Content-Type': 'application/x-www-form-urlencoded'
  },
  formData: {
    'app_id': 'APPID6917LTY',
    'timestamp': '1583302789',
    'random': '5dsf6698',
    'sign': '8F889204B0600F25A4C121E6FF16D0D8',
    'shop_id': '0001'
  }

Return value (bound):

{
    "code": 0,   /* Please refer to Error list for other errors*/
    "msg": "succeed",
    "data": {
        "status": 1,   /* bound*/
        "bound_info": {
            "company_id": "1000",
            "shop_id": "0001",
            "sunmi_company_no": "476934507308",
            "sunmi_shop_no": "803743210109"
        }
    }
}

Return value (not bound):

{
    "code": 0,     /* Please refer to Error list for other errors*/
    "msg": "succeed"
    "data": {
        "status": 2,  /* not bound*/
        "bound_info": {
            "company_id": "",
            "shop_id": "",
            "sunmi_company_no": "",
            "sunmi_shop_no": ""
        }
    }