Electronic Shelf Label(ESL)

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-Typeapplication/x-www-form-urlencoded
return type JSON
encodingUTF-8
signing algorithmsMD5
signing rules see chapter 2.2

2.2 Signing rules

see Authentication

2.3 common parameter

parameterrequiredtypedescription
app_idyesstring unique identifier provided by SUNMI store open platform
randomyesstring 6-10 digit random string with number and alphabets
timestampyesint 10 digit current unix timestamp
signyesstring 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 addressDescription
/device/esl/bindbind an ESL to a shop
/device/esl/unbindunbind an ESL from a shop
/device/esl/getListget the list of ESLs from a shop
/device/esl/getInfoget the detail info of a given ESL
/device/esl/pushImagepush an image to the ESL
/device/esl/flashLedorder the given ESL to flash its LED light
/device/esl/setRefreshTimeset the refresh rate of a given esl (unavailable yet)
/device/getOverviewget 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

parameterrequiredtypedescription
shop_idyesstring The identifier of the shop in open platform
esl_codeno (either esl_code or esl_sn must be provided)string8-digit ID of the ESL
esl_snno (either esl_code or esl_sn must be provided)stringSerial number of the ESL

Return Value: 

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

Errors:

Error codeDescription
5000database error
5301invalid ESL
5338ESL already bounded
5041invalid saas provider

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

parameterrequiredtypedescription
shop_idyesstringThe identifier of the shop in open platform
esl_idyesstringThe unique ID from bind API

Return value: 

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

Errors:

Error codeDescription
5000database error
5301invalid ESL
5041invalid saas provider

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

parametersrequiredtypedescription
shop_idyesstringThe identifier of the shop in open platform
page_numno (default 1)intcurrent page
page_sizeno (default 10)intThe 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 valuedescription
0Not activated
1Not binded
2Waiting For Data
3Push success
4Push Failed

Errors:

Error CodeDescription
5000database error
5020invalid parameter
5041invalid saas provider

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:

parameterrequiredtypedescription
shop_idyesstringThe identifier of the shop in open platform
esl_code
no (either esl_code or esl_sn must be provided)string8-digit ID of the ESL
esl_idno (either esl_code or esl_sn must be provided)stringunique 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 valuedescription
0Not activated
1Not binded
2Waiting For Data
3Push Success
4Push Failed

Errors:

error codedescription
5000database error
5023parameter missing
5502invalid ESL
5041invalid saas provider

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:

parameterrequiredtypedescription
shop_idyesstringThe identifier of the shop in open platform
esl_idyesstringThe ID of the given ESL
picyesfileThe 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 typecolor supportedpicture size(px)
SL121black, white, red212 * 104
SL126black, white, red296 * 152
SL126+black, white296 * 152
SL142black, white, red400 * 300
SL142+black, white, red400 * 300

Return value: 

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

Errors:

Error codedescription
5004system error
5005invalid file
5020invalid parameter
5300invalid AP
5301invalid ESL
5041invalid saas provider

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

parameterrequiredtypedescription
shop_idyesstringThe identifier of the shop in open platform
esl_idyesstringThe ID of the given ESL
channelnointLED color: 1-white, 2-blue, 4-green, 8- red, 512-cyan, 1024-purple, 2048-yellow(default 4)
cyclenointThe duration of a single flash, 1 cycle = 10ms. (default 100)
durationnointThe total flash times (default 8)

Return value: 

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

Errors:

Error codedescription
5000database error
5301invalid ESL
5041invalid saas provider

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

parameterrequiredtypedescription
shop_idyesstringThe identifier of the shop in open platform
esl_code
no (either esl_code or esl_id must be provided)string8-digit ID of the ESL
esl_idno (either esl_code or esl_id must be provided)intThe unique ID of a given ESL
refresh_timeyesintrefresh 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:

parameterrequiredtypedescription
shop_idyesstringThe 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 addressdescription
/device/ap/bindbind an AP to a shop
/device/ap/unbindunbind an AP from a shop
/device/ap/getListget the List of APs from a shop
/device/ap/getInfoget the info about a given AP
/device/ap/updateNameupdate the name of an AP
/device/ap/rebootreboot a given AP
/device/ap/setScanTimeset 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:

parameterrequiredtypedescription
shop_idyesstringThe identifier of the shop in open platform
ap_snyesstringThe serial number of an AP
ap_namenostringThe name of an AP
ap_macnostringThe MAC Address of an AP

Return value: 

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

Errors:

Error codeDescription
5000database error
5023invalid parameter
5300invalid AP
5339AP already bound to a shop
5041invalid saas provider

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

parameterrequiredtypedescription
shop_idyesstringThe identifier of the shop in open platform
ap_idyesstringThe ID of an AP

Return value: 

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

Errors:

Error codeDescription
5000database error
5300invalid AP
5041invalid saas provider

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:

parameterrequiredtypedescription
shop_idyesstringThe identifier of the shop in open platform
page_numnointcurrent page (default 1)
page_sizenointcurrent 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 valuedescription
0not activated
1online
2offline

Errors:

Error codedescription
5000database error
5020invalid parameter
5041invalid saas provider

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

parameterrequiredtypedescription
shop_idyesstringThe identifier of the shop in open platform
ap_idyesstring 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 valuedescription
0not activated
1online
2offline

Errors:

Error codedescription
5000database error
5011invalid model type
5300invalid AP
5041invalid saas provider

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

parameterrequiredtypedescription
shop_idyesstringThe identifier of the shop in open platform
ap_idyesstringThe id of an AP
ap_nameyesstringThe new name of this AP

Return value: 

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

Errors:

Error codeDescription
5000database error
5300invalid AP
5041invalid saas provider

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

parameterrequiredtypedescription
shop_idyesstringThe identifier of the shop in open platform
ap_idyesstringThe ID of an AP

Return value: 

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

Errors:

Error codeDescriptions
5000database error
5300invalid AP
5041invalid saas provider

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

parameterrequiredtypedescription
shop_idyesstringThe identifier of the shop in open platform
ap_idyesstringThe ID of an AP
scan_timeyesintThe 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 addressdescription
/device/ap/firmware/getListget the firmware info of APs by model
/device/ap/firmware/upgradeupdate the firmware of APs
/device/esl/firmware/getListget the firmware info of ESLs by model
/device/esl/firmware/upgradeudpate 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:

parameterrequiredtypedescription
shop_idyesstringThe identifier of the shop in open platform
page_numnointCurrent page (default 1) (currently unavailable)
page_sizenointCurrent 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 codeDescription
5000database error
5041invalid saas provider

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

parameterrequiredtypedescription
shop_idyesstringThe 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

parameterrequiredtypedescription
shop_idyesstringThe identifier of the shop in open platform
page_numnointcurrent page (default 1) (currently not available)
page_sizenointcurrent 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 codeDescription
5000database error
5041invalid saas provider

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

parameterrequiredtypedescription
shop_idyesstringThe 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 addressdescription
/template/createcreate a new template
/template/updateupdate an existing template
/template/getListget all template
/template/getInfoget the detail of a given template
/template/deletedelete 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

parameterrequiredtypedescription
shop_idyesstringThe identifier of the shop in open platform
template_nameyesstringThe name of the template
template_coloryesintThe color type that the templates support: 1-black and white, 2- black white and red.
template_screenyesintThe screen size this template support (1 – 2.13 inch,2 – 2.6 inch,3 – 4.2 inch)
template_jsonyesstringThe template JSON

Return value: 

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

Errors:

Error codeDescription
5000database error
5005file error
5343invalid template
5346template name already exists
5041invalid saas provider

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

parameterrequiredtypedescription
shop_idyesstringThe identifier of the shop in open platform
template_idyesstring
The ID of a template
template_namenostringThe name of a template
template_jsonnostringTemplate JSON

Return value: 

}

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

Errors:

Error codeDescription
5000database error
5005file error
5343invalid template
5346template name already exists
5041invalid saas provider

7.3.3 Get all template

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

API address:/template/getList

Parameters

parameterrequiredtypedescription
shop_idyesstringThe identifier of the shop in open platform
page_numnointcurrent page
page_sizenointcurrent 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 codeDescription
5000database error
5020invalid parameters
5041invalid saas provider

Return parameter color:

color valuedescription
1black and white
2black, white and red

Return parameter screen:

screen valuedescription
12.13 inch
22.6 inch
34.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

parameterrequiredtypedescription
shop_idyesstringThe identifier of the shop in open platform
template_idyesstringThe 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 codeDescription
5000database error
5005file error
5343invalid template
5041invalid saas provider

Return parameter color:

color valuedescription
1black and white
2black white and red

Return parameter screen:

screen valuedescription
12.13 inch
22.6 inch
34.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

parameterrequiredtypedescription
shop_idyesstring The identifier of the shop in open platform
template_id_listyesarrayThe unique ID of a template

Return value: 

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

Errors:

Error codeDescription
5000database error
5041invalid saas provider

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 addressdescription
/product/bindEslbind a product to an ESL
/product/unbindEslunbind a product from an ESL
/product/getBindEslListget the list of ESLs a product is bound to
/product/updateTemplateupdate the template of a product
/product/getInfoget the info of a product
/product/getListget 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

parameterrequiredtypedescription
shop_idyesstringThe identifier of the shop in open platform
product_idyesstringThe unique ID of a product
esl_codeno (either esl_code or esl_sn must be provided)string8-digit ID of the ESL
esl_idno (either esl_code or esl_sn must be provided)stringThe unique ID of a given ESL
template_idyesstringThe unique ID of a template

Return value: 

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

Errors:

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

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

parameterrequiredtypedescription
shop_idyesstringThe identifier of the shop in open platform
esl_codeno (either esl_code or esl_sn must be provided)string 8-digit ID of the ESL
esl_idno (either esl_code or esl_sn must be provided)stringThe unique ID of a given ESL

}

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

Errors:

Error codeDescription
5000database error
5020invalid parameters
5301invalid ESL
5320ESL not bounded
5336ESL bound to another shop   
5342invalid ESL image
5006oss error
5041invalid saas provider

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

parameterrequiredtypedescription
shop_idyesstringThe identifier of the shop in open platform
product_idyesstringThe 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 codedescription
5000database error
5020invalid parameters
5301invalid ESL
5015invalid product
5041invalid saas provider

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

parameterrequiredtypedescription
shop_idyesstringThe identifier of the shop in open platform
product_idyesstringThe unique id of the product
template_idyesstring
The unique id of a template

Return value: 

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

Errors:

Error codedescription
5000database error
5020invalid parameter
5005file error
5006oss error
5343invalid template
5015invalid product
5342invalid ESL image
5041invalid saas provider

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

parameterrequiredtypedescription
shop_idyesstringThe identifier of the shop in open platform
product_idyesstringThe 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:Success is 0, failure is 1(see failure reasons for details)

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

parameterrequiredtypedescription
shop_idyesstringThe identifier of the shop in open platform
keywordnostringsearching keywords
page_numnointpage number
page_sizenointnumber 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:Success is 0, failure is 1(see failure reasons for details)

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.消息推送中心