云打印机CP事件及消息示例

1 事件列表

event取值	说明
6001	未经处理的文字小票上传消息
6002	未经处理的图片小票上传消息
6003	经过处理的小票消息

2 事件消息示例

2.1 未经处理的文字小票上传消息(event=6001)

{
  "id": 123,     // 系统生成的小票ID
  "sn": "sn",    // 打印设备SN
  "text": "abc"  // 文字小票内容
}

2.2 未经处理的图片小票上传消息 (event=6002)

{
  "id": 123,  // 系统生成的小票ID
  "sn": "sn", // 打印设备SN
  "base64_image": "avc"  // 图片小票的base64 encoded string
}

2.3 经过处理的小票消息 (event=6003)

{
  "id": 123,  // 系统生成的小票ID
  "sn": "sn",  // 打印设备SN
  "order_id": 456, // 小票上的订单ID
  "order_time": "2020-01-01", // 小票生成时间
  "total_payment": 10.11  // 小票金额
  "sales_detail_list": [{   //明细列表
    "amount": 10,          // 商品单价
    "item":   "商品",      // 商品名字
    "quantity": 1          // 商品数量
  },
  ...
  ]
}

Order APIs

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.

Multiple SUNMI IOT device can help the user to digitize their shop. Based on the data from their shop such as face recognition and customer statistics along with the order info from saas provider, user could analyze their shops better.

This document describes how to exchange data with the third party saas provider to make sure SUNMI store open platform can get the order information from saas provider as soon as possible to do analysis.

2. API Specification

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 algorithm	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 APIs

3.1 Order APIs

3.1.1 Parameters

The following parameters are all for SUNMI store open platform and is used to explain APIs. Saas providers must provide the parameter of their own to make sure the order can be synced to open platform.

The parameters in the order below are the basics properties of an order, there will be more properties in real orders.

Order

parameter	type	required	unique	description
order_no	string	●	●	the unique identifier of an order
order_type	int	●		type of an order（1- normal order、 2- canceled， 3-exchanged for new product, 4- suspend，5-报表）
order_time	int	●		order timestamp
order_start_time	int			the start time of an order
purchase_amount	double (2 digit precision)	●
discount_amount	double (2 digit precision)	●
received_amount	double (2 digit precision)	●
payment_type	int	●		1-cash、2-alipay、3-wechat pay、4-QQpay、5-JD wallet、6-credit card、7-unionpay QR code、8-other
customer_count	int			default 1
device_sn	string	●
software_name	string
software_spec	string
hardware_name	string
hardware_spec	string
cashier_no	string
cashier_disk	string
shop_assistant_no	string
order_source	int			1-offline、 2-online (default offline)
member_no	string
ali_id	string
wechat_open_id	string
member_points	double
coupon_no	string
coupon_source	int			1-shop，2-alipay， 3-wechat pay， 4-other
receipt_no	string
sunmi_receipt_no	string
product_list	array[product]	●		see the list below

product

parameter	type	description	required
name	string	name of the product	●
seq_num	string	sequence number of the product
bar_code	string	bar code of the product
spec	string	spec of the product	●
unit	string	unit of the product
quantity	double (3 digit precision)	sell quantity	●
stock_quantity	double (3 digit precision)	stock quantity
original_price	double (2 digit precision)	original price	●
present_price	double (2 digit precision)	current price	●
promote_amount	double (2 digit precision)	promotion price	●
subtotal_amount	double (2 digit precision)	subtotal of this product	●

product additional properties for specific product

parameter	type	description	required
color	string	code for color
size	string	code for size

3.1.2 Update order

API description: By requesting this API, the saas provider can notify the SUNMI store open platform that there is a new order in their system.

API address：/order/update（this is for reference, the detail of this API for each saas provider will be different and needed to be discussed）

Parameters：

parameter	required	type	description
shop_id	yes	string	The identifier of the shop in open platform
order_list	yes	array	the list of order needed to be update

Return value：

{
  code: 0,
  msg: "succeed",
  data: {
    "invalid_list": [
      "CN0000938",
      "CN0000939"
    ]
  }
}

Errors:

Error code	Description
5041	invalid saas provider
5047	invalid order

4 Return value

4.1 Error type

Error types will be returned in HTTP response. If the sign is invalid, then the http status code 401 will be returned.

If the sign is valid, then it will return HTTP status code 200 whatsoever, the error will be returned in the HTTP response body. The structure of our response body is normally:

{
    code：0
    msg: "success"
    data: {}
}

4.2 Error list

see Error List

5 Examples

Error Codes

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.

ESL and other IoT devices are directly attached to the store’s products, prices and strategies, thus a basic product database framework is preserved in SUNMI Store. For data sources, users can choose either to edit on the page of SUNMI Store or to deal with the data on the third-party SaaS provider.

This document describes the error codes user might encounter and the description of that error.

2. Return value

Error types will be returned in HTTP response. If the sign is invalid, then the http status code 401 will be returned.

If the sign is valid, then it will return HTTP status code 200 whatsoever, the error will be returned in the HTTP response body. The structure of our response body is normally:

{
    code：0
    msg: "success"
    data: {}
}

3. Error list

Error code	description
5090	invalid sign
5091	invalid timestamp
5092	invalid random value
5000	database error
5013	invalid saas provider or shop
5015	invalid product
5022	invalid parameter
5041	invalid saas provider
5047	invalid order

Notification Center

1. Background

The data flow between the SUNMI store open platform and the Saas provider could be bidirectional and real-time. The Saas provider can pass its data to the open platform and remote control SUNMI’s IOT device.

Meanwhile, SUNMI store open platform could push the data in its system to the saas provider through the data center on their need

２. API specification

2.1 protocol

All Open APIs are HTTPS request with POST method only.

Content-Type	application/x-www-form-urlencoded
data type	JSON
encoding	UTF-8
signature	MD5
sign rule	see chapter 2.2

2.2 Sign rule

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 digits random string with numbers and alphabets.
timestamp	yes	int	current 10 digit unix timestamp
sign	yes	string	see 2.2

3. Event Monitor APIs

3.1 API list

API address	description
/hook/add	add the HTTP callback address for a set of events
/hook/delete	delete the HTTP callback address for a set of events

3.2 API detail

8.3.1 Add an event monitoring

API description: By requesting this API, User could set up an http callback for a set of events of their choice on the SUNMI store open platform.

When the specified events happened, open platform will request the given HTTP API.

The authorization of this HTTP API must be the same as the SUNMI store open platform API method.

Following parameters must be included in the callback API:

parameter	required	type	description
shop_id	yes	string	the identifier of the shop in open platform
event	yes	int	The type of event to monitor
payload	yes	string	the specific structure of message in JSON

API address: /hook/add

Parameters：

parameter	required	type	description
shop_id	是	string	the identifier of the shop in open platform
http_callback	是	string	the http call back API
event_list	是	array[int]	the list of event to be monitored

return value：

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

parameter event

event value	description
1010	IPC FM010 motion detecting message
1100	add a face to a group result message
2001	IPC real time face recognition message
4100	price change message (currently unavailable)

payload(event=1010):

{
  ipc_id: 029388
  sn: "FS101D8BS00080",
  name: "设备1",
 video_url:"http://xxx.xxx.xxx.xxx/xxx/xxx/41b061f6f10dbd6fe1aaf469fb0ab012d9193d9655816af31cdfbcsdfe71a5fe1",
  model_name: "FM020",
  motion_type: 0,
}

Parameter motion_type:

motion_type value	description
1	motion detection event
2	voice detection event

payload(event=1100):

{
  code: 0,
  msg: "",
  face_id:195
}

Parameter code

code value	description
5527	bad face image
5000	database error

payload(event=2001):

{
    ipc_id: "928",
    face_id: "29195",
    gender: 1,
    age_range: 4，
    group_id: "8927"，
    group_name: "stranger",
    group_type": 2
}

Parameter gender:

gender value	description
0	unknown
1	male
2	female

parameter age_range:

age_range value	description
1	age 0~6
2	age 7~12
3	age 13~18
4	age 19~28
5	age 29~35
6	age 36~45
7	age 46~55
8	age 56~

Parameter group_type

group_type value	description
1	stranger face library
2	familiar face library
3	shop assistant face library
5	custom face library

8.3.2 Cancel event monitoring

API description: By requesting this API, the user can cancel the monitor on given events

API address：/hook/delete

Parameters：

parameter	required	type	description
shop_id	yes	string	the identifier of the shop in open platform
event_list	yes	array[int]	the list of events that need to be canceled

Return value：

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

Parameter event:

event value	description
1010	IPC FM010 motion detecting message
1100	add a face to a group result message
2001	IPC real time face recognition message
4100	price change message (currently unavailable)

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

Product APIs

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.

This document describes how to interchange the product information of the third-party SaaS provider, including how to synchronize the information (the merchant’s products and prices) between SaaS system and SUNMI Store in real-time after the initial interchange of product data.

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 APIs

3.1 Product mapping

3.1.1 Parameters

The following parameters are for open platform APIs. The saas providers will need to provide their product properties list to create a mapping between their system and open platform’s system

parameter	type	description	required	saas system parameters
id	string	the id in sunmi database	yes
seq_num	string	product sequence number	no
bar_code	string	product bar code	no
name	string	product name	yes
alias	string	product alias	no
price	double	current product price	yes
promote_price	double	product promotion price	no
member_price	double	membership price	no
spec	string	specs for the product	no
unit	string	unit for the product	no
level	string	level of the product	no
area	string	area of the product	no
brand	string	brand of the product	no
qr_code	string	qr code url for the product	no
expire_time	int	product expire time	no

3.1.2 Create New Product

API description：This API is used after a saas system had created a new product to inform the open platform system about the change.

This API is for creating new products only, if the product ID exists, then this ID will be added into the exist_list. If the required parameter is not passed, then the id will be put into invalid_list and returned.

API address：/product/create （just for reference）

parameters：

parameter	required	type	description
shop_id	yes	string	the identifier of the shop in open platform
product_list	yes	array	array of product

product parameter：

parameter	required	type	description
id	yes	string	unique identifier of the product
seq_num	no	string	product sequence number
bar_code	no	string	product bar code
name	yes	string	product name
alias	no	string	product alias
price	no	double（non-negative ,2digit precision）	current selling price
promote_price	no	double（ non-negative ,2digit precision ）	promote price
member_price	no	double（ non-negative ,2digit precision ）	membership price
spec	no	string	product specs
unit	no	string	product unit
level	no	string	product level
area	no	string	product area
brand	no	string	product brand
qr_code	no	string	product qr code url
expire_time	no	int	product expire time

Return value：

{
    "code": 0,
    "msg": "succeed",
    "data": {
        "exist_list": [
            "1"
        ],
        "invalid_list": [
            "400"
        ],
    }
}

Error list

Error code	description
5000	database error
5041	invalid saas provider
5015	invalid product

3.2.3 Update New Product

API description ： This API is used after a saas system had udpate a new product to inform the open platform system about the change.

Note that the update API will only update the existing product. If there are no such product, the product id will be returned in the not_exist_list.

Update API will only modify the existing properties of a product, if there are no such property in the system, then it will do nothing.

API address：/product/update（for reference only）

Parameter：

parameter	required	type	description
shop_id	yes	string	the identifier of a shop
product_list	yes	array	the list of product to be updated

product parameter：

parameter	required	type	description
id	yes	string	ID of the product
seq_num	no	string	sequence number of the product
bar_code	no	string	bar code of the product
name	no	string	name of the product
alias	no	string	alias of the product
price	no	double（ non-negative ,2digit precision ）	current price
promote_price	no	double（ non-negative ,2digit precision ）	promotion price
member_price	no	double（ non-negative ,2digit precision ）	membership price
spec	no	string	spec of the product
unit	no	string	unit of the product
level	no	string	level of the product
area	no	string	area of the product
brand	no	string	brand of the product
qr_code	no	string	QR code url of the product
expire_time	no	int	expiration time of the product

Return value:

{
    "code": 0,
    "msg": "succeed",
    "data": {
        "not_exist_list": [
            "5"
        ],
        "invalid_list": []
    }
}

Errors:

error code	description
5000	database error
5041	invalid saas provider
5015	invalid product

3.2.4 Delete Product

API description ： This API is used after a saas system had udpate a new product to inform the open platform system about the change.

The delete API will only delete the existing product in the open platform, if the open platform cannot match the product id, it will add this id to the not_exist_list and return.

API address：/product/delete（for reference only）

Parameters：

parameter	required	type	description
shop_id	yes	string	id of the shop
product_key_list	yes	list	list of product id to be deleted

Return value：

{
    "code": 0,
    "msg": "succeed",
    "data": {
        "not_exist_list": [
            "100"
        ]
    }
}

Error:

Error code	Description
5000	database error
5041	invalid saas provider
5015	invalid product

4 Return Value

4.1 Error Type

Error types will be returned in HTTP response. If the sign is invalid, then the http status code 401 will be returned.
If the sign is valid, then it will return HTTP status code 200 whatsoever, the error will be returned in the HTTP response body. The structure of our response body is normally:

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

4.2 Error Code List

Please Refer to the Error Code List

５ Open API from the saas provider

In the process of creating product mapping, SUNMI store open platform might request the saas provider to provide the following API:

5.1 Get all products Information List

API description ： This API is used for SUNMI store open platform to get all product information from the saas provider. Note that for different saas provider the return data structure can be different.

API address：https://example.SaaS.com/api/getProductList（for reference only）

Parameters：

parameter	required	type	description
shop_id	yes	string	id of the shop
page_num	yes	int	current page number
page_size	yes	int	number of items returned per request

Return value：

{
    "code": 0,
    "msg": "succeed",
    "data": {
        "total": 2,
        "product_list": [
            {
                "name": "example_product",
                "seq_num": "28929380903",
                "price": 10.00,
            }, ...
        ]
    }
}

6 Examples

This chapter offers some examples for creating the product mapping.

The API below requires the shop mapping done to work. For shop mappings please see shop API

The sample paramater we use (we have skipped the sign, random, etc. parameters for reader’s convenience)：

app_id	secret_key	shop_id
APPID6917LTY	tokenlty123	7948

As shown below, after the initial shop mapping, there are not products in the list.

6.1 Example to create new product

6.1.1 Success example

After successfulling creating the shop binding, user will need to call product/create to create product on open platform

Parameters：

app_id	APPID6917LTY
shop_id	7948
product_list	[{“name”:”\u53ef\u53e3\u53ef\u4e50\/\u704c\u88c5″,”id”:”1″,”seq_num”:”cola58476″,”bar_code”:”6958644000259″,”unit”:”\u7f50″,”price”:”3.2″,”member_price”:”3″,”spec”:”250ml”,”level”:””,”brand”:”\u53ef\u4e50″}]

Return value：

{
    "code": 0,
    "msg": "succeed",
    "data": {
        "exist_list": [],
        "invalid_list": []
    }
}

After refreshing the page, we can see that we successfully created a product.

Click Details for the product detail.

6.1.2 Failed Example: product already existed

Resend the same request in 6.1.1, we can find the product_id in the exist list, telling us this product already existed

Parameters：

app_id	APPID6917LTY
shop_id	7948
product_list	[{“name”:”\u53ef\u53e3\u53ef\u4e50\/\u704c\u88c5″,”id”:”1″,”seq_num”:”cola58476″,”bar_code”:”6958644000259″,”unit”:”\u7f50″,”price”:”3.2″,”member_price”:”3″,”spec”:”250ml”,”level”:””,”brand”:”\u53ef\u4e50″}]

Return value：

{
    "data": {
        "exist_list": [
            "1"
        ],
        "invalid_list": []
    },
    "code": 0,
    "msg": "succeed"
}

6.1.3 Failed Example: invalid JSON

In this example we put an invalid JSON in the request body

Parameter:

app_id	APPID6917LTY
shop_id	7948
product_list	[{“name”:”\u53ef\u53e3\u53ef\u4e50\/\u704c\u88c5″,,,”id”:”1″,”seq_num”:”cola58476″,”bar_code”:”6958644000259″,”unit”:”\u7f50″,”price”:”3.2″,”member_price”:”3″,”spec”:”250ml”,”level”:””,”brand”:”\u53ef\u4e50″}]

Return value:

{
    "code": 1,
    "msg": "product_list: JSON.parse error"
}

6.1.4 Failed Example: missing required field

In this request, the request body is missing parameter id

Parameters：

app_id	APPID6917LTY
shop_id	7948
product_list	[{“name”:”\u53ef\u53e3\u53ef\u4e50\/\u704c\u88c5″,”id”:”1″,”seq_num”:”cola58476″,”bar_code”:”6958644000259″,”unit”:”\u7f50″,”price”:”3.2″,”member_price”:”3″,”spec”:”250ml”,”level”:””,”brand”:”\u53ef\u4e50″}]

Return value：

{
    "code": 1,
    "msg": "invalid saas product info"
}

6.2 Example to update an existing product

6.2.1 Success example – update the existing product

Requesting the product/update API to update the price of a product

Parameters：

app_id	APPID6917LTY
shop_id	7948
product_list	[{“id”:1, “price”:”3.5″}]

Return value：

{
    "data": {
        "not_exist_list": [],
        "invalid_list": []
    },
    "code": 0,
    "msg": "succeed"
}

In the sunmi store page, we can see that the price has already been changed and the update time is recorded.

before

after

6.2.2 Success example – create a new product

The update API can also be used to create a product that doesn’t exist.

Parameters：

app_id	APPID6917LTY
shop_id	7948
product_list	[{“id”:2, “name”:”Non-Exist Product”,”seq_num”:”nonexist1″,”price”:”58.2″}]

Return value：

{
    "data": {
        "not_exist_list": [
            "2"
        ],
        "invalid_list": []
    },
    "code": 0,
    "msg": "succeed"
}

The return value shows that the product with id “2” does not exist, so it created an item with product id 2.

before

after

6.2.3 Failed Example: invalid JSON

In this example we put an invalid JSON in the request body

Parameters：

app_id	APPID6917LTY
shop_id	7948
product_list	[{“name”:”\u53ef\u53e3\u53ef\u4e50\/\u704c\u88c5″,,,”id”:”1″,”seq_num”:”cola58476″,”bar_code”:”6958644000259″,”unit”:”\u7f50″,”price”:”3.2″,”member_price”:”3″,”spec”:”250ml”,”level”:””,”brand”:”\u53ef\u4e50″}]

Return value：

{
    "code": 1,
    "msg": "product_list: JSON.parse error"
}

6.2.4 Failed Example: missing required field

In this request, the request body is missing parameter id

Parameters：

app_id	APPID6917LTY
shop_id	7948
product_list	[{“name”:”\u53ef\u53e3\u53ef\u4e50\/\u704c\u88c5″,”id”:”1″,”seq_num”:”cola58476″,”bar_code”:”6958644000259″,”unit”:”\u7f50″,”price”:”3.2″,”member_price”:”3″,”spec”:”250ml”,”level”:””,”brand”:”\u53ef\u4e50″}]

Return value：

{
    "code": 1,
    "msg": "invalid saas product info"
}

6.3 Example to delete an existing product

6.3.1 Success example

Requesting product/delete API to delete an existing product.

Parameters：

app_id	APPID6917LTY
shop_id	7948
product_key_list	[2]

Return value：

{
    "data": {
        "not_exist_list": []
    },
    "code": 0,
    "msg": "succeed"
}

In the product list, we can see that the product has already been deleted.

before

after

6.3.2 Failed Example: invalid product

In this request we tried to delete a product that does not exist

Parameters：

app_id	APPID6917LTY
shop_id	7948
product_key_list	[3]

Return value：

{
    "data": {
        "not_exist_list": [
            "3"
        ]
    },
    "code": 0,
    "msg": "succeed"
}

Shop APIs

1.Background

The SUNMI Store Open Platform structure consists of 2 different units: merchant and store. Merchant is the basic unit to use the open platform. Users will be able to create mutilevels of stores to which the equipments belong. All products, membership information and face information from the equipments will be saved to the corresponding store. Additionally, if there are cooperation with other software service, a shop-to-shop mapping is needed first. After the mapping is established, the software service will be able to use the open store service.
The open platform supports 2 ways of creating the mapping: either the software service provide the API to create the mapping or the open platform will. The details of it will be provided in chapter 2.
All devices and data are aggregated based on the stores in SUNMI Store, which means that all devices are “bound” to a specified store. Meanwhile, users’ operation on devices and data are also based on stores.
As shown below, there will be a multilevel shop system under 1 merchant. In this system, all data and device belongs to a specific shop.

If not specified, the parameter used to identify the store should be included in the parameters for all requests. Please see the table below:

parameter	required	type	description
shop_id	yes	string	the unique identifier for the shop in the saas provider

Note: the parameter shop_id is the unique identifier of a shop on the SaaS provider. Once it is determined, SUNMI Store open platform will use this ID for all request. Please refer to chapter 2 on how to map the shop to this unique identifier on SUNMI Store.

2. Mapping the shops

Before doing actual business on SUNMI store, the shop must on the saas provider must map themselves to the SUNMI store open platform. By mapping the shops to the correct shop_id, SUNMI store open platform will be able to recognize the shop to operate on.

There are currently 2 ways to do the mapping. The first will be requesting SUNMI store open platform API and the second one is requesting the API provided by the saas provider. User can do it either way.

2.1 Requesting the saas provider API

When users choose to do the mapping by requesting the saas provider API, they must be provided with the contents below:

The identifier of the shop, like the shop number, username and password
The HTTP API for the saas provider to validate the information above

After getting the information above, users can click the button 对接ERP to start the mapping.

Then the user can select the SaaS provider to do the mapping on the page below.

This image has an empty alt attribute; its file name is image2019-10-19_16-42-16.png

After clicking the button 保存 (Save), SUNMI Store will call the validation API provided by the SaaS provider to check if the information is valid. After the validation is passed, SUNMI Store open platform will record the shop information and the shop ID the user logged in with.

This image has an empty alt attribute; its file name is image2019-10-19_16-46-26.png

For all the request after, if the user pass the shop_id parameter in the request, it will automatically be done on the shop with this ID.

2.1.2 Saas Provider API Example

API description: this API is the request by by SUNMI Store open platform to validate the data provided by the user on SUNMI Store open platform to do the shop mapping.

For different saas provider, the identifier of a shop can be different and the way to validate the data should be discussed for each distinct saas provider. The example below use the shop id and the verification code as the identifier.

API link: https://example.SaaS.com/api/verifyShop (for reference only)

API parameters:

parameter	required	type	description
shop_id	yes	string	the identifier for a shop in saas platform
verify_code	yes	string	the verification code for that shop id

Return body: (passed)

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

Return body: (error)

{
  code:0
  msg: "invalid verify code"
  data: {}
}

2.2 Requesting the open platform API

User can also do the shop mapping by requesting the SUNMI store open platform API.

First of all, user needs to register an account and create a merchant and a shop on SUNMI Store platform or SUNMI Assistant App. After creation, the user can obtain the API key by clicking on the menu on the left side: 基础数据 (basic data) → 门店管理 (store management) → 查看店铺信息 (check store info) to pop out the page below.

This image has an empty alt attribute; its file name is image2019-10-19_16-54-11.png

This image has an empty alt attribute; its file name is image2019-10-19_16-56-3.png

Click the 获取对接凭证 (get API key) to obtain the API key and the unique shop ID created by SUNMI Store system for the shop. To ensure the effectiveness and safety of the information, the interface voucher is valid for 24 hours, and a new API key can be obtained if the former one expired.

User can input the above two information to the saas provider shop mapping page to conduct verification through the shop mapping API provided by SUNMI Store open platform. For details, please refer to the API in chapter 4.

3. Mapping APIs

3.1 API Specifications

3.1.1 Protocol

All Open APIs are HTTP request with POST method only.

content-type	application/x-www-form-urlencoded
return data format	JSON
character encoding	utf-8
signature	MD5
signing rules	see authentication

3.1.2 Signing rules

See Authentication

3.1.3 Common parameters

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

3.2 API list

API address	description
/shop/bind	create a shop mapping
/shop/unbind	delete a shop mapping
/shop/update	update a shop mapping

3.3 API Details

3.3.1 Create a shop mapping

API description: users can create a shop mapping between SUNMI store open platform and the saas platform by calling this API.

API address: /shop/bind

Parameters:

parameter	required	type	description
shop_id	yes	string	the ID of the shop provided by the saas provider
shop_name	yes	string	the name of a shop
sunmi_shop_no	yes	string	the shop number provided by the open platform.
sunmi_shop_key	yes	string	the API key mentioned in chapter 2.2
company_id	yes	string	The unique ID of the merchant
company_name	yes	string	the name of a merchant
contact_person	yes	string	the name of the contact person
phone	yes	string	the phone number of the contact person
industry_id	no	int	the industry number of a shop
industry_name	no	string	the industry name of a shop
province	no	string	the province of the shop’s location
city	no	string	the city of the shop’s location
district	no	string	the disctrict of the shop’s location
address	no	string	the address of the shop’s location
mail	no	string	the mail address of the shop
format	no	int	Store format: 0 – None; 1 – pay before having meal; 2 – pay after having meal. 0 by default.
status	no	int	Store status: 1 – enabled; 2 – disabled; 1 by default

Return value:

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

Error:

Error code	description
5000	database error
5032	invalid shop_id
5041	invalid saas provider
5042	shop already mapped
5043	API key error

3.2.2 Delete a shop mapping

API description: users can delete a shop mapping between SUNMI store open platform and the saas platform by calling this API.

API address: /shop/unbind

Parameter:

parameter	required	type	description
shop_id	yes	string	the shop_id of the shop to be unmapped

Return value:

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

Error:

Error code	description
5032	invalid shop_id
5041	invalid saas provider
5000	database error

3.2.3 Update a shop mapping

API description: users can update a shop mapping between SUNMI store open platform and the saas platform by calling this API. (Currently the contact name and contact phone cannot be changed)

API address: /shop/bind

Parameter:

parameter	required	type	description
shop_id	yes	string	the ID of the shop provided by the saas provider
shop_name	yes	string	the name of a shop
company_name	yes	string	the name of a merchant
industry_id	no	int	the industry number of a shop
industry_name	no	string	the industry name of a shop
province	no	string	the province of the shop’s location
city	no	string	the city of the shop’s location
district	no	string	the disctrict of the shop’s location
address	no	string	the address of the shop’s location
mail	no	string	the mail address of the shop
format	no	int	Store format: 0 – None; 1 – pay before having meal; 2 – pay after having meal. 0 by default.
status	no	int	Store status: 1 – enabled; 2 – disabled; 1 by default

Return value:

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

Error code:

error code	description
5032	invalid shop_id
5041	invalid saas provider
5000	database error

4. Merchant Mappings

For chain-stores, users need to manage multiple stores, the devices in stores and the data generated correspondingly. SUNMI Store open platform and the cooperative SaaS platform should create merchants mapping.

The API for mapping merchants are still developing

If there is merchant level setting in the cooperative SaaS platform, then when calling bindShop, the user can pass merchant ID and merchant name which can be used as the key to bind the merchant and the store for the interface (for aligning merchant) to come.

5. Appendix

Authentication

1.Background

Authentication is designed to ensure the security of all Open APIs of SUNMI store Open Platform. All HTTP Request in the SUNMI store Open Platform will be authenticated by the method described below. The content below describes how to pass the Sunmi store authentication and use its service.

2. Specification

2.1 Protocol

All open API in SUNMI store open platform uses HTTPS protocol with POST method.

2.2 Sign rules

SUNMI store open platform will distribute the following to all who uses our API:

app_id: the unique identifier of a user ( for some special API, the app_id can be skipped)
secret_key: the signing key of the user

The sign of the HTTP request will be generated from the parameters with the following rules:

There must be a parameter named ‘random’, it is a random string combination of number and alphabets with the length of 6 to 10 digits.
There must be a parameter named ‘timestamp’, it is the current 10-digit unix timestamp, for details please visit: https://tool.chinaz.com/tools/unixtime.aspx
There must be a parameter named ‘app_id’
Sort all parameter in the key’s alphabetic order. Create a string which concatenate all key-value pair in such order.
Concatenate the user’s secret_key at the tail of the string. For details, please read the example
use the MD5 signature of the string
Convert the MD5 sign to all caps.

Example:

Suppose the parameter of the request is the following:

product_id: 389238
user_id: 29389
content: newproductmask
environment: test

Then, by the rules above, we can generate our sign below:

str1 = "app_id=2039dds&content=newproductmask&environment=test&product_id=389238&random=289192×tamp=1593029283&user_id=29389;
str2 = str1 + "&key=kdsofkdsnflke9382938k";
sign = MD5(str2).upper();

By the code above, our final request will contains the parameters below:

app_id:2039dds
product_id: 389238
user_id: 29389
content: newproductmask
environment: test
sign: IDKNFLK392038KDS932K
timestamp: 1593029283
random:289192

Sunmi Store Open Platform will check if the sign is valid, if the sign is invalid then it will return error code: 5090.
It will then check if the timestamp is within the reasonable time window, if the request is outdated, it will return error code: 5091.

3. Authentication Procedure

SUNMI Store Cloud Platform will conduct authentication in the following sequence.

4. Return Value

4.1 Error Type

{
    code：0
    msg: "success"
    data: {}
}

4.2 Error Code

Error Code	Reason
0	success
5090	invalid sign
5091	timestamp outdated