1 Introduction
SUNMI Electronic Shelf Label (ESL) can be used in supermarkets, warehouses, hospitals, meeting rooms and other scenarios to show product prices, stock information and attendee information, etc.
Users can directly manage ESLs on SUNMI Store open platform, but in some real cases, they need to interact their software system with SUNMI Store to send product information to SUNMI Store and manage the functionalities of ESLs in order to complete the final ESL integration.
To meet our clients’ needs and empower our partners, SUNMI Store provides ESL-related openAPIs to integrate ESLs with a 3rd party software in different levels.
SUNMI Store is available in 3 editions (SUNMI Cloud Edition, Private Cloud Version and Private Local Server Version), and APIs of different editions vary.
Note: This document is written to illustrate how to realize product information display, but it also can be a reference for more ESL uses in different scenarios.
2 Integration Process
1. Communication. After determining to use SUNMI openAPIs, please first read openAPI documents (on SUNMI Store) and discuss with SUNMI team on the level of integration, business process design, matters need attention, schedule and other matters through a messaging app.
2. Send the name of the software to be integrated with and email address to SUNMI technical support team which then will email parameters including app_id, secret_key and ESL App in the UAT environment to you.
3. Integration. SUNMI provides technical support through the messaging app.
4. Testing. Once the integration in UAT environment is completed, you can test by yourself and provide a test account for SUNMI to verify at the same time.
5. SUNMI sends the parameters in onl environment and complete integration in onl environment.
3 Levels of Integration
SUNMI Store provides multiple ESL-related openAPIs and you can integrate as needed.
Frankly speaking, we have set four integration levels, which are listed in the table below:
| Level | Object | Functionalities Realized |
| L1 | Product data | Integration at this level enables the synchronization of product data and store binding information. After successful integration, the 3rd party software uploads product data to the digital store or the digital store automatically acquires product data from the software. A managed ESL can automatically update its display with price modification in the third-party software. ESL management functions, such as ESL binding, ESL unbinding, and template editing, are only available in SUNMI Store and SUNMI Assistant App. |
| L2 | Basic operations | Based on L1 integration, L2 integrates ESL binding and unbinding APIs to the 3rd party software. After successful integration, basic operations, such as ESL binding and unbinding, can be performed in the 3rd party software directly. |
| L3 | Device | Based on L2 integration, L3 level allows the integration of specific device APIs to the 3rd party software. After successful integration, the third-party software supports basic ESL management operations, such as template switching, ESL flashing, and data repushing. Template editing and AP management functions are only available in SUNMI Store and SUNMI ESL App. |
| L4 | ESL management system | Based on L3 integration, L4 implements a comprehensive integration between the ESL system and the 3rd party software. After successful integration, all ESL management functions are available in the 3rd party software except the independent template Studio (login to the Studio is not required). SUNMI Store is not necessary for routine operations. |
L1 integration is sufficient in most cases, and some clients may need an L2 integration. Please thoroughly communicate on business scenarios before selecting any higher level integration.
4 APIs of Different Modules and Corresponding Documents
APIs are categorized in accordance with different modules, please refer to the modules and corresponding documents listed below.
| Module & Doc | Description |
| Authentication | It contains the general authentication rules of SUNMI Store, please read carefully before commencing development. |
| Shop APIs | SUNMI devices and services are managed per store under a company, please bind the store on SUNMI Store and the store on the 3rd party software before starting function integration. |
| Product APIs | It contains the APIs to add, delete and modify a product, which is included in the L1 integration. In addition to ESL, these APIs also can be used for other devices and services. |
| ESL APIs | It contains APIs to manage ESLs, what are included in the L2 integration and levels higher. |
5 APIs and Corresponding Modules
ESL-related openAPIs are categorized in accordance with modules, and you can combine different modules as needed.
APIs included in L1-L4 are listed below. Whether to enable some functions (e.g.: flash LED, upgrade, etc.) is up to your needs.
| Module | API name | API | L1 | L2 | L3 | L4 | Description |
| Store Binding | Binding a SUNMI store | /shop/bind | √ | √ | √ | Manually bind the store that has already been created on SUNMI Store. | |
| Unbinding a SUNMI store | /shop/unbind | √ | √ | √ | |||
| Updating store info | /shop/update | √ | √ | √ | |||
| Creating a company | /company/create | √ | The company and store created through this API are automatically bound. | ||||
| Getting software company list | /company/getList | √ | |||||
| Getting software company info | /company/getInfo | √ | |||||
| Creating a store | /shop/create | √ | |||||
| Getting software store list | /shop/getList | √ | |||||
| Getting software store info | /shop/getInfo | √ | |||||
| Getting the binding status a software store | /shop/getBindInfo | Search the corresponding store information thorough shop_id. | |||||
| Product APIs | Creating a product | /product/create | √ | √ | √ | √ | |
| Updating a product | /product/update | √ | √ | √ | √ | This API can also be used to create a product. | |
| Deleting a product | /product/delete | √ | √ | √ | √ | ||
| Getting all software product info | api/getProductList | An API you provided to SUNMI to pull all product information from the 3rd party software. | |||||
| ESL – Product | Binding an ESL with a product | /product/bindEsl | √ | √ | √ | Bind ESL, product and template. After binding, the display will be updated and the ESL will be bound to a store. | |
| Unbinding an ESL from a product | /product/unbindEsl | √ | √ | √ | |||
| Getting the list of ESLs bound to a product | /product/getBindEslList | √ | √ | More than one ESL can be included. | |||
| Modifying the ESL template bound to a product | /product/updateTemplate | ESL ID, template. | |||||
| Getting product list | /product/getList | √ | √ | ||||
| Getting product information | /product/getInfo | √ | √ | ||||
| ESL – shelf label | Adding an ESL to a store | /device/esl/bind | This is only used to add an ESL to a store (binding it to a product is not included). | ||||
| Removing an ESL from a store | /device/esl/unbind | √ | √ | Only the ESL that has been unbound can be removed. | |||
| Getting ESL list | /device/esl/getList | √ | √ | ESL status is included. | |||
| Getting ESL info | /device/esl/getInfo | √ | √ | Get basic information, bind to products or use templates through ESL ID. | |||
| Pushing a certain image to an ESL | /device/esl/pushImage | The 3rd party software can generate and push images to ESLs (there is a limit to image size). | |||||
| Getting overview statistics | /device/getOverview | √ | √ | The number of ESLs in the system, the number of products and the number of each push status. | |||
| ESL – flash LED | Flashing an ESL‘s LED | /device/esl/flashLed | √ | √ | Flash certain ESL’s LED in a certain way. | ||
| ESL – AP | Getting AP list | /device/ap/getList | √ | Please bind an AP using ESL App. | |||
| Getting AP info | /device/ap/getInfo | √ | |||||
| Changing AP info | /device/ap/updateName | √ | |||||
| Restarting an AP | /device/ap/reboot | √ | |||||
| ESL – template | Uploading a newly created template | /template/create | √ | Upload the json file you created in the independent template Studio to the ESL system. | |||
| Updating a specified template | /template/update | √ | |||||
| Getting template list | /template/getList | √ | |||||
| Getting template info | /template/getInfo | √ | |||||
| Deleting a template | /template/delete | √ |
6 Develop Environments
SUNMI Store runs in more than one environment. Developing and jointly debugging in uat environment is recommended, and release it to onl environment after the joint debugging has been completed.
| Environment | SUNMI Store Web Address | API Address | Sample API |
| uat | https://store.uat.sunmi.com/ | https://store.uat.sunmi.com/openapi/ | https://store.uat.sunmi.com/openapi/product/update |
| onl | https://store.sunmi.com/ | https://store.sunmi.com/openapi/ | https://store.sunmi.com/openapi/product/update |
