Guide on ESL Integration

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