Dynamic detection on the IPC supports detection and alarm motional and audio events. This API is used to set dynamic detection thresholds and period.
Request Link
https://192.168.0.1/openapi/config/setDynamicDetect, 192.168.0.1 should be replaced by the IP address of the IPC.
Request Parameters
Below are private parameters for this API, please refer to Public Parameters for more details.
Parameter
Type
Description
Required
Example
motion_level
int
Motion detection level, range is [0, 3] where 3 is most sensitive.
Y
2
audio_level
int
Audio detection level, range is [0, 3] where 3 is most sensitive.
Y
2
weekday
int
Detection period in a week. Bits are used to represent the weekdays:
bit 0 is for Monday, bit 1 is for Tuesday, bit 2 is for Wednesday,
bit 3 is for Thursday, bit 4 is for Friday, bit 5 is for Saturday,
bit 6 is for Sunday and bit 7 is for 7 x 24 hours. For example,
0b00001111 means detection is on from Monday to Thursday,
0b00010101 means detection is on at Monday, Wednesday and Friday.
Y
128 (decimal value of 0b10000000), 21 (decimal value of 0b00010101)
start_time
long
Start time of the day in minute, range is [0, 1440]. For example, 60 is
01:00, 121 is 02:01.
Y
200
stop_time
long
Stop time of the day in minute, range is [0, 1440]. For example, 60 is
01:00, 121 is 02:01.
Y
400
Response Parameters
Parameter
Type
Description
code
int
Return code, represent the request result, possible return codes are 0, 1, 3, 5, 7, 114, 115, 116, 117, see Error Code for further details.
Request Example
POST /openapi/config/setDynamicDetect HTTP/1.1
Host: 192.168.0.1
Content-Type: application/x-www-form-urlencoded
https://192.168.0.1/openapi/config/getDynamicDetect, 192.168.0.1 should be replaced by the IP address of the IPC.
Request Parameters
No private parameter for this API, please refer to Public Parameters for more details.
Response Parameters
Parameter
Type
Description
code
int
Return code, represent the request result, possible return codes are 0, 1, 3, 5, 7, see Error Code for further details.
motion_level
int
Motion detection level, range is [0, 3] where 3 is most sensitive.
audio_level
int
Audio detection level, range is [0, 3] where 3 is most sensitive.
weekday
int
Detection period in a week. Bits are used to represent the weekdays:
bit 0 is for Monday, bit 1 is for Tuesday, bit 2 is for Wednesday,
bit 3 is for Thursday, bit 4 is for Friday, bit 5 is for Saturday,
bit 6 is for Sunday and bit 7 is for 7 x 24 hours. For example,
0b00001111 means detection is on from Monday to Thursday,
0b00010101 means detection is on at Monday, Wednesday and Friday.
start_time
long
Start time of the day in minute, range is [0, 1440]. For example, 60 is
01:00, 121 is 02:01.
stop_time
long
Stop time of the day in minute, range is [0, 1440]. For example, 60 is
01:00, 121 is 02:01.
Request Example
POST /openapi/config/getDynamicDetect HTTP/1.1 Host: 192.168.0.1 Content-Type: application/x-www-form-urlencoded
This API is used to restore the IPC to factory settings.
Request link
https://192.168.0.1/openapi/device/reset, 192.168.0.1 should be replaced by the IP address of the IPC.
Request Parameters
No private parameter for this API, please refer to Public Parameters for more details.
Response Parameters
Parameter
Type
Description
code
int
Return code, represent the request result, possible return codes are 0, 1, 2, 3, 5, 7, see Error Code for further details.
Request Example
POST /openapi/device/reset HTTP/1.1 Host: 192.168.0.1 Content-Type: application/x-www-form-urlencoded app_id=mdk923idkf&random=289192×tamp=15930292837&sign=IDKNFLK392038KDS932K
Response Example
{ “code”: 0, }
4.Reboot
Description
This API is used to reboot the IPC.
Request link
https://192.168.0.1/openapi/device/reboot, 192.168.0.1 should be replaced by the IP address of the IPC.
Request Parameters
No private parameter for this API, please refer to Public Parameters for more details.
Response Parameters
Parameter
Type
Description
code
int
Return code, represent the request result, possible return codes are 0, 1, 2, 3, 5, 7, see Error Code for further details.
Request Example
POST /openapi/device/reset HTTP/1.1 Host: 192.168.0.1 Content-Type: application/x-www-form-urlencoded app_id=mdk923idkf&random=289192×tamp=15930292837&sign=IDKNFLK392038KDS932K
Response Example
{ “code”: 0, }
Update to UAT Firmware
1 Introduction
This document is intended to help users manually update the IPC firmware to the UAT version for deployment and debugging in the UAT environment.
2 Get Firmware
Please consult Sunmi Technology Customer Service for the latest firmware of your devices and do not use any third-party firmware which may cause malfunctions.
UAT firmware for the Face Sense Camera (or FS & FM020): Part1, Part2.
UAT firmware for the Store Sense Camera (or SS & FM010): Download here.
3 Notes
Firmware is not interchangeable and you should use correct firmware for your device.
The versioning convention of IPC firmware is like 1.2.0-release for release environment and 1.2.0-uat for UAT environment. The device can only be updated to a different version.
Verification will be performed to ensure the firmware is correctly signed before actually updating. Please make sure the firmware comes from Sunmi Technology to prevent malfunctions or bricks after updating.
4 Update Procedure
4.1 Copy the firmware to the SD-card
Plug the SD-card into a computer, format the SD-card with EXFAT file system and set the volume label to “SUNMI-XXXX” where “XXXX” is the last four digits of the MAC address which is on the label of the device.
Create a “firmware” directory in the SD-card’s root directory, copy the firmware file here and rename it to “ip-up.bin”.
4.2 Update
Insert the SD-card with firmware inside into the IPC.
Power on the IPC.
Wait for around 1 min until the red LED blinks, indicating it is updating.
Wait for around 1 min, if the red LED is off and green LED is on that means the device is going to reboot. The updating procedure completes when the green LED is flashing or the blue LED is on.
4.3 Setup
After rebooting, hold the Reset button for a few seconds to restore the factory settings.
Follow the procedures in the User Manual to setup your device and bind it to your account.
If the SD-card is unformatted, use the Sunmi Assistant App or go to https://store.uat.sunmi.com and follow steps in 4.2 to format the SD-card.
Remember to delete the “ipc-up.bin” file under the firmware directory in the SD-card, preventing any accidently update.
Update to Release Firmware
1 Introduction
This document is intended to help users manually
update the IPC firmware to the release version after deployment and debugging
in the UAT environment.
2 Get Firmware
Please consult Sunmi Technology Customer Service for the latest firmware of your devices and do not use any third-party firmware which may cause malfunctions.
Release firmware for the Face Sense Camera (or FS & FM020): Part1, Part2.
Release firmware for the Store Sense Camera (or SS & FM010): Download here.
3 Notes
Firmware is not interchangeable and you should use correct firmware for your device.
The versioning convention of IPC firmware is like 1.2.0-release for release environment and 1.2.0-uat for UAT environment. The device can only be updated to a different version.
Verification will be performed to ensure the firmware is correctly signed before actually updating. Please make sure the firmware comes from Sunmi Technology to prevent malfunctions or bricks after updating.
4 Update Procedure
4.1 Copy the firmware to the SD-card
Plug the SD-card into a computer, format the SD-card with EXFAT file system and set the volume label to “SUNMI-XXXX” where “XXXX” is the last four digits of the MAC address which is on the label of the device.
Create a “firmware” directory in the SD-card’s root directory, copy the firmware file here and rename it to “ipc-up.bin”.
4.2 Update
Insert the SD-card with firmware inside into the IPC.
Power on the IPC.
Wait for around 1 min until the red LED blinks, indicating it is updating.
Wait for around 1 min, if the red LED is off and green LED is on that means the device is going to reboot. The updating procedure completes when the green LED is flashing or the blue LED is on.
4.3 Setup
After rebooting, hold the Reset button for a few seconds to restore the factory settings.
Follow the procedures in the User Manual to setup your device and bind it to your account.
If the SD-card is unformatted, use the Sunmi Assistant App or go to https://store.sunmi.com and format the SD-card.
Remember to delete the “ipc-up.bin” file under the firmware directory in the SD-card, preventing any accidently update.
Cloud API
1 Background
SUNMI Store is a store management system provided by SUNMI for merchants to manage the IoT devices in stores.
As an open platform, SUNMI Store support the interface with the data of third-party SaaS suppliers including product information, transaction information and membership system interface.
2 Interface Specifications
2.1 Protocols
Currently, Open APIs use HTTPS method only, and all messages use POST method.
Not: the message payload should not exceed 1M, and any request larger than 1M will be rejected directly.
Content-Type
application/x-www-form-urlencoded
Data format
Return in JSON format
Character encoding
UTF-8 character encodings
Signature Algorithm
MD5
Sign rules
Refer to 2.2 for sign rules
2.2 Sign Rules
Please refer to Open API – Authentication.
2.3 Common Parameters
Parameter
Required
Type
Descriptions
Example
app_id
Yes
string
The unique ID of the one who applies for interfacing, which can be obtained from SUNMI
EF3OG8R5B32X0
random
Yes
string
A random character string (6-10 digit) which is constituted by numbers and alphabets
123123
timestamp
Yes
int
The current unix timestamp (a 10-digit number) which is accurate to second
1578969281
sign
Yes
string
Signature information. Please refer to 3.2.2 for details
57178021FE900A04C6F98DA6281598AF
3 Specifications for Store Design
Please refer to Open API – Align Merchants/Stores.
4 The Interface for Device Management
4.1 Interface Description
Those interfaces are used to manage the essential attributes (name, e.g.) of an IPC.
4.2 Interface List
Interface
Description
/device/ipc/getList
Acquire the list of devices
/device/ipc/getInfo
Acquire the basic information of devices
/device/ipc/updateName
Change the device name
4.3 Details of Interfaces
4.3.1 Acquire the List of Devices
Intro to the interface: users can acquire the list of devices in relevant stores by using this interface.
Request link: /device/ipc/getList
Interface parameter:
Parameter
Required
Type
Introduction
Example
shop_id
Yes
string
The ID of the store to be interfaced with on SaaS platform, which should be provided by the SaaS supplier.
{
"code": 0, /* Please refer to the error list for other errors */
"msg": "succeed",
"data": {}
}
Error codes:
Error code
Description
5000
Database error
5011
Error in communication with the device
5013
No data found
5041
No shop_id parameter found in the request
5501
The IPC doesn’t exist
5506
No data of this IPC found in the database
5510
Unbound device
5 The Interface to Manage Face Group
5.1 Interface Description
It is an interface used to manage the interfaces related to faces. SUNMI Store will save relevant authorized data and configuration on the cloud and synchronize data needed to the IPC in the store.
5.2 Interface List
Interface
Description
/face/group/getList
Acquire the list of face group
/face/group/getInfo
Acquire the information of a specified face group
/face/group/create
Add face group
/face/group/update
Modify a specified face group
/face/group/delete
Delete a specified face group
/face/group/getFaceList
Acquire the face list of a specified face group
/face/getInfo
Acquire the detailed information of a specified face
/face/add
Add face information to a specified face group
/face/update
Modify the attribute information of a specified face
/face/updatePicture
Modify the attribute information of a specified face image
/face/delete
Delete face information from a specified face group
/face/group/move
Move a specified face among face groups
/face/group/updateMoveStrategy
Modify the strategies on moving new customers among groups
5.3 Details of Interfaces
5.3.1 Acquire the List of Face Group
Intro to the interface: users can acquire the list of face group by calling this interface.
Request link: /fact/group/getList
Interface parameter:
Parameter
Required
Type
Description
Example
shop_id
Yes
string
The ID of the store to be interfaced with on SaaS platform, which should be provided by the SaaS supplier.
{
"code": 0, /* Please refer to the error list for other errors */
"msg": "succeed",
"data": {
"face_id": "578968740430"
}
}
Error codes:
Error code
Description
5000
Database error
5013
No data found
5041
No shop_id parameter found in the request
5520
The number of face groups or the face capacity reaches the upper limit
Note: SUNMI Store will process the images added to the face library and generate the corresponding face_id. The process result will be noticed asynchronously for it takes some time to process images.
For details, please refer to Notification Push Center.
The synchronous process and return method are being developed.
5.3.9 Modify the Attribute Information of a Specified Face
Interface description: users can modify the attribute information of a specified face by calling this interface.
Request link: /face/update
Interface parameters:
Parameter
Required
Type
Description
Example
shop_id
Yes
string
The ID of the store to be interfaced with on SaaS platform, which should be provided by the SaaS supplier.
{
"code": 0, /* Please refer to the error list for other errors */
"msg": "succeed",
"data": {}
}
Error codes:
Error code
Description
5000
Database error
5013
No data found
5041
No shop_id parameter found in the request
5506
The data has not been found
5520
The number of face groups or the face capacity reaches the upper limit
5525
The information of the default face group cannot be changed
6 The Interface for Customer Flow Statistics
6.1 Interface Description
This interface is used to inquire the customer flow and history monitored and saved by the IPC. Three statistical dimensions are included – historical customer flow data (T+1), the customer flow data of the current day (T+0), real-time customer flow data.
The historical customer flow data (T+1) and the customer flow data of the current day (T+0) are provided by HTTP interface. SaaS suppliers can obtain the data by initiating request and the frequency of updating statistical data of the current day is smaller 15s/update, and the real-time customer flow data will be obtained by receiving notifications. For details, please refer to Notification Push Center.
6.2 Interface List
Interface
Description
/passengerFlow/stat/today/getLatest
Acquire the real-time customer flow of the current day (real-time total customer flow)
/passengerFlow/stat/today/groupByTag
Acquire the customer flow data of the current day (according to the age and new/repeat face groups)
/passengerFlow/stat/today/groupByGender
Acquire the customer flow data of the current day (according to the age and gender group)
/passengerFlow/stat/today/getTrendByHour
Acquire the customer flow trend of the current day (total customer flow, the time granularity is hour)
/passengerFlow/stat/history/groupByTag
Acquire historical customer flow data (total customer flow/new and repeat customer/member)
/passengerFlow/stat/history/groupByGender
Acquire the details on historical customer group (age and gender)
/passengerFlow/stat/history/getTrendByHour
Acquire the historical customer flow trend (total customer flow/new and repeat customers, the time granularity is hour)
/passengerFlow/stat/history/getTrendByDay
Acquire the historical customer flow trend (total customer flow/new and repeat customer, the time granularity is day)
/passengerFlow/stat/history/getTrendByWeek
Acquire the historical customer flow trend (total customer flow/new and repeat customer, the time granularity is week) (developing)
/passengerFlow/stat/history/getTrendByMonth
Acquire the historical customer flow trend (total customer flow/new or repeat customer, the time granularity is month) (developing)
6.3 Interface Details
6.3.1 Acquire the Real-Time Customer Flow of the Current Day
Interface description: users can acquire the customer flow of the current day by calling this interface.
{
"code": 0, /* Please refer to the error list for other errors*/
"msg": "succeed",
"data": {
"count": "123"
"unexposed_count": 0
}
}
Error codes:
Error code
Description
5000
Database error
5013
No data found
5041
No shop_id parameter found in the request
6.3.2 Acquire the Customer Flow Data of the Current Day (According to the Group of New and Repeat Customer and Age Range)
Interface description: users can acquire the data of new/repeat customer flow data according to the age range of the current day by calling this interface.
{
"code": 0, /* Please refer to the error list for other errors*/
"msg": "succeed"
"data": {
"url": "https://xxxxxxxx/C101P98200023/1219130724381102080.flv?auth_key=1579501989-729716105000265001016467621435-0-",
"hls_url": "https://xxxxxxxx/C101P98200023/1219130724381102080.m3u8?auth_key=1579501989-729716105000265001016467621435-0-"
}
}
Field description: resolution
resolution value
Description
0
Super high definition
1
High definition
Error codes:
Error code
Description
5000
Database error
5011
Error in communication with the device
5013
No data found
5041
No shop_id parameter found in the request
5501
The IPC does not exist
5510
Unbound device
7.3.2 End Live
Interface description: users can end the remote live by calling this interface.
Request link: /media/live/stop
Interface parameters:
Parameter
Required
Type
Description
Example
shop_id
Yes
string
The ID of the store to be interfaced with on SaaS platform, which should be provided by the SaaS supplier.
{
"code": 0, /* Please refer to the error list for other errors*/
"msg": "succeed",
"data": {
"snapshot_url":"http://xxxxxxxx/VIDEO/IPC/SS101D8BS00087/39C1045AF2EA34B0CEA528FB228C8EDA"
}
}
Error codes:
Error code
Description
5000
Database error
5013
No data found
5041
No shop_id parameter found in the request
7.3.7 Acquire the Real-Time Monitoring Image
Interface description: users can acquire the real-time monitoring images by calling this interface, and the validity of the images is one day.
Request link: /media/live/getSnapshot
Interface parameters:
Parameter
Required
Type
Description
Example
shop_id
Yes
string
The ID of the store to be interfaced with on SaaS platform, which should be provided by the SaaS supplier.
{
"code": 0, /* Please refer to the error list for other errors*/
"msg": "succeed",
"data":{
"snapshot_url":"http://xxxxxxxx/VIDEO/IPC/SS101D8BS00087/39C1045AF2EA34B0CEA528FB228C8EDA"
}
}
Error codes:
Error code
Description
5000
Database error
5011
Error in communication with the device
5013
No data found
5041
No shop_id parameter found in the request
5501
IPC does not exist
5510
The device is unbound
5515
The screenshot time overrun the limit
7.3.8 Start remote playback
Interface description: Through this interface call, the user can start remote playback.
Request link: /media/playback/start
Interface parameters:
Parameter
Required
Type
Description
Example
shop_id
Yes
string
The ID of the store to be interfaced with on SaaS platform, which should be provided by the SaaS supplier.
{
"code": 0, /* Please refer to the error list for other errors*/
"msg": "succeed",
"data": {
"url": "https://xxxxxxxx/SAAS-OpenAPI_1211497245552152576/1577092646.flv?auth_key=1577096246-57626095498907571693914212321441-0-",
"hls_url": "https://xxxxxxxx/SAAS-OpenAPI_1211497245552152576/1577092646.flv?auth_key=1577096246-57626095498907571693914212321441-0-",
"client_id": "SAAS-OpenAPI_1211497245552152576"
}
}
Error codes:
Error code
Description
5021
Illegal parameter (time interval exceeding limit)
5041
No shop_id parameter found in the request
5087
Unmatched data
5088
Database error
5506
No data found
7.3.9 End remote playback
Interface description: Through this interface call, the user can start remote playback.
{
"code": 0, /* Please refer to the error list for other errors*/
"msg": "succeed",
"data": {}
}
Error codes:
Error code
Description
5020
Invalid parameter
8 Notifications Center
8.1 Interface description
SUNMI Store platform can push notifications to the cooperative SaaS parties according to the notification type subscribed by the cooperative platforms
8.2 Interface List
Please refer to Notification Center.
9 docking demonstration
9.1 Shop lignment
Please refer to Sunmi Store Open Platform -> Shop APIs, it is introduce how to set up the mapping relationship between sunmi’s shop and saas’ shop. All subsequent operations are based on the devices and data in the stop
9.2 Configuration Network For Device
If your device is connected to the Internet through cable, please skip this step.
If your device is connected to the Internet through a wireless network, please follow the steps below to use the Android SDK for network configration (for other operating systems or devices, you can also directly call the device API for network configration).
If the blue light on the device is always on which inndicates that the device is connected to Internet successful
If the green light on the device is always on which inndicates that the device is connected to Internet abnormal
9.3 Bind Device
9.3.1 Bind Device by API(under development)
After the IPC device is connected to the network successful, call the device binding interface /device/ipc/bind to bind the device to the specified stop.
Open the Sunmi assistant APP which can be downloaded from
Android or IOS market, login with your own username and password which has been
set up relationship with saas’ shop.
In the shop, please click the Device to choose a type device added, at the same
time, turn on the camera power. After the power is turned on, wait for about 20
seconds. When the camera’s green light is flashing , then click next.
There are two mode for connecting Internet: Wired and wireless
For cable network connection, need
to plug in the cable for the camera, at the same time, keep the sunmi assistant
app in the same network; after the camera ‘s
blue light is always on, then click next, and find the corresponding IPC
device to bind.
For wireless network connection,
need to connect your mobile phone which has been installed sunmi assistant app
to the camera’s wireless network [Sunmi XXXX] (you can find the network name on
the camera body or the box), then click next to find the corresponding IPC
device to bind
After adding successfully, the newly added IPC devices can
be seen on mobile phones and the web
9.4 Device configration
9.4.1 Adjust Camera Focus By API (under development)
After the device is bound, the API can be called to adjust camera focus
9.4.2 Setting Incoming Line On Store Web
The first thing for face sense camera is set incoming line for the shop.
Step1: open the sunmi assistant app, login the
corresponding shop with right username and password, click the Device, then
click the three small icons in the upper right of the screen to enter the
camera settings, then start to adjust the screen to get the best picture
Step2: the screen will prompt “please guide the customer to face to the
IPC and stand at the right place for face reorganization”, and then click
next in the upper right corner of the screen
Step3: the screen will prompt ” Please fit the face into the facial recognition box by adjusting the size of the image and moving the box “. At the same time, the camera will automatically adjust the screen, and prompt ” To ensure the recognition accuracy, you can move the store doorsill line you set or drag the ends of the doorsill line to change doorsill length “, which is that you can manually mark the line on the mobile screen to set the position of the entrance threshold, and then click finish
9.5 Watch Living Video
Interface List
Detailed info can be read in chapter 7: playbace living video
Interface
Description
/media/live/start
Start remote live video
/media/live/stop
End remote live video
/media/playback/start
Start remote video playback (developing)
/media/playback/stop
End remote video playback (developing)
/media/video/getList
Acquire the list of video playback
/media/motionDetection/getList
Acquire the list of motion detection videos
/media/playback/getSnapshot
Acquire the snapshots of a specified period of time
/media/live/getSnapshot
Acquire the snapshots of real-time monitor
9.6 Customer Flow Statistics
Interface list
Detailed info can be read in chapter 6: customer flow statistics
Interface
Description
/passengerFlow/stat/today/getLatest
Acquire the real-time customer flow of the current day (real-time total customer flow)
/passengerFlow/stat/today/groupByTag
Acquire the customer flow data of the current day (according to the age and new/repeat face groups)
/passengerFlow/stat/today/groupByGender
Acquire the customer flow data of the current day (according to the age and gender group)
/passengerFlow/stat/today/getTrendByHour
Acquire the customer flow trend of the current day (total customer flow, the time granularity is hour)
/passengerFlow/stat/history/groupByTag
Acquire historical customer flow data (total customer flow/new and repeat customer/member)
/passengerFlow/stat/history/groupByGender
Acquire the details on historical customer group (age and gender)
/passengerFlow/stat/history/getTrendByHour
Acquire the historical customer flow trend (total customer flow/new and repeat customers, the time granularity is hour)
/passengerFlow/stat/history/getTrendByDay
Acquire the historical customer flow trend (total customer flow/new and repeat customer, the time granularity is day)
/passengerFlow/stat/history/getTrendByWeek
Acquire the historical customer flow trend (total customer flow/new and repeat customer, the time granularity is week) (developing)
/passengerFlow/stat/history/getTrendByMonth
Acquire the historical customer flow trend (total customer flow/new or repeat customer, the time granularity is month) (developing)
9.7 Real-time To Get face_id
Please refer to Sunmi Store Open Platform ->Notification Center: hook/add. First, hook the monitored event with the callback HTTP address and function to sunmi store open platform
Second, when IPC get the related face will report to sunmi cloud backend system, sunmi will push the face info to saas’ hooked http address.
9.7.1 Add an event monitoring
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 saas shop which applied by saas
event
yes
int
the type of event to monitor
payload
yes
string
the specific structure of message in JSON
API address: /hook/add
Parameters：
parameters
reqired
type
decription
example
shop_id
yes
string
the identifier of the saas shop which applied by saas
Simplified interface， keep the shop_id as the only indentifer for saas
2019-08-08
adjust some return value
2019-08-23
update notification center
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.
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）
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:
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.
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.
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)
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)
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
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 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.
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 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.
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.
