Electronic Shelf Label – Sunmi Developer Docs

1. Background

SUNMI Store system is a store management system provided by SUNMI for merchants based on the IoT devices in stores.

As an open platform, SUNMI Store can do data interchange for third-party SaaS providers, including the interchange of product information, transaction information and membership system.

2. API Specifications

2.1 Protocol

All APIs use HTTPS Protocol with POST method.

Note: The size of the request body should be no more than 1 MB. If this size is exceeded, open platform will deny it.

Content-Type	application/x-www-form-urlencoded
return type	JSON
encoding	UTF-8
signing algorithms	MD5
signing rules	see chapter 2.2

2.2 Signing rules

see Authentication

2.3 common parameter

parameter	required	type	description
app_id	yes	string	unique identifier provided by SUNMI store open platform
random	yes	string	6-10 digit random string with number and alphabets
timestamp	yes	int	10 digit current unix timestamp
sign	yes	string	see chapter 2.2

3. Shop design

See Shop section

4. ESL APIs

4.1 Description

This set of APIs are used to manage the basic properties of the ESL.

4.2 API List

API address	Description
/device/esl/bind	bind an ESL to a shop
/device/esl/unbind	unbind an ESL from a shop
/device/esl/getList	get the list of ESLs from a shop
/device/esl/getInfo	get the detail info of a given ESL
/device/esl/pushImage	push an image to the ESL
/device/esl/flashLed	order the given ESL to flash its LED light
/device/esl/setRefreshTime	set the refresh rate of a given esl (unavailable yet)
/device/getOverview	get the overview of both a shop’s ESL and its AP

4.3 API detail

4.3.1 Bind an ESL to a shop

API description：By calling this API, user can bind his ESL to a given shop

API address：/device/esl/bind

Parameters：

parameter	required	type	description
shop_id	yes	string	The identifier of the shop in open platform
esl_code	no (either esl_code or esl_sn must be provided)	string	8-digit ID of the ESL
esl_sn	no (either esl_code or esl_sn must be provided)	string	Serial number of the ESL

Return Value：

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

Errors：

Error code	Description
5000	database error
5301	invalid ESL
5338	ESL already bounded

4.3.2 Unbind an ESL from a shop

API description：By calling this API, user can bind his ESL to a given shop

API address：/device/esl/unbind

Parameters：

parameter	required	type	description
shop_id	yes	string	The identifier of the shop in open platform
esl_id	yes	string	The unique ID from bind API

Return value：

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

Errors：

Error code	Description
5000	database error
5301	invalid ESL

4.3.3 Get the list of ESLs from a shop

API description：By calling this API, user can get the list of ESLs from a shop

API address：/device/esl/getList

Parameters：

parameters	required	type	description
shop_id	yes	string	The identifier of the shop in open platform
page_num	no (default 1)	int	current page
page_size	no (default 10)	int	The number of items per page

Return value：

{
  code: 0,
  msg: "succeed",
  data: {
    "total_count": 100,
    "esl_list": [{
      "esl_id": "129200",
      "esl_code": "SKDI39DN",
      "esl_sn": "B101194N00002",
      "model_name": "SL121+",
      "status": 2
    }, 
    .......
    ]
  }
}

Parameter Status:

status value	description
0	Not activated
1	Not binded
2	Waiting For Data
3	Push success
4	Push Failed

Errors：

Error Code	Description
5000	database error
5020	invalid parameter

4.3.4 Get the detail info of a given ESL

API description：By calling this API, user can get the detail info of a given ESL

API address：/device/esl/getInfo

Parameters：

parameter	required	type	description
shop_id	yes	string	The identifier of the shop in open platform
esl_code	no (either esl_code or esl_sn must be provided)	string	8-digit ID of the ESL
esl_id	no (either esl_code or esl_sn must be provided)	string	unique ID of the ESL

Return value：

{
  code: 0,
  msg: "succeed",
  data: {
    "esl_id": "1000",
    "esl_code": "SKDI39DN",
    "esl_sn": "B101194N00002",
    "model_name": "SL121+",
    "status": 2,
    "screen_size_name": "2.13寸",
    "software_version": "1.0.1",
    "battery": 90,
    "rssi": -23,
    "connect_time": 15683920394,
    "ap_id":  "10200",
    "ap_sn": "B201E95D00001",
     "ap_sn": "B201E95D00001",
  }
}

Parameter status

status value	description
0	Not activated
1	Not binded
2	Waiting For Data
3	Push Success
4	Push Failed

Errors:

error code	description
5000	database error
5023	parameter missing
5502	invalid ESL

4.3.5 Push an image to the ESL

API description：By calling this API, user can push an image to a given ESL

API address：/device/esl/pushImage

Parameters：

parameter	required	type	description
shop_id	yes	string	The identifier of the shop in open platform
esl_id	yes	string	The ID of the given ESL
pic	yes	file	The picture to be pushed

Note：

The color and the resolusion of the picture must meet the standard below, otherwise the ESL won’t be able to display that.

ESL type	color supported	picture size(px)
SL121	black, white, red	212 * 104
SL126	black, white, red	296 * 152
SL126+	black, white	296 * 152
SL142	black, white, red	400 * 300
SL142+	black, white, red	400 * 300

Return value：

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

Errors：

Error code	description
5004	system error
5005	invalid file
5020	invalid parameter
5300	invalid AP
5301	invalid ESL

4.3.6 Order the given ESL to flash its LED light

API description：By calling this API, user can order the given ESL to flash its LED light

API address：/device/esl/flashLed

Parameters：

parameter	required	type	description
shop_id	yes	string	The identifier of the shop in open platform
esl_id	yes	string	The ID of the given ESL
channel	no	int	LED color： 1-white， 2-blue， 4-green， 8- red, 512-cyan， 1024-purple， 2048-yellow（default 4）
cycle	no	int	The duration of a single flash, 1 cycle = 10ms. (default 100)
duration	no	int	The total flash times (default 8)

Return value：

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

Errors:

Error code	description
5000	database error
5301	invalid ESL

4.3.7 Set the refresh rate of a given esl

API description：By calling this API, user can set the refresh rate of a given esl. Currently this API is not available.

API address：/device/esl/setRefreshTime (unavailable yet)

Parameters：

parameter	required	type	description
shop_id	yes	string	The identifier of the shop in open platform
esl_code	no (either esl_code or esl_id must be provided)	string	8-digit ID of the ESL
esl_id	no (either esl_code or esl_id must be provided)	int	The unique ID of a given ESL
refresh_time	yes	int	refresh time in second

Return value：

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

4.3.8 Get the overview of both a shop’s ESL and its AP

API description：By calling this API, user can set the refresh rate of a given esl. Currently this API is not available.

API address：/device/getOverview

Parameters：

parameter	required	type	description
shop_id	yes	string	The identifier of the shop in open platform

Return value：

{
  code: 0,
  msg: "succeed",
  data: {
    "ap_total_count":24,
    "esl_total_count":55,
    "esl_pending_count":54,
    "esl_failed_count":3
  }
}

5. Access Point APIs

5.1 Description

The set of APIs used to manage the basic properties of the Access Points(AP)

5.2 API lists

API address	description
/device/ap/bind	bind an AP to a shop
/device/ap/unbind	unbind an AP from a shop
/device/ap/getList	get the List of APs from a shop
/device/ap/getInfo	get the info about a given AP
/device/ap/updateName	update the name of an AP
/device/ap/reboot	reboot a given AP
/device/ap/setScanTime	set the scan time of a given AP (currently unavailable)

5.3 API detail

5.3.1 Bind an AP to a shop

API description：By calling this API, user can bind an AP to a shop.

API address：/device/ap/bind

Parameters：

parameter	required	type	description
shop_id	yes	string	The identifier of the shop in open platform
ap_sn	yes	string	The serial number of an AP
ap_name	no	string	The name of an AP
ap_mac	no	string	The MAC Address of an AP

Return value：

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

Errors：

Error code	Description
5000	database error
5023	invalid parameter
5300	invalid AP
5339	AP already bound to a shop

5.3.2 Unbind an AP from a shop

API description：By calling this API, user can unbind an AP from a shop.

API address：/device/ap/unbind

Parameters：

parameter	required	type	description
shop_id	yes	string	The identifier of the shop in open platform
ap_id	yes	string	The ID of an AP

Return value：

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

Errors：

Error code	Description
5000	database error
5300	invalid AP

5.3.3 Get the List of APs from a shop

API description：By calling this API, user can get the List of APs of a shop.

API address：/device/ap/getList

Parameters：

parameter	required	type	description
shop_id	yes	string	The identifier of the shop in open platform
page_num	no	int	current page (default 1)
page_size	no	int	current items per page (default 10)

返回值：

{
  code: 0,
  msg: "succeed", 
  data: {
    "total_count": 100,
    "ap_list": [{
      "ap_id": “1000”,
      "ap_sn": "B201E96500001",
      "ap_name": "Gate 5", 
      "esl_count": 1920,
      "status": 2
    },
    ......
  ]}
}

Return parameter status

status value	description
0	not activated
1	online
2	offline

Errors：

Error code	description
5000	database error
5020	invalid parameter

5.3.4 Get the info about a given AP

API description：By calling this API, user can get the info about a given AP.

API address：/device/ap/getInfo

Parameters：

parameter	required	type	description
shop_id	yes	string	The identifier of the shop in open platform
ap_id	yes	string	The ID of an AP

Return value：

{
  code: 0,
  msg: "succeed",
  data: {
    "ap_id": “1000”,
    "ap_sn": "B201E96500001",
    "ap_name": "Gate 5",
    "model_name": "SLAP1",
    "status": 2,
    "esl_count": 1920,
    "software_version": "1.0.1",
    "connect_time": 15683920394，
  }
}

Return parameter status

status value	description
0	not activated
1	online
2	offline

Errors：

Error code	description
5000	database error
5011	invalid model type
5300	invalid AP

5.3.5 Update the name of an AP

API description：By calling this API, user can update the name of an AP.

API address：/device/ap/updateName

Parameters：

parameter	required	type	description
shop_id	yes	string	The identifier of the shop in open platform
ap_id	yes	string	The id of an AP
ap_name	yes	string	The new name of this AP

Return value：

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

Errors：

Error code	Description
5000	database error
5300	invalid AP

5.3.6 Reboot the given AP

API description：By calling this API, user can reboot the given AP.

API address：/device/ap/reboot

Parameters：

parameter	required	type	description
shop_id	yes	string	The identifier of the shop in open platform
ap_id	yes	string	The ID of an AP

Return value：

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

Errors：

Error code	Descriptions
5000	database error
5300	invalid AP

5.3.7 Set the scan time of a given AP

API description：By calling this API, user can set the scan time of a given AP.

API address：/device/ap/setScanTime (temporary unavailableq)

Parameters：

parameter	required	type	description
shop_id	yes	string	The identifier of the shop in open platform
ap_id	yes	string	The ID of an AP
scan_time	yes	int	The new scan time of the given AP

Return value：

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

6. Device update APIs

6.1 Description

This set of APIs are used to manage and update the firmware of ESL and AP.

6.2 API List

API address	description
/device/ap/firmware/getList	get the firmware info of APs by model
/device/ap/firmware/upgrade	update the firmware of APs
/device/esl/firmware/getList	get the firmware info of ESLs by model
/device/esl/firmware/upgrade	udpate the firmware of ESLs

6.3 API detail

6.3.1 Get the firmware info of APs by model

API description：By calling this API, user can get the firmware info of APs by model. If multiple versions of firmware are running on differents APs with same model type, only the latest version of firmware will be returned

API address：/device/ap/firmware/getList

Parameters：

parameter	required	type	description
shop_id	yes	string	The identifier of the shop in open platform
page_num	no	int	Current page (default 1) (currently unavailable)
page_size	no	int	Current items per page (default 10) (currently unavailable)

Return value：

{
  code: 0,
  msg: "succeed",
  data: {
    "total_count": 10,
    "ap_firmware_list": [{
      "model_name": "SLAP1",
      "software_version": "1.0.2",
      },
      ......
    ],
  }
}

Errors：

Error code	Description
5000	database error

6.3.2 Update the firmware of APs

API description：By calling this API, user can update the firmware of APs by model. This API is currently not available.

API address：/device/ap/firmware/upgrade (暂未开放)

Parameters：

parameter	required	type	description
shop_id	yes	string	The identifier of the shop in open platform

返回值：

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

6.3.3 Get the firmware info of ESLs by model

API description：By calling this API, user can Get the firmware info of ESLs by model. If multiple versions of firmware are running on differents ESLs with same model type, only the latest version of firmware will be returned

API address：/device/esl/firmware/getList

Parameters：

parameter	required	type	description
shop_id	yes	string	The identifier of the shop in open platform
page_num	no	int	current page (default 1) (currently not available)
page_size	no	int	current items per page (default 10) (currently not available)

Return value：

{
  code: 0,
  msg: "succeed",
  data: {
    "total_count": 10,
    "ap_firmware_list": [{
      "model_name": "SLAP1",
      "software_version": "1.0.2",
      },
      ......
    ],
  }
}

Errors：

Error code	Description
5000	database error

6.3.4 Update the firmware of ESLs

API description：By calling this API, user can update the firmware of ESLs by model. This API is currently not available.

API address：/device/esl/firmware/upgrade (currently unavailable)

Parameters：

parameter	required	type	description
shop_id	yes	string	The identifier of the shop in open platform

Return value：

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

7. Template management API

7.1 Description

The set of APIs used to manage the template

7.2 API list

API address	description
/template/create	create a new template
/template/update	update an existing template
/template/getList	get all template
/template/getInfo	get the detail of a given template
/template/delete	delete a template

7.3 API detail

7.3.1 Create a new template

API description：By calling this API, user can upload json and create a new template.

API address：/template/create

Parameters：

parameter	required	type	description
shop_id	yes	string	The identifier of the shop in open platform
template_name	yes	string	The name of the template
template_color	yes	int	The color type that the templates support: 1-black and white, 2- black white and red.
template_screen	yes	int	The screen size this template support (1 – 2.13 inch，2 – 2.6 inch，3 – 4.2 inch)
template_json	yes	string	The template JSON

Return value：

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

Errors：

Error code	Description
5000	database error
5005	file error
5343	invalid template
5346	template name already exists

7.3.2 Update a given template

API description：By calling this API, user can upload json and create a new template.

API address：/template/update

Parameters：

parameter	required	type	description
shop_id	yes	string	The identifier of the shop in open platform
template_id	yes	string	The ID of a template
template_name	no	string	The name of a template
template_json	no	string	Template JSON

Return value：

}

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

Errors：

Error code	Description
5000	database error
5005	file error
5343	invalid template
5346	template name already exists

7.3.3 Get all template

API description：By calling this API, user can get all templates.

API address：/template/getList

Parameters：

parameter	required	type	description
shop_id	yes	string	The identifier of the shop in open platform
page_num	no	int	current page
page_size	no	int	current items per page

Return value：

{
  code: 0,
  msg: "succeed",
  data: {
    "total_count": 15,
    "template_list":[{
      "template_id": "100",
      "template_name": "sample",
      "template_color": 1,  /* currently not available*/
      "template_screen": 1
    },
    .......
    ]
  }
}

Errors：

Error code	Description
5000	database error
5020	invalid parameters

Return parameter color:

color value	description
1	black and white
2	black, white and red

Return parameter screen:

screen value	description
1	2.13 inch
2	2.6 inch
3	4.2 inch

7.3.4 Get the detail of a given template

API description：By calling this API, user can get the detail of a given template.

API address：/template/getInfo

Parameters：

parameter	required	type	description
shop_id	yes	string	The identifier of the shop in open platform
template_id	yes	string	The unique ID of a template

Rerturn value：

{
  code: 0,
  msg: "succeed",
  data: {
    "template_name": "sample",
    "template_color_name": "BW",
    "template_screen_type_name": "2.6",
    "template_json": "...",
    "template_color:": 1, /* currently unavailable */
    "template _screen": 1, /* currently unavailable */
  }
}

Errors：

Error code	Description
5000	database error
5005	file error
5343	invalid template

Return parameter color:

color value	description
1	black and white
2	black white and red

Return parameter screen:

screen value	description
1	2.13 inch
2	2.6 inch
3	4.2 inch

7.3.5 Delete a template

API description：By calling this API, user can delete a given template.

API address：/template/delete

Parameters：

parameter	required	type	description
shop_id	yes	string	The identifier of the shop in open platform
template_id_list	yes	array	The unique ID of a template

Return value：

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

Errors：

Error code	Description
5000	database error

8. Product Management APIs

8.1 Description

This set of APIs is used to manage the price of the product and its relationship to the ESLs. After the relationship is set up, SUNMI store open platform will automatically update the changes of a product to the ESLs.

8.2 API list

API address	description
/product/bindEsl	bind a product to an ESL
/product/unbindEsl	unbind a product from an ESL
/product/getBindEslList	get the list of ESLs a product is bound to
/product/updateTemplate	update the template of a product
/product/getInfo	get the info of a product
/product/getList	get the list of all product

8.3 API detail

8.3.1 Bind a product to an ESL

API description：By calling this API, user can bind a product to an ESL

API address：/product/bindEsl

Parameters：

parameter	required	type	description
shop_id	yes	string	The identifier of the shop in open platform
product_id	yes	string	The unique ID of a product
esl_code	no (either esl_code or esl_sn must be provided)	string	8-digit ID of the ESL
esl_id	no (either esl_code or esl_sn must be provided)	string	The unique ID of a given ESL
template_id	yes	string	The unique ID of a template

Return value：

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

Errors：

Error code	Description
5000	database error
5020	invalid parameters
5015	invalid products
5343	invalid template
5300	invalid AP
5301	invalid ESL
5338	ESL already bounded to another shop
5342	invalid ESL image
5006	oss error

8.3.2 Unbind a product from an ESL

API description：By calling this API, user can unbind a product from an ESL

API address：/product/unbindEsl

Parameters：

parameter	required	type	description
shop_id	yes	string	The identifier of the shop in open platform
esl_code	no (either esl_code or esl_sn must be provided)	string	8-digit ID of the ESL
esl_id	no (either esl_code or esl_sn must be provided)	string	The unique ID of a given ESL

}

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

Errors：

Error code	Description
5000	database error
5020	invalid parameters
5301	invalid ESL
5320	ESL not bounded
5336	ESL bound to another shop
5342	invalid ESL image
5006	oss error

8.3.3 Get the list of ESLs

API description：By calling this API, user can unbind a product from an ESL

API address：/product/getBindEslList

Parameters：

parameter	required	type	description
shop_id	yes	string	The identifier of the shop in open platform
product_id	yes	string	The unique ID of a product

Return value：

{
  code: 0,
  msg: "succeed",
  data: {
    "esl_list": [{
      "esl_id": ”1000“,
      "esl_code": "DJKS90EN",
      "template_id": ”10002“,
      "status": 1,
      },
      .......
      ]
    }
  }
}

Errors：

Error code	description
5000	database error
5020	invalid parameters
5301	invalid ESL
5015	invalid product

8.3.4 Update the template of a product

API description：By calling this API, user can update the template of a product

API address：/product/updateTemplate

Parameters：

parameter	required	type	description
shop_id	yes	string	The identifier of the shop in open platform
product_id	yes	string	The unique id of the product
template_id	yes	string	The unique id of a template

Return value：

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

Errors：

Error code	description
5000	database error
5020	invalid parameter
5005	file error
5006	oss error
5343	invalid template
5015	invalid product
5342	invalid ESL image

8.3.5 Get product info

API description：By calling this API, user can get the product info of a specific product

API address：/product/getInfo

Parameters：

parameter	required	type	description
shop_id	yes	string	The identifier of the shop in open platform
product_id	yes	string	The unique ID of a product

Return value：

{
  code: 0,
  msg: "succeed",
  data: {
    "id":,
    "name":,
    "alias":,
    "seq_num":,
    "bar_code":,
    "qr_code":,
    "unit":,
    "spec":,
    "area":,
    "level":,
    "brand":, 
    "expire_time":,
    "price":,
    "promote_price":,
    "member_price":,
  }
}

Errors：

Error code	description
5000	database error
5015	invalid product id

8.3.6 Get product list

API description：By calling this API, user can get the product list of a given shop

API address：/product/getList

Parameters：

parameter	required	type	description
shop_id	yes	string	The identifier of the shop in open platform
keyword	no	string	searching keywords
page_num	no	int	page number
page_size	no	int	number of items per page

Return value：

{
  code: 0,
  msg: "succeed",
  data: {
    "total_count": 1,
    "product_list": [{
      "id": ,
      "name": ,
      "seq_num": ,
      "bar_code": ,
      "category_id": ,
      "price": ,
      "modified_time":
    }]
  }
}

Errors：

Error code	Description
5000	database error
5020	invalid parameters

9. Notifications

9.1 Description

After receiving the message from the device, SUNMI store open platform can push notification to the saas providers based on their need.

9.2 API specification

具体接口和实现标准，参考 015.消息推送中心