Guide on ESL Integration

1 Introduction

SUNMI Electronic Shelf Label (ESL) can be used in supermarkets, warehouses, hospitals, meeting rooms and other scenarios to show product prices, stock information and attendee information, etc.

Users can directly manage ESLs on SUNMI Store open platform, but in some real cases, they need to interact their software system with SUNMI Store to send product information to SUNMI Store and manage the functionalities of ESLs in order to complete the final ESL integration.

To meet our clients’ needs and empower our partners, SUNMI Store provides ESL-related openAPIs to integrate ESLs with a 3rd party software in different levels.

SUNMI Store is available in 3 editions (SUNMI Cloud Edition, Private Cloud Version and Private Local Server Version), and APIs of different editions vary.

Note: This document is written to illustrate how to realize product information display, but it also can be a reference for more ESL uses in different scenarios.

2 Integration Process

1. Communication. After determining to use SUNMI openAPIs, please first read openAPI documents (on SUNMI Store) and discuss with SUNMI team on the level of integration, business process design, matters need attention, schedule and other matters through a messaging app.

2. Send the name of the software to be integrated with and email address to SUNMI technical support team which then will email parameters including app_id, secret_key and ESL App in the UAT environment to you.

3. Integration. SUNMI provides technical support through the messaging app.

4. Testing. Once the integration in UAT environment is completed, you can test by yourself and provide a test account for SUNMI to verify at the same time.

5. SUNMI sends the parameters in onl environment and complete integration in onl environment.

3 Levels of Integration

SUNMI Store provides multiple ESL-related openAPIs and you can integrate as needed.

Frankly speaking, we have set four integration levels, which are listed in the table below:

Level Object Functionalities Realized
L1 Product data Integration at this level enables the synchronization of product data and store binding information. After successful integration, the 3rd party software uploads product data to the digital store or the digital store automatically acquires product data from the software. A managed ESL can automatically update its display with price modification in the third-party software. ESL management functions, such as ESL binding, ESL unbinding, and template editing, are only available in SUNMI Store and SUNMI Assistant App.
L2 Basic operations Based on L1 integration, L2 integrates ESL binding and unbinding APIs to the 3rd party software. After successful integration, basic operations, such as ESL binding and unbinding, can be performed in the 3rd party software directly.
L3 Device Based on L2 integration, L3 level allows the integration of specific device APIs to the 3rd party software. After successful integration, the third-party software supports basic ESL management operations, such as template switching, ESL flashing, and data repushing. Template editing and AP management functions are only available in SUNMI Store and SUNMI ESL App.
L4 ESL management system Based on L3 integration, L4 implements a comprehensive integration between the ESL system and the 3rd party software. After successful integration, all ESL management functions are available in the 3rd party software except the independent template Studio (login to the Studio is not required). SUNMI Store is not necessary for routine operations.

L1 integration is sufficient in most cases, and some clients may need an L2 integration. Please thoroughly communicate on business scenarios before selecting any higher level integration.

4 APIs of Different Modules and Corresponding Documents

APIs are categorized in accordance with different modules, please refer to the modules and corresponding documents listed below.

Module & Doc Description
Authentication It contains the general authentication rules of SUNMI Store, please read carefully before commencing development.
Shop APIs SUNMI devices and services are managed per store under a company, please bind the store on SUNMI Store and the store on the 3rd party software before starting function integration.
Product APIs It contains the APIs to add, delete and modify a product, which is included in the L1 integration. In addition to ESL, these APIs also can be used for other devices and services.
ESL APIs It contains APIs to manage ESLs, what are included in the L2 integration and levels higher.

5 APIs and Corresponding Modules

ESL-related openAPIs are categorized in accordance with modules, and you can combine different modules as needed.

APIs included in L1-L4 are listed below. Whether to enable some functions (e.g.: flash LED, upgrade, etc.) is up to your needs.

Module API name API L1 L2 L3 L4 Description
Store Binding Binding a SUNMI store /shop/bind Manually bind the store that has already been created on SUNMI Store.
Unbinding a SUNMI store /shop/unbind
Updating store info /shop/update
Creating a company /company/create The company and store created through this API are automatically bound.
Getting software company list /company/getList
Getting software company info /company/getInfo  
Creating a store /shop/create
Getting software store list /shop/getList
Getting software store info /shop/getInfo
Getting the binding status a software store /shop/getBindInfo Search the corresponding store information thorough shop_id.
Product APIs Creating a product /product/create
Updating a product /product/update This API can also be used to create a product.
Deleting a product /product/delete
Getting all software product info api/getProductList An API you provided to SUNMI to pull all product information from the 3rd party software.
ESL – Product Binding an ESL with a product /product/bindEsl Bind ESL, product and template. After binding, the display will be updated and the ESL will be bound to a store.
Unbinding an ESL from a product /product/unbindEsl
Getting the list of ESLs bound to a product /product/getBindEslList More than one ESL can be included.
Modifying the ESL template bound to a product /product/updateTemplate ESL ID, template.
Getting product list /product/getList
Getting product information /product/getInfo
ESL – shelf label Adding an ESL to a store /device/esl/bind This is only used to add an ESL to a store (binding it to a product is not included).
Removing an ESL from a store /device/esl/unbind Only the ESL that has been unbound can be removed.
Getting ESL list /device/esl/getList ESL status is included.
Getting ESL info /device/esl/getInfo Get basic information, bind to products or use templates through ESL ID.
Pushing a certain image to an ESL /device/esl/pushImage The 3rd party software can generate and push images to ESLs (there is a limit to image size).
Getting overview statistics /device/getOverview The number of ESLs in the system, the number of products and the number of each push status.
ESL – flash LED Flashing an ESL‘s LED /device/esl/flashLed Flash certain ESL’s LED in a certain way.
ESL – AP Getting AP list /device/ap/getList Please bind an AP using ESL App.
Getting AP info /device/ap/getInfo
Changing AP info /device/ap/updateName
Restarting an AP /device/ap/reboot
ESL – template Uploading a newly created template /template/create Upload the json file you created in the independent template Studio to the ESL system.
Updating a specified template /template/update
Getting template list /template/getList
Getting template info /template/getInfo
Deleting a template /template/delete

6 Develop Environments

SUNMI Store runs in more than one environment. Developing and jointly debugging in uat environment is recommended, and release it to onl environment after the joint debugging has been completed.

Environment SUNMI Store Web Address API Address Sample API
uat https://store.uat.sunmi.com/ https://store.uat.sunmi.com/openapi/ https://store.uat.sunmi.com/openapi/product/update
onl https://store.sunmi.com/ https://store.sunmi.com/openapi/ https://store.sunmi.com/openapi/product/update

IPC OpenAPI Testing Tutorial

1. Introduction

This tutorial will show you how to test the IPC OpenAPI with Postman.

Consult the Sunmi Technology Customer Service and get materials in the table below except the IP and SN of your device. And please connect your IPC to the Internet and make sure the blue LED is solid before going through the following steps.

Item Example in this tutorial
app_id08BABCDABBB661234567
secret_keyABCDEFG3F2BB03917123
Activation Codeabcd2986jnts8987hntl1234
OpenAPI Cert and its passwordopenapi.p12
Postman CollectionsSunmi_IPC_OpenAPI_Postman_Collection_202007001_en.json
IP192.168.103.198
SNC201000P00123

2. Postman Setup

  1. Download Postman: Link, we use v7.27.1 in this tutorial.
  2. And just follow the Installation Wizard.

3. Collection Import and Configuration

  1. Launch Postman
  2. Click File -> Import -> Upload Files, And open the Postman collection from Sunmi, i.e. “Sunmi_IPC_OpenAPI_Postman_Collection_202007001_en.json”, confirm and click “Import”.
  3. Click File -> Settings -> Certificate, add the certificate file and its password, put the IP in the Host filed.
  • 4. Open the General page, set “SSL certificate verificatio” to `OFF`.
  • 5. Back to homepage of Postman, right click on “Sunmi IPC OpenAPI” collections, “Edit”, and update the corresponding settings at “CURRENT VALUE” in page “Variables”.

4. Activation Example

  1. Activation use the activation code as the secret key, Make sure the value of secret_key in the Variables page is your activation code.
  2. Open Sunmi IPC OpenAPI -> Basic -> 0. Activation, modify the “sn” to your device’s SN in the Body tab, click Send, activations succeed with “code” 0 in the response.

5. API Test

  • This collection only includes several API example for testing. Each request needs to be correctly signed, see the Sign Rules.
  • Sign script are included in this collection in “Pre-request Scripts”, it will calculate the value of “app_id”, “timestamp”, “random” and “sign” in every request.

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 will help customers digitalize their shop. Based on these data, such as passenger flow and statistic info, combined with the saas order, SUNMI will be able to create a multi-dimensional analysis and chart.

This document describes how to syncronize the order information with the Saas provider to make sure our customer can obtain data as soon as possible for future process or BI analysis

2 API Specifications

2.1 Protocol

All APIs use HTTPS Protocol with POST method

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

Content-Typeapplication/x-www-form-urlencoded
return type JSON
encodingUTF-8
signing algorithmsMD5
signing rulessee chapter 2.2

2.2 Signing rules

see Authentication

2.3 Common Parameters

parameterrequiredtypedescription
app_idyesstringunique identifier provided by SUNMI store open platform
randomyesstring6-10 digit random string with number and alphabets
timestampyesint10 digit current unix timestamp
signyesstring see chapter 2.2

3 APIs

3.1 ORDER APIs

3.1.1 Order properties

Properties shown below are SUNMI order properties. Those are just for demonstration. Saas providers will need to provide their properties list to SUNMI.

The table below is the basic properties of an order. For specific orders, there will be more properties

order

groupparametertypedescriptionrequireduniquedescription
order basic infoorder_idstringorder idunique order id from saas provider
order_typeintorder typetype of the order ( 1-normal 2-refund 3-exchange 4-on hold 5-list 6-payment failed 7-canceled 8-etc
order_timeintorder timeorder timestamp
order_start_timeintorder start timestart time of the order
purchase_amountdouble(2-digit precision)total price
discount_amountdouble(2-digit precision)discount
received_amountdouble(2-digit precision) actual amount get
payment_typeintpayment type1-cash 2-alipay 3-wechat 4-qq 5-JD 6-debit cart 7-union pay QR code 8-etc
customer_countintcustomer countdefault 1
device infodevice_snstringdevice sn
software_namestringsoftware name
software_specstringsoftware specification
hardware_namestringhardware name of saas provider
hardware_specstringhardware specification
cashier_idstringcashier id
cashier_deskstringcashier desk
shop_assistant_idstringshop assistant id
order source infoorder_sourceintorder source1-offline 2-online (default 1)
membership infomember_idstringmember id
ali_idstringalipay id

wechat_open_idstringwechat open id
member_pointsdoublepoints

coupon infocoupon_idstringcoupon id
coupon_source intcoupon source1-
receipt inforeceipt_idstringreceipt id
sunmi_receipt_idstringsunmi receipt id
product infoproduct_liststring(form array[product])product list

see below

Product

parametertypedescriptionrequiredunique
idstringproduct id
namestringproduct name
seq_numstringproduct sequence number


bar_codestringbar code
specstringproduct spec
unitstringproduct unit
quantitydouble(3-digit precision)product quantity
stock_quantitydouble(3-digit precision)stock
category_idstringcategory id
category_namestringcategory name
original_pricedouble(2-digit precision)original price
present_pricedouble(2-digit precision)actual price
promote_amountdouble(2-digit precision)discount
subtotal_amountdouble(2-digit precision)subtotal

Additional parameters

additional parameterstypedescriptionrequiredunique
colorstringcolor code
sizestringsize code

3.1.2 Create order API

Description: This API is used for Saas provider to notify SUNMI when a new order is created. SUNMI store will save a copy of order in the database and provide some visualization of such order.

API Address:/order/create

API version:v2.0

Parameter

parameterrequiredtypedescriptionexample
sunmi_shop_no nostringSunmi shop number 100939070408
shop_idnostringsunmi shop id (used for version before v2.0. After v2.0, please use sunmi_shop_no10001
order_listyesstring(form of array)order list [
{
“order_id”: “d12324b545a5678”,
“order_type”: 1,
“order_time”: 1583246199,
“order_start_time”: 1568875091,
“purchase_amount”: 100,
“discount_rate”: 80,
“discount_amount”: 20,
“received_amount”: 80,
“payment_type”: 1,
“customer_count”: 2,
“order_status”: 1,
“device_sn”: “SS123LTY6917”,
“software_name”: “SUNMI”,
“software_spec”: “app”,
“hardware_name”: “hw”,
“hardware_spec”: “hws”,
“order_source”: 1,
“member_id”: 123456,
“product_list”: [
{
“name”: “p_name”,
“seq_num”: “abc”,
“id”: 5,
“price”: 10,
“quantity”: 3,
“color”: “red”,
“size”: “larse”
}
],
“cashier_id”: “cachier123”,
“cashier_desk”: 123,
“shop_assistant_id”: 666,
“ali_id”: 13111115555,
“wechat_open_id”: “wechat123”,
“member_points”: 156,
“coupon_id”: 123,
“coupon_source”: 1,
“receipt_id”: “rcn12333333”,
“sunmi_receipt_id”: “sunmi666”
}
]

Exmaple: 

  'method': 'POST',
  'url': 'https://store.uat.sunmi.com/openapi/order/create',
  'headers': {
    'Content-Type': 'application/x-www-form-urlencoded'
  },
  formData: {
    'shop_id': '10001',
    'app_id': 'I4VI99A0JDS21',
    'timestamp': '1581662687',
    'random': '5dsf6698',
    'sign': 'E3CC30458CBDC74E7D959E24B56732F6',
    'order_list': '[{
      "order_id": "d12324b545a5678",
      "order_type": 1,
      "order_time": 1583246199,
      "order_start_time": 1568875091,
      "purchase_amount": 100,
      "discount_rate": 80,
      "discount_amount": 20,
      "received_amount": 80,
      "payment_type": 1,
      "customer_count": 2,
      "order_status": 1,
      "device_sn": "SS123LTY6917",
      "software_name": "SUNMI",
      "software_spec": "app",
      "hardware_name": "hw",
      "hardware_spec": "hws",
      "order_source": 1,
      "member_id": 123456,
      "product_list": [{
          "name": "p_name",
          "seq_num": "abc",
          "id": 5,
          "price": 10,
          "quantity": 3,
          "color": "red",
          "size": "larse"
       }],
      "cashier_id": "cachier123",
      "cashier_desk": 123,
      "shop_assistant_id": 666,
      "ali_id": 13111115555,
      "wechat_open_id": "wechat123",
      "member_points": 156,
      "coupon_id": 123,
      "coupon_source": 1,
      "receipt_id": "rcn12333333",
      "sunmi_receipt_id": "sunmi666"
    }],
 }

Return value: 

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

Error Code:

error codeReason
5041invalid saas provider
5047illegal order

4 Return Value

4.1 Error types

Return value will be returned as part of the http response. If the sign validation failed, an HTTP code 401 will be returned. Otherwise, a http code of 200 will be returned

Rest of the error will be returned in the json response, normal response type will be:

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

4.2 Error codes

See error codes

5 Examples

IPC Notification Center

There are two ways to get IPC message. Firstly, if some event is subscribed, the IPC will post a message to related callback url. Secondly, we can maintain a TCP connection to get related message.

1. Post Message

We can subscribe some topic to IPC, and the IPC will post a http message to the subscribers when something relative happened. It has the same function as Message Channel.

1. 1 Signature

Refer to Sign Rules.

1.2 Subscribe

1.2.1 Subscribe

Description

This API is used to subscribe some topic to IPC. The IPC will post a http message to the callback url passed in by this API when something related happened, thus the subscribe is informed.

Request link

https://192.168.0.1/openapi/hook/add, 192.168.0.1 needs to be replaced by the IP address of IPC.

Request Parameters

Below are private parameters for this API, please refer to Public Parameters for more details.

ParameterTypeDescriptionRequired
event_listarray[string]Topic list, the following is allowed. “face_recog_event” is only supported by “FM020”.
[“face_recog_event”,”dynamic_detect_event”]
Y
http_callbackstringCallback url. The IPC will post a message to this url when something related happened.Y

Response Parameters

ParameterTypeDescription
codeintReturn code, represent the request result, possible return codes are 0, 1, 2, 5, 310, 311, see Error Code for further details.

Request Example

POST openapi/hook/add HTTP/1.1
Host: 192.168.0.1
Content-Type: application/x-www-form-urlencoded

app_id=mdk923idkf&random=289192&timestamp=15930292837&sign=IDKNFLK392038KDS932K&
event_list=[“face_recog_event”,”dynamic_detect_event”]&http_callback=http://192.168.0.100/msg

Response Example

{
    "code": 0
}

1.2.2 Unsubscribe

Description

This api is used to unsubscribe some topic that is already subscribed. The subscriber will not receive relative messages once relative topic unsubscribed.

Request link

https://192.168.0.1/openapi/hook/delete, 192.168.0.1 needs to be replaced by the IP address of IPC.

Request Parameters

Below are private parameters for this API, please refer to Public Parameters for more details.

ParameterTypeDescriptionRequired
event_listarray[string]opic list, the following is allowed. “face_recog_event” is only supported by “FM020”.
[“face_recog_event”,”dynamic_detect_event”]
Y

Response Parameters

ParameterTypeDescription
codeintReturn code, represent the request result, possible return codes are 0, 1, 2, 5, 310, see Error Code for further details.

Request Example

POST openapi/hook/delete HTTP/1.1
Host: 192.168.0.1
Content-Type: application/x-www-form-urlencoded

app_id=mdk923idkf&random=289192&timestamp=15930292837&sign=IDKNFLK392038KDS932K&
event_list= [“dynamic_detect_event”, “face_recog_event”]

Response Example

{
    "code": 0
}

1.2.3 Query subscribed message

Description

This API is used to query all topics and callbacks that subscribed to the IPC. When something related happened, the IPC will post a http message to relative callback urls.

Request link

https://192.168.0.1/openapi/hook/query, needs to be replaced by the IP address of IPC.

Request Parameters

No private parameter for this API, please refer to Public Parameters for more details.

Response Parameters

ParameterTypeDescription
codeintReturn code, represent the request result, possible return codes are 0, 1, 5, see Error Code for further details.
sub_eventarraySubscriber list
eventstringTopic
http_callbackarrayHttp callback of the topic
numstringNumber of the subscriber of the topic

Request Example

POST openapi/hook/query HTTP/1.1
Host: 192.168.0.1
Content-Type: application/x-www-form-urlencoded

app_id=mdk923idkf&random=289192&timestamp=15930292837&sign=IDKNFLK392038KDS932K&

Response Example

{
    "data": {
        "num": 2,
        "sub_event": [
            {
                "event": "face_recog_event",
                "http_callback": [
                    "10.10.61.206:8000"
                ]
            },
            {
                "event": "dynamic_detect_event",
                "http_callback": [
                    "10.10.61.206:8000"
                ]
            }
        ]
    },
    "code": 0
}

1.3 Post

The IPC will post a http message to inform subscribers. The http post is formed in form table, the “Content-Type” is “multipart/form-data”, the payload of message is packaged in “payload”.

Dynamic Detect Message

The payload is formatted as follow:

POST / HTTP/1.1
Host: 10.10.61.206:8000
User-Agent: libcurl/7.52.1 OpenSSL/1.0.2p
Accept: */*
Content-Length: 826
Expect: 100-continue
Content-Type: multipart/form-data; boundary=————————c83c36cd4ee4082f
 
————————–c83c36cd4ee4082f
Content-Disposition: form-data; name=”app_id”
 
123
————————–c83c36cd4ee4082f
Content-Disposition: form-data; name=”random”
 
692777
————————–c83c36cd4ee4082f
Content-Disposition: form-data; name=”timestamp”
 
1579158766
————————–c83c36cd4ee4082f
Content-Disposition: form-data; name=”sign”
 
372F669601E8347737744FFC88B74665
————————–c83c36cd4ee4082f
Content-Disposition: form-data; name=”payload”
 
{“event_id”:1,”detect_type”:2,”video_url”:”https://10.10.63.19/mnt/sd-card/sunmi_video/video_detect/1579158761.flv?auth_key=1579158765-d701e761fecf0df84853440d4dbc3fe1″,”event_type”:”dynamic_detect_event”,”sn”:”SS101D8BS00080″,”report_time”:1579158765}
————————–c83c36cd4ee4082f–

The fields of the payload is described as follow.

ParameterTypeDescription
event_idlongEvent ID
event_type stringEvent Type
report_timelongTimestamp of event
detect_typeintType of dynamic detect:
0: Motion Detected
1: Audio Detected
2: Motion and Audio Detected
3: Detected Human
video_urlstringDownload url of the video
snstringSerial number of IPC which send this message

Face Recognize Message

The payload is formatted as follow.

POST / HTTP/1.1
Host: 192.168.103.173:8010
User-Agent: libcurl/7.52.1 OpenSSL/1.0.2p
Accept: /
Content-Length: 906
Content-Type: multipart/form-data; boundary=————————7faeecefd4fb5aaf

————————–7faeecefd4fb5aaf
Content-Disposition: form-data; name=”app_id”

KJQJ89V956U9O9UI
————————–7faeecefd4fb5aaf
Content-Disposition: form-data; name=”random”

956429
————————–7faeecefd4fb5aaf
Content-Disposition: form-data; name=”timestamp”

1597894809
————————–7faeecefd4fb5aaf
Content-Disposition: form-data; name=”sign”

004B3CD3FACB562E06CC04A0935410A5
————————–7faeecefd4fb5aaf
Content-Disposition: form-data; name=”payload”

{“event_id”:2,”faceid”:”358526″,”cloud_faceid”:”8798765433″,”group_name”:”db_0″,”age”:0,”age_range”:5,”gender”:0,”arrive_times”:3,”pic_url”:”https://192.168.103.117/mnt/sd-card/sunmi_image/snap/1597894624456_7.jpg?auth_key=1597894624-f88c2f9a6e69834430648c2f4931ffae”,”event_type”:”face_recog_event”,”sn”:”FS101D8BS00080″,”report_time”:1597894809}
————————–7faeecefd4fb5aaf–

The payload is formatted as follow.

ParameterTypeDescription
event_idlongEvent ID
event_typestringEvent Type
snstringSerial number of IPC which send this message
report_timelongTimestamp of event
faceidstringFace ID
cloud_faceidstringFace ID used in Sunmi Store
group_namestringName of group which the face belong to
ageintAge, if it’s blank, it means that the age of this face has not set yet
age_rangeintRange of age
1 — 1 to 6 years old
2 — 7 to 12 years old
3 — 13 to 18 years old
4 — 19 to 28 years old
5 — 29 to 35 years old
6 — 36 to 45 years old
7 — 45 to 55 years old
8 — 55 to 100 years old
genderintGender
0 — Undefined
1 — Male
2 — Female
arrive_timesintTotal times of arrival
pic_urlstringUrl of face picture
item1stringUser-defined attribute, only returned if exist
item2stringUser-defined attribute, only returned if exist
item3 stringUser-defined attribute, only returned if exist
item4stringUser-defined attribute, only returned if exist
item5stringUser-defined attribute, only returned if exist

2. Message Channel

Message channel allows user to maintain a tcp connect with IPC to communicate with IPC, it has the same function as Post Message.

2.1. Protocol

Protocol

The message channel use TCP connection with SSL to ensure the security of data. The protocol is implemented as Client/Server mode where the IPC is the server on port 10021.

Protocol Format

The protocol message, which consists of header, payload and CRC checksum, is described briefly in this section, as shown in the figure below.

  • Header

Flag

The “Flag” is fixed to 0xFF3E3EFF indicating it is using message channel.

Version

The “Version” describes the version of the protocol, it’s 0x01 for the moment. The protocol is backward compatible.

Packet Type

TypeValueDirectionDescription
Reserved0ProhibitReserved
CONNECT1Client to ServerClient send this message to establish connection
CONNACK2Server to ClientConnection acknowledge message sent by server, the content marks whether the connection is legal or not
PINGREQ3Client to ServerHeartbeat request
PINGRESP4Server to ClientHeartbeat response
SUBSCRIBE5Client to ServerClient send this message to subscribe events
SUBACK6Server to ClientConfirmation of subscription
UNSUBSCRIBE7CLient to ServerClient send this message to unsubscribe events
UNSUBACK8Server to ClientConfirm of unsubscription
PUBLISH9Client to Server, or Server to ClientOnly server can publish message to client for the moment
PUBACK10 Client to Server, or Server to Client Acknowledge to published message
DISCONNECT11 Client to Server, or Server to Client Disconnect

Length

“Length” is the length of the payload, which range from 0 to 65535.

  • Payload

“Payload” is the actual content of the message, which formatted with json. The payload is different for each packet type.

  • CRC Checksum

“CRC” is the CRC(Cyclic Redundancy Check) checksum of payload, which occupies 4 bytes.

2.2 Connection Establishment

The connection is initiated by client, and IPC act as server.

  • Initiate connection

The Packet Type of the message is 0x01, and the payload is formatted as bellow. The client will insert some parameters in payload, and sign the payload with secret key. The signature rule is described in Sign Rules section. The server check whether the content is legal with the same signature rule.

{
    "app_id": "mdk923idkf",
    "timestamp": "15930292837",
    "random": "289192",
    "sign": "IDKNFLK392038KDS932K",
    "keep_alive": 30
}

keep_alive: The period of heartbeat in unit of second, which can be specified by client.

  • Acknowledge to connection

The Packet Type of the message is 0x02, and the payload is formatted as bellow. The “code” represents the request result, possible return codes are 0, 1, 2, 3, 5, 7, refer to Error Code for more details.

{
    "code": 0
}

2.3 Heartbeat

The client send heartbeat message to server with specified period, and the server will disconnect after 3 heartbeat messages.

  • Heartbeat request

The header of the message is 0x03, and the payload is empty.

  • Heartbeat response

The header of the message is 0x04, and the payload is empty.

2.4 Subscribe

The client subscribes message to server.

  • Subscribe or unsubscribe

The header of the message is 0x05 or 0x07, and the payload is formatted as bellow.

{
    "event_list": [
        "dynamic_detect_event",
        "face_recog_event"
    ]
}

The fields of the payload is described as bellow.

Parameter Type Description
event_list string List of events to be subscribed

The supported events is listed bellow.

Event Type Description
dynamic_detect_event Dynamic detect event
face_recog_event Face recognition event
  • Response of subscribe or unsubscribe

The header of the message is 0x06 or 0x07, and the payload is formatted as follow. The “code” represents the request result, possible return codes are 0, 1, 2, 3, 5, 7, 310, 311, refer to Error Code for more details.

{
    "code": 0
}

2.5 Publish message

  • Publish

The IPC server publishe messages to client. The header of the message is 0x09, and the payload is different with event.

  • Dynamic detect message

The payload is formatted as follow.

{
    "event_id": 1,
    "event_type": "dynamic_detect_event",
    "sn": "FS101D8BS00106",
    "report_time": 15930292837,
    "detect_type": 1,
    "video_url": "https://192.168.0.1/mnt/sd-card/sunmi_video/video_detect/1565535983.flv?auth_key=1564129415215f61f3c5f552c5bf8f43ccef5c66a9"
}

The fields of the payload is described as follow.

NameTypeDescription
event_idlongEvent ID
event_typestringEvent Type
report_timelongTimestamp of the event
detect_typeintType of dynamic detect:
1: picture changed
2: voice changed
3: picture and voice changed
video_urlstringURL of video
snstringSerial number of the IPC which send this message
  • Face recognize message

The payload is formatted as follow.

{
    "event_id": 2,
    "event_type": "face_recog_event",
    "sn": "FS101D8BS00106",
    "report_time": 15930292837,
    "group_name": "vip",
    "faceid": "00000001",
    "cloud_faceid":"8798765433",
    "age": 10,
    "gender": 2,
    "arrive_times": 4,
    "pic_url":"https://192.168.103.117/mnt/sd-card/sunmi_image/snap/1597894624456_7.jpg?auth_key=1597894624-f88c2f9a6e69834430648c2f4931ffae",
    "vip_level": "1",
    "hobby": "tennis",
    "weight": "60",
    "height": "180"
}

The fields of the payload is described as follow.

NameTypeDescription
event_idlongEvent ID
event_typestringEvent Type
snstringSerial number of IPC which send this message
report_timelongTimestamp of event
faceidstringFace ID
cloud_faceidstring Face ID used in Sunmi Store
group_namestringName of group which the face belong to
ageintAge, if it’s blank, it means that the age of this face has not set yet
age_rangeintRange of age
1– 1 to 6 yeares old;
2– 7 to 12 years old;
3– 13 to 18 years old;
4– 19 to 28 years old;
5– 29 to 35 years old;
6– 36 to 45 years old;
7– 45 to 55 years old;
8– 55 to 100 years old.
genderintGender
0– Undefined;
1– Male;
2– Female.
arrive_timesintTotal times of arrival
pic_urlstringUrl of face picture
item1stringUser-defined attribute, only returned if exist.
item2stringUser-defined attribute, only returned if exist.
item3stringUser-defined attribute, only returned if exist.
item4stringUser-defined attribute, only returned if exist.
item5stringUser-defined attribute, only returned if exist.
  • Acknowledge to publish

If the subscriber received this message, it should return acknowledge. The header of the message is 0x0a, and the payload is formatted as fellow.

{
    "event_id": 1
}

The fields of the payload is described as follow.

NameTypeDescription
event_idlongEvent ID

2.6 Disconnect

The header of this message is 0x11, and the payload is empty.

Customer Flow Statistics

1.Set The Coordinates of Door Threshold

Description

The the door threshold is used to judge whether a person has came in or not. This API is used to set the coordinates of door threshold.

Request link

https://192.168.0.1/openapi/peopleFlow/setDoorLine, 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.

ParameterTypeDescriptionRequiredExample
resolutionintResolution of the image, 0 for 1080p, 1 for 720PY0
start_xintThe x-coordinate of the starting point of the door threshold, range is [0, 1920] for
1080p, and range is [0, 1280] for 720p
Y500
start_yintThe y-coordinate of the starting point of the door threshold, range is [0, 1080] for
1080p, and range is [0, 720] for 720p
Y 500
end_xintThe x-coordinate of the end point of the door threshold, range is [0, 1920] for 1080p,
and range is [0, 1280] for 720p
Y 500
end_yintThe y-coordinate of the end point of the door threshold, range is [0, 1080] for 1080p,
and range is [0, 720] for 720p
Y 500

Response Parameters

ParameterTypeDescription
codeintReturn code, represent the request result,
possible return codes are 0, 1, 2, 3, 5, 7, 277, 278, see Error Code for further details.

Request Example

POST openapi/peopleFlow/setDoorLineHTTP/1.1
Host: 192.168.0.1
Content-Type: application/x-www-form-urlencoded

app_id=mdk923idkf&random=289192×tamp=15930292837&sign=IDKNFLK392038KDS932K&resolution=0&start_x=1200&start_y=900&end_x =1500&end_y=900

Response Example

{
"code":  0
}

2.Get The Coordinates of Door Threshold

Description

Get the coordinates of door threshold.

Request link

https://192.168.0.1/openapi/peopleFlow/getDoorLine, 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

ParameterTypeDescription
codeintReturn code, represent the request result,
possible return codes are 0, 1, 2, 3, 5, 7, 260, 261, 262, 263, 264, 276, 277, 279, see Error Code for further details.
resolutionintResolution of the image, 0 for 1080p, 1 for 720P
start_xintThe x-coordinate of the starting point of the door threshold, range is [0, 1920] for
1080p, and range is [0, 1280] for 720p
start_yintThe y-coordinate of the starting point of the door threshold, range is [0, 1080] for
1080p, and range is [0, 720] for 720p
end_xintThe x-coordinate of the end point of the door threshold, range is [0, 1920] for 1080p,
and range is [0, 1280] for 720p
end_yintThe y-coordinate of the end point of the door threshold, range is [0, 1080] for 1080p,
and range is [0, 720] for 720p

Request Example

POST openapi/peopleFlow/getDoorLine 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,
    "data": {
    "resolution": 0,
    "start_x": 1200,
    "start_y": 900,
    "end_x": 1500,
    "end_y": 900
    }
}

3. Get Flow Statistics Settings

Description

Get flow statistics settings.

Request Link

https://192.168.0.1/openapi/peopleFlow/getConfig, 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

ParameterTypeDescription
codeintReturn code, represent the request result,
possible return codes are 0, 1, 2, 3, 5, 7, see Error Code for further details.
facerecog_intervalintThe deduplication time of face recognition in seconds.
customer_judgemodeintCustomer flow mode, 0 is snapshot mode and 1 is normal mode.

Request Example

POST openapi/peopleFlow/getConfig HTTP/1.1
Host: 192.168.0.1
Content-Type: application/x-www-form-urlencoded

app_id=mdk923idkf&random=289192&timestamp=15930292837&sign=IDKNFLK392038KDS932K

Response Example

{
  "code": 0,
  "data":{
    "facerecog_interval":60,
    "customer_judgemode":1
  }
}

4. Set Flow Statistics Settings

Description

Set flow statistics settings. The parameter “facerecog_interval” is the deduplication time of face recognition, in which period only the first entry of a face will be reported. The parameter “customer_judgemode” sets the customer flow mode. The events will be reported depending on the movement and size change of faces if in normal mode, while in snapshot mode they will be reported immediately once faces show up.

Request Link

https://192.168.0.1/openapi/peopleFlow/setConfig, 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.

ParameterTypeDescription
facerecog_intervalint The deduplication time of face recognition in seconds, range is [0,86400].
customer_judgemodeintCustomer flow mode, 0 is snapshot mode and 1 is normal mode.

Response Parameters

ParameterTypeDescription
codeintReturn 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/peopleFlow/getDoorLine HTTP/1.1
Host: 192.168.0.1
Content-Type: application/x-www-form-urlencoded

app_id=mdk923idkf&random=289192&timestamp=15930292837&facerecog_interval=10&customer_judgemode=0&sign=IDKNFLK392038KDS932K

Response Example

{
  "code": 0
}

5.Get Inflow Customer Statistics For A Specified Time

Description

Get inflow customer statistics in a specified time. Error will be returned if no record is found.

Request link

https://192.168.0.1/openapi/peopleFlow/getPeopleStat, 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.

ParameterTypeDescriptionRequiredExample
start_timelongStart time, UNIX format timestamp in second. Y1578969264
end_timelongEnd time, UNIX format timestamp in second. Y1579055640
periodintTime granularity, 1: half an hour; 2: one hour; 3: one day.Y2

Response Parameters

ParameterTypeDescription
codeint Return code, represent the request result,
possible return codes are 0, 1, 2, 3, 5, 7, 211, 220, 265, 266, 267, 277, 280, see Error Code for further details.
totalintTotal number of people
start_timelongStart time of Statistics
end_timelongEnd time of Statistics
male_num_statarrayThere are 8 integers in the integer array, representing the male statistical
data of 1-6 years old, 7-12 years old, 13-18 years old, 19-28 years old, 29-35
years old, 36-45 years old, 46-55 years old and 56-100 years old respectively.
female_num_statarrayThere are 8 integers in the integer array, representing the female statistical
data of 1-6 years old, 7-12 years old, 13-18 years old, 19-28 years old, 29-35
years old, 36-45 years old, 46-55 years old and 56-100 years old respectively.

Request Example

POST openapi/peopleFlow/getPeopleStat HTTP/1.1
Host: 192.168.0.1
Content-Type: application/x-www-form-urlencoded

app_id=mdk923idkf&random=289192×tamp=15930292837&sign=IDKNFLK392038KDS932K&start_time=1561910400&end_time=1562083200&period=3

Note: This example is to get the customer flow statistics from 2019-07-01 to 2019-07-02 with the time granularity of one day.

Response Example

{
    "code": 0,
    "data": {
    "total": 2998,
    "stat_list": [{
            "start_time": 1561910400,
            "end_time": 1561996800,
            "total": 1499,
            "male_num_stat": [10, 20, 50, 109, 280, 380, 156, 10],
            "female_num_stat": [11, 34, 50, 78, 132, 45, 123, 11]
        },
        {
            "start_time": 1561996800,
            "end_time": 1562083200,
            "total": 1499,
            "male_num_stat": [10, 20, 50, 109, 280, 380, 156, 10],
            "female_num_stat": [11, 34, 50, 78, 132, 45, 123, 11]
        }]
    }
}

6.Get Pass-by Customer Statistics For A Specified Time

Description

Get pass-by customer statistics in a specified time. Error will be returned if no record is found.

Request link

https://192.168.0.1/openapi/peopleFlow/getPeopleStatPass, 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.

ParameterTypeDescriptionRequiredExample
start_timelongStart time, UNIX format timestamp in second. Y1578969264
end_timelongEnd time, UNIX format timestamp in second. Y1579055640
periodintTime granularity, 1: half an hour; 2: one hour; 3: one day.Y2

Response Parameters

ParameterTypeDescription
codeint Return code, represent the request result,
possible return codes are 0, 1, 2, 3, 5, 7, 211, 220, 265, 266, 267, 277, 280, see Error Code for further details.
totalintTotal number of people
start_timelongStart time of Statistics
end_timelongEnd time of Statistics

Request Example

POST openapi/peopleFlow/getPeopleStatPass HTTP/1.1
Host: 192.168.0.1
Content-Type: application/x-www-form-urlencoded

app_id=mdk923idkf&random=289192×tamp=15930292837&sign=IDKNFLK392038KDS932K&start_time=1561910400&end_time=1562083200&period=3

Note: This example is to get the customer flow statistics from 2019-07-01 to 2019-07-02 with the time granularity of one day.

Response Example

{
    "code": 0,
    "data": {
    "total": 2998,
    "stat_list": [{
            "start_time": 1561910400,
            "end_time": 1561996800,
            "total": 1499,
        },
        {
            "start_time": 1561996800,
            "end_time": 1562083200,
            "total": 1499,
        }]
    }
}

7.Get Outflow Customer Statistics For A Specified Time

Description

Get outflow customer statistics in a specified time. Error will be returned if no record is found.

Request link

https://192.168.0.1/openapi/peopleFlow/getPeopleStatOut, 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.

ParameterTypeDescriptionRequiredExample
start_timelongStart time, UNIX format timestamp in second. Y1578969264
end_timelongEnd time, UNIX format timestamp in second. Y1579055640
periodintTime granularity, 1: half an hour; 2: one hour; 3: one day.Y2

Response Parameters

ParameterTypeDescription
codeint Return code, represent the request result,
possible return codes are 0, 1, 2, 3, 5, 7, 211, 220, 265, 266, 267, 277, 280, see Error Code for further details.
totalintTotal number of people
start_timelongStart time of Statistics
end_timelongEnd time of Statistics

Request Example

POST openapi/peopleFlow/getPeopleStatOut HTTP/1.1
Host: 192.168.0.1
Content-Type: application/x-www-form-urlencoded

app_id=mdk923idkf&random=289192×tamp=15930292837&sign=IDKNFLK392038KDS932K&start_time=1561910400&end_time=1562083200&period=3

Note: This example is to get the customer flow statistics from 2019-07-01 to 2019-07-02 with the time granularity of one day.

Response Example

{
    "code": 0,
    "data": {
    "total": 2998,
    "stat_list": [{
            "start_time": 1561910400,
            "end_time": 1561996800,
            "total": 1499,
        },
        {
            "start_time": 1561996800,
            "end_time": 1562083200,
            "total": 1499,
        }]
    }
}

8. Get The List of Visitors In A Specified Time

Description

Get the list of vistors sorted by arrival times in a specified time.

Request link

https://192.168.0.1/openapi/peopleFlow/getVisitorList, 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.

ParameterTypeDescriptionRequiredExample
start_timelongUNIX format timestamp in second.Y1578969264
end_timelongUNIX format timestamp in second.Y1579055640
orderintNumber of records sorted by arrival times.Y50
group_namestringSpecify a face group, default to all face groups.Nvip
genderintGender, 1 for male, 2 for female, both male and female if this parameter not provided.N1
age_rangeintAge group: 1 for [1,6], 2 for [7,12], 3 for [13,18], 4 for [19,28], 5 for [29,35],
6 for [36,45], 7 for [46,55], 8 for [56, 100]
N4
ageintAge and age range are mutually exclusive. First query the faces that meet the age. If the
age is not provided but the age range is provided, query the faces that meet the age range;
if the age and the age range are not provided, query the faces of all ages.
N4
item1stringIt can be matched according to the custom attribute, and the match of the custom attribute 1.
If you need to use the custom attribute query, make sure that the specified face group has added
the corresponding custom attribute, otherwise the query fails (you cannot add the custom attribute
for the group of strangers and regular)
Nvalue1
item2stringMatch of custom attribute 2Nvalue2
item3stringMatch of custom attribute 3Nvalue3
item4stringMatch of custom attribute 4Nvalue4
item5stringMatch of custom attribute 5Nvalue5
page_numintCurrent page number, default and minimum is 1N1
page_sizeintCurrent page entries, default is 10, range is [1, 100]N10

Response Parameters

ParameterTypeDescription
codeint Return code, represent the request result,
possible return codes are 0, 1, 2, 3, 5, 7, 211, 220, 266, 267, 268, 269, 270, 271, 272,
273, 274, 277, 280, 281, 282, see Error Code for further details.
total_numintTotal number of faces meeting the specified conditions
return_numintCurrent number of faces
faceidstringFace ID
group_namestringGroup name
agestringAge. If it is blank, the real age is not set
age_rangeint1 for [1,6], 2 for [7,12], 3 for [13,18], 4 for [19,28], 5 for [29,35], 6 for [36,45], 7 for [46,55], 8 for [56, 100]
genderintGender, 0 for unknown, 1 for male, 2 for female
arrive_timesintNumber of arrivals
item1stringCustom attribute 1, which will be returned only after the user has added it
item2stringCustom attribute 2, which will be returned only after the user has added it
item3stringCustom attribute 3, which will be returned only after the user has added it
item4stringCustom attribute 4, which will be returned only after the user has added it
item5stringCustom attribute 5, which will be returned only after the user has added it

Request Example

The following is a list of face ID information obtained from 30-year-old male VIP guests who have visited most times in two days from June 14, 2019 to June 15, 2019.

POST openapi/peopleFlow/getVisitorList HTTP/1.1
Host: 192.168.0.1
Content-Type: application/x-www-form-urlencoded

app_id=mdk923idkf&random=289192×tamp=15930292837&sign=IDKNFLK392038KDS932K&
order=2&start_date=1560441600&end_date=1560528000&gropu_name=vip&age=30&gender=1&item1=value1&&item2=value2&&item3=value3&&item4=value5&&item5=value5

Response Example

{
    "code": 0,
    "data": {
    "total_num": 2,
    "return_num": 2,
    "face_list": [{
        "faceid": "000001",
        "group_name": "vip",
        "age": "32",
        "age_range": 5,
        "gender': 1, 
        "arrive_times": 100,
        "item1": value1, //Custom attribute 
        "item2": value2, //Custom attribute 
        "item3": value3, //Custom attribute 
        "item4": value4, //Custom attribute
        "item5": value5 //Custom attribute 
        }, {
        "faceid": "000002",
        "group_name": "vip",
        "age": "30",
        "age_range": 5,
        "gender": 1,
        "arrive_times": 99,
        "item1": value1, //Custom attribute 
        "item2": value2, //Custom attribute
        "item3": value3, //Custom attribute
        "item4": value4, //Custom attribute 
        "item5": value5 //Custom attribute
        }]
    }
}

9. Get The Visit Records of A Specified Face ID

Description

Get the visit records of a specified face ID within a specified time.

Request link

https://192.168.0.1/openapi/peopleFlow/getFaceVisitDetail, 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.

ParameterTypeDescriptionRequiredExample
start_timelongUNIX format timestamp in second.Y1578969264
end_timelongUNIX format timestamp in second.Y1579055640
faceidstringFace IDY 000001

Response Parameters

ParameterTypeDescription
codeint Return code, represent the request result,
possible return codes are 0, 1, 2, 3, 5, 7, 211, 220, 266, 267, 275, 277, 280, see Error Code for further details.
total_timesintTotal visits
came_in_timelong arrayList of visit times

Request Example

POST openapi/peopleFlow/getFaceVisitDetail HTTP/1.1
Host: 192.168.0.1
Content-Type: application/x-www-form-urlencoded

app_id=mdk923idkf&random=289192×tamp=15930292837&sign=IDKNFLK392038KDS932K&start_time=1561910400&end_time=1562083200&faceid=000002

Note: This example is to get the visit list of faceid “000002” from July 1, 2019 to July 2, 2019.

Response Example

{
    "code": 0,
    "data": {
    "total_times": 2,
    "came_in_time": [1561910400, 1561996800]
    }
}

Face Recognition

  1. Create Face Group
  2. Edit Face Group
  3. Configure The Stranger-to-regular Conditions
  4. Delete Face Group
  5. Get The List of Face Group
  6. Add Attributes to A Face Group
  7. Delete Attributes of A Face Group
  8. Get List of User-defined Attributes of A Face Group
  9. Add Face Record
  10. Delete Face Record
  11. Update Face Record
  12. Get Face Record
  13. Get List of Face Records
  14. Get Face Records That Don’t Arrival For The Longgest Time
  15. Get Face Record By Picture

1. Create Face Group

Description

Create a new face group via this interface and configure its attributes. The IPC supports up to 10 face groups including the default stranger group and regular group and maximum 8 user groups.

Request link

https://192.168.0.1/ openapi/face/createGroup, 192.168.0.1 needs to be replaced with the actual IP address of IPC.

Request Parameters

Below are private parameters for this API, please refer to Public Parameters for more details.

ParameterTypeDescriptionRequiredExample
name string The name of group, maximum 96 characters. The system has two default group,
stranger and regular.
Yvip
capacity int Capacity of group, the sum of all group capacities shall not exceed 30000.Y10000
DescriptionstringDescription of group, maximum 150 characters.
YCustomers with gold card.

Note:

1. The first character of name shall not be a blank space;

2. By default, the name of stranger group is stranger, the name of regular group is regular.

Response Parameters

ParameterTypeDescription
code int Return code, represent the request result,
possible return codes are 0, 1, 2, 3, 5, 7, 200, 201, 202, 211, 212, 220, see Error Code for further details.

Request Example

POST openapi/face/createGroup HTTP/1.1
Host: 192.168.0.1
Content-Type: application/x-www-form-urlencoded

app_id=mdk923idkf&random=289192&timestamp=15930292837&sign=IDKNFLK392038KDS932K& name=vip&capacity=10000&description=Customers with gold card.

Response Example

{
    "code": 0
}

2. Edit Face Group

Description

This API is used to edit attributes of a face group.

Request link

https://192.168.0.1/openapi/face/updateGroup, 192.168.0.1 needs to be replaced with the actual IP address of IPC.

Request Parameters

Below are private parameters for this API, please refer to Public Parameters for more details.

ParameterTypeDescriptionRequiredExample
old_name string The name of Face Group you want to modify. Y vip
name string The new name of Face Group, can be same with old_name.Y svip
capacity int The new capacity of Face Group, can be same with the old capacity. Y 10000
Descriptionstring Description of group, maximum 150 characters. Y Customers with platinum card.

Note:

1.name must be same with old_name when you edit stranger group or regular group, in other words, the name of default groups art not allowed to be modified;

2.The first character of name shall not be a blank space.

Response Parameters

ParameterTypeDescription
code int Return code, represent the request result,
possible return codes are 0, 1, 2, 3, 5, 7, 200, 201, 202, 204, 211, 212, 220, see Error Code for further details.

Request Example

POST openapi/face/updateGroup HTTP/1.1
Host: 192.168.0.1
Content-Type: application/x-www-form-urlencoded

app_id=mdk923idkf&random=289192&timestamp=15930292837&sign=IDKNFLK392038KDS932K& old_name=vip&name=svip&capacity=10000&description=Customers with platinum card.

Response Example

{
    "code": 0
}

3. Configure The Stranger-to-regular Conditions

Description

Stranger and regular face groups will be created once the IPC is activated. The records in stranger face group will be moved to the regular face group when they meet the moving conditions which is 5 times in 7 days by default. This API is used to Configure The Stranger-to-regular Conditions.

Request Link

https://192.168.0.1/openapi/face/updateMigration, 192.168.0.1 needs to be replaced with the actual IP address of IPC.

Request Parameters

Below are private parameters for this API, please refer to Public Parameters for more details.

ParameterTypeDescriptionRequiredExample
arrive_times int value range 1~10.Y 5
period int value range 1~100, unit: day.Y 20

Note:

It means that record will be move from stranger to regular while the face was captured more than [arrive_times] times in [period] days. So this api is only applicable to the stranger face group.

Response Parameters

ParameterTypeDescription
code int Return code, represent the request result,
possible return codes are 0, 1, 2, 3, 5, 7, 204, 211, 220, see Error Code for further details.

Request Example

POST openapi/face/updateMigrationHTTP/1.1
Host: 192.168.0.1
Content-Type: application/x-www-form-urlencoded

app_id=mdk923idkf&random=289192&timestamp=15930292837&sign=IDKNFLK392038KDS932K&arrive_times=5&period=3

Response Example

{
    "code": 0
}

4. Delete Face Group

Description

Delete the specified face group.

Request Link

https://192.168.0.1/openapi/face/deleteGroup, 192.168.0.1 needs to be replaced with the actual IP address of IPC.

Request Parameters

Below are private parameters for this API, please refer to Public Parameters for more details.

ParameterTypeDescriptionRequiredExample
name string The name of group to be deleted, stranger and regular group are not
allowed to be deleted. The group should be empty before it is deleted.
Y vip

Response Parameters

ParameterTypeDescription
code int Return code, represent the request result,
possible return codes are 0, 1, 2, 3, 5, 7, 201, 204, 205, 211, 220, see Error Code for further details.

Request Example

POST openapi/face/deleteGroup HTTP/1.1
Host: 192.168.0.1
Content-Type: application/x-www-form-urlencoded

app_id=mdk923idkf&random=289192&timestamp=15930292837&sign=IDKNFLK392038KDS932K& name=vip

Response Example

{
    "code": 0
}

5. Get The List of Face Group

Description

This API is used to get infomations of all groups.

Request Link

https://192.168.0.1/openapi/face/getGroupList, 192.168.0.1 needs to be replaced with the actual IP address of IPC.

Request Parameters

No private parameter for this API, please refer to Public Parameters for more details.

Response Parameters

ParameterTypeDescription
code int Return code, represent the request result,
possible return codes are 0, 1, 2, 3, 5, 7, 211, 220, see Error Code for further details.
num int number of groups
name string name of group
capacity int capacity of group.
Descriptionstring description of group.
times int attribute only for stranger.
period int attribute only for stranger.
count int number of records in the group.

Request Example

POST openapi/face/getGroupList HTTP/1.1
Host: 192.168.0.1
Content-Type: application/x-www-form-urlencoded

app_id=mdk923idkf&random=289192&timestamp=15930292837&sign=IDKNFLK392038KDS932K

Response Example

{
    "data": {
        "face_group": [
            {
                "capacity": 5000,
                "count": 0,
                "name": "regular",
                "description": "this is regular group"
            },
            {
                "capacity": 1000,
                "count": 0,
                "name": "employee",
                "description": "this is employee group"
            },
            {
                "capacity": 1000,
                "count": 0,
                "name": "blacklist",
                "description": "this is blacklist group"
            },
            {
                "name": "stranger",
                "times": 5,
                "capacity": 1000,
                "count": 0,
                "period": 2,
                "description": "this is stranger group"
            }
        ],
        "num": 4
    },
    "code": 0
}

6. Add Attributes to A Face Group

Description

Each face group has 5 user-defined fields or attributes that can be filled with string with up to 50 characters for every records, except the default groups.

It is strongly recommended to add user-defined attributes after creating the face group and before adding any record with this interface.

Request Link

https://192.168.0.1/openapi/face/addFaceInfoItem, 192.168.0.1 needs to be replaced with the actual IP address of IPC.

Request Parameters

Below are private parameters for this API, please refer to Public Parameters for more details.

ParameterTypeDescriptionRequiredExample
num int Number of attributes to add. Y 1
group_name string Name of group. Y vip
name_list string array Attribute name list, maximum 50 characters in length for each name.Y [“hobby”]

Note:

1. The default groups (stranger and regular) are not allowed to add attributes;

2. The following names are reserved and can not be used as attribute names: group_name, pic, age, gender, faceid, age_range, arrive_times, pic_url, total_num, return_num。

Response Parameters

ParameterTypeDescription
code int Return code, represent the request result,
possible return codes are 0, 1, 2, 3, 5, 7, 204, 211, 220, 240, 241, 242, see Error Code for further details.

Request Example

POST openapi/face/addFaceInfoItem HTTP/1.1
Host: 192.168.0.1
Content-Type: application/x-www-form-urlencoded

app_id=mdk923idkf&random=289192&timestamp=15930292837&sign=IDKNFLK392038KDS932K& num=2&group_name=vip&name_list=[“phone_num”, “weight”]

Response Example

{
    "code": 0
}

7. Delete Attributes of A Face Group

Description

This interface is used to delete user-defined attributes in a specified face group.

Request Link

https://192.168.0.1/openapi/face/removeFaceInfoItem, 192.168.0.1 needs to be replaced with the actual IP address of IPC.

Request Parameters

Below are private parameters for this API, please refer to Public Parameters for more details.

ParameterTypeDescriptionRequiredExample
num int Number of attributes to delete. Y 1
group_name string Name of group Y vip
name_list string Attribute name list, maximum 50 characters in length for each name.Y [“hobby”]

Note: ID of default group cannot be deleted.

Response Parameters

ParameterTypeDescription
code int Return code, represent the request result,
possible return codes are 0, 1, 2, 3, 5, 7, 204, 211, 220, 240, 241, 242, 243, see Error Code for further details.

Request Example

POST openapi/face/removeFaceInfoItem HTTP/1.1
Host: 192.168.0.1
Content-Type: application/x-www-form-urlencoded

app_id=mdk923idkf&random=289192&timestamp=15930292837&sign=IDKNFLK392038KDS932K& num=2&group_name=vip&name_list=[“phone_num”, “weight”]

Response Example

{
    "code": 0
}

8. Get List of User-defined Attributes of A Face Group

Description

This interface is used to get the list of user-defined attribute of a specified group.

Request Link

https://192.168.0.1/openapi/face/getFaceInfoItem, 192.168.0.1 needs to be replaced with the actual IP address of IPC.

Request Parameters

Below are private parameters for this API, please refer to Public Parameters for more details.

Parameter Type Description Required Example
group_name string name of group Y stranger

Response Parameters

ParameterTypeDescription
code int Return code, represent the request result,
possible return codes are 0, 1, 2, 3, 5, 7, 204, 211, 220, see Error Code for further details.
num int Number of attributes.
name_list string Attribute name list.

Request Example

POST openapi/face/getFaceInfoItemHTTP/1.1
Host: 192.168.0.1
Content-Type: application/x-www-form-urlencoded  

app_id=mdk923idkf&random=289192&timestamp=15930292837&sign=IDKNFLK392038KDS932K& num=2&group_name=vip

Response Example

{
    "code": 0,
    "data": {
        "num": 3,
        "name_list": [
            "phone",
            "address",
            "vip_level"
        ]
    }
}

9. Add Face Record

Description

This API is used to add a face record in the specified group.

Request Type

Content-Type is multipart/form-data, and all arguments except file are signed according to the signature rules.

Request Link

https://192.168.0.1/openapi/face/addFace, 192.168.0.1 needs to be replaced with the actual IP address of IPC.

Request Parameters

Below are private parameters for this API, please refer to Public Parameters for more details.

ParameterTypeDescriptionRequiredExample
faceidstringFaceid, a positive 64-bit numeric string, the device will generate if not supply.N123456
pic file Face photo file in jpg/png format, maximum resulution is 1920*1080,
the size of file must not exceed 1M bytes.
Y example.jpg
group_name string name of group Y stranger
age int preset attribute, age N 14
gender int preset attribute , gender, 0 for unknown, 1 for male, 2 for female N 1
item1 string user-defined attribute 1 N value1
item2 string user-defined attribute 2 N value2
item3 string user-defined attribute 3 N value3
item4 string user-defined attribute 4 N value4
item5 string user-defined attribute 5N value5

Note:

1.The preset attributes above are built-in attribute of face record in the databse, and others include item1/item2/item3/item4/item5 are user-defined attributes. Users must call the interface to add user-defined attributes before using; The IPC will ignore the parameters if the corresponding attributes are not found.

2.If the attribute age is not provided, the age range will be set automatically by the IPC;

3. If the attribute gender is not provided, this field will be set automatically by the IPC.

Response Parameters

ParameterTypeDescriptionExample
code int Return code, represent the request result,
possible return codes are 0, 1, 2, 3, 5, 7, 204, 206, 208, 210, 211, 220, see Error Code for further details.
faceidstringfaceid123456

Request Example

POST /openapi/face/addFace HTTP/1.1
Host: 192.168.0.1
Content-Type: multipart/form-data; boundary=————————–962974737227706390007700
Content-Length: 1683

—————————-962974737227706390007700
Content-Disposition: form-data; name=”app_id”

mdk923idk
—————————-962974737227706390007700
Content-Disposition: form-data; name=”faceid”

Vip11024
—————————-962974737227706390007700
Content-Disposition: form-data; name=”random”  

289192
—————————-962974737227706390007700
Content-Disposition: form-data; name=”timestamp”  

15930292837
—————————-962974737227706390007700
Content-Disposition: form-data; name=”sign”  

IDKNFLK392038KDS932K
—————————-962974737227706390007700
Content-Disposition: form-data; name=”group_name”  

VIP
—————————-962974737227706390007700
Content-Disposition: form-data; name=”age”  

21
—————————-962974737227706390007700
Content-Disposition: form-data; name=”gender”  

1
—————————-962974737227706390007700
Content-Disposition: form-data; name=”hobby”  

hiking
—————————-962974737227706390007700
Content-Disposition: form-data; name=”vip_level”  

2
—————————-962974737227706390007700
Content-Disposition: form-data; name=”weight”  

60
—————————-962974737227706390007700
Content-Disposition: form-data; name=”phone_num”  

1234
—————————-962974737227706390007700
Content-Disposition: form-data; name=”pic”; filename=”11024.jpg”
Content-Type: image/jpeg  

(binary data of picture)
—————————-962974737227706390007700–

Note:

The above hobby, vip_level, weight and phone_num are user-defined attributes, should be added before using them.

Response Example

{
    "code": 0
    "data": {
        "faceid": "123456"
    }
}

10. Delete Face Record

Description

This API is used to delete the face records from the specified group.

Request Link

https://192.168.0.1/openapi/face/deleteFace, 192.168.0.1 needs to be replaced with the actual IP address of IPC.

Request Parameters

Below are private parameters for this API, please refer to Public Parameters for more details.

ParameterTypeDescriptionRequiredExample
num int Number of face records to delete Y 1
group_name string Name of group Y Example
faceid_list string array List of face record to delete. Y [“105”]

Response Parameters

Paramter TypeDescription
code int Return code, represent the request result,
possible return codes are 0, 1, 2, 3, 5, 7, 204, 211, 220, see Error Code for further details.
success_list string array List of face records that have been deleted
failed_list string array List of failed deleting face records
not_exist_list string array List of face records that are not exist.

Request Example

POST openapi/face/deleteFace HTTP/1.1
Host: 192.168.0.1
Content-Type: application/x-www-form-urlencoded  

app_id=mdk923idkf&random=289192&timestamp=15930292837&sign=IDKNFLK392038KDS932K& group_name=vip&faceid_list=[“000001”, “0000002”]&num=2

Response Example

{
    "code": 0,
    "data": {
        "success_list": [
            "000001",
            "000002"
        ],
        "failed_list": [],
        "not_exist_list": [
            "000003"
        ]
    }
}

11. Update Face Record

Description

Update the information of the specified face record.

Request Link

https://192.168.0.1/openapi/face/updateFace, 192.168.0.1 needs to be replaced with the actual IP address of IPC.

Request Method

Content-Type is multipart/form-data, and all arguments except file are signed according to the signature rules.

Request Parameters

Below are private parameters for this API, please refer to Public Parameters for more details.

ParameterTypeDescriptionRequiredExample
group_name string Name of group Y svip
faceid string Face ID Y 21
new_group_name string New group name, the record will be moved to this group if provided. N vip
pic file Face photo file in jpg/png format, maximum resulution is 1920*1080,
the size of file must not exceed 1M bytes.
N example.jpg
age int preset attribute, age N 10
gender int preset attribute , gender, 0 for unknown, 1 for male, 2 for female N 1
item1 string user-defined attribute 1 N value1
item2 string user-defined attribute 2 N value2
item3 string user-defined attribute 3 N value3
item4 string user-defined attribute 4 N value4
item5 string user-defined attribute 5 N value5

Response Parameters

ParameterTypeDescription
code int Return code, represent the request result,
possible return codes are 0, 1, 2, 3, 5, 7, 204, 207, 208, 210, 211, 220, see Error Code for further details.

Request Example

POST /openapi/face/addFace HTTP/1.1
Host: 192.168.0.1
Content-Type: multipart/form-data; boundary=————————–962974737227706390007700
Content-Length: 1683  

—————————-962974737227706390007700
Content-Disposition: form-data; name=”app_id”  

mdk923idk
—————————-962974737227706390007700
Content-Disposition: form-data; name=”random”  

289192
—————————-962974737227706390007700
Content-Disposition: form-data; name=”timestamp”  

15930292837
—————————-962974737227706390007700
Content-Disposition: form-data; name=”sign”  

IDKNFLK392038KDS932K
—————————-962974737227706390007700
Content-Disposition: form-data; name=”group_name”  

stranger
—————————-962974737227706390007700
Content-Disposition: form-data; name=”facdid”  

21
—————————-962974737227706390007700
Content-Disposition: form-data; name=”new_group_name”  

VIP
—————————-962974737227706390007700
Content-Disposition: form-data; name=”hobby”  

hiking
—————————-962974737227706390007700
Content-Disposition: form-data; name=”vip_level”  

2
—————————-962974737227706390007700
Content-Disposition: form-data; name=”weight”  

60
—————————-962974737227706390007700
Content-Disposition: form-data; name=”phone_num”  

1234
—————————-962974737227706390007700–

Note:

The above hobby, vip_level, weight and phone_num are user-defined attributes, should be added before using them.

Response Example

{
    "code": 0
}

12. Get Face Record

Description

Get information of the face record by face ID.

Request Link

https://192.168.0.1/openapi/face/getFace, 192.168.0.1 needs to be replaced with the actual IP address of IPC.

Request Parameters

Below are private parameters for this API, please refer to Public Parameters for more details.

ParameterTypeDescriptionRequiredExample
faceid string faceid Y 123456

Response Parameters

ParameterTypeDescription
code int Return code, represent the request result,
possible return codes are 0, 1, 2, 3, 5, 7, 211, see Error Code for further details.
faceid string Face ID
group_name string Group name
age int age, NULL means user has not set the age of the face record.
age_range int age range, 1 means 1~6 years old, 2 means 7~12 years old, 3 means 13~18
years old, 5 means 19~28 years old, 5 means 29~35 years old, 6 means
36~45 years old, 7 means 45~55 years old, 8 means 55~100 years old
gender int gender, 0 means unknown, 1 means male, 2 means female
arrive_count int Total number of arrivals
arrive_time int Timestamp of the last arrival
item1 string User-defined attribute 1, only returned if exist.
item2 string User-defined attribute 2, only returned if exist.
item3 string User-defined attribute 3, only returned if exist.
item4 string User-defined attribute 4, only returned if exist.
item5 string User-defined attribute 5, only returned if exist.

Request Example

POST openapi/face/getFace HTTP/1.1
Host: 192.168.0.1
Content-Type: application/x-www-form-urlencoded

app_id=mdk923idkf&random=289192&timestamp=15930292837&sign=IDKNFLK392038KDS932K&
faceid=4

Response Example

{
    "code": 0,
    "data": {
        "arrive_time": 1566215943,
        "arrive_count": 2,
        "faceid": "123456",
        "group_name": "vip",
        "point": "113",
        "gender": 1,
        "age": 10,
        "age_range": 2,
        "vip_level": "1",
        "hobby": "tennis",
        "weight": "60",
        "height": "180"
    }
}

Note:

The above hobby, vip_level, weight and phone_num are user-defined attributes, should be added before using them.

13. Get List of Face Records

Description

Get list of the face records in the specified group.

Request Link

https://192.168.0.1/openapi/face/getFaceList, 192.168.0.1 needs to be replaced with the actual IP address of IPC.

Request Parameters

Below are private parameters for this API, please refer to Public Parameters for more details.

ParameterTypeDescriptionRequiredExample
group_name string name of group Y vip
page_num int Current page number, default and minimum is 1 N 4
page_size int Current page entries, default is 10, range is [1, 100] N 10

Response Parameters

ParameterTypeDescription
code int Return code, represent the request result,
possible return codes are 0, 1, 2, 3, 5, 7, 211, see Error Code for further details.
total_num int Total number of face records
return_num int Number of face records currently returned
faceid string Face ID
age int age, NULL means user has not set the age of the face record.
age_range int age range, 1 means 1~6 years old, 2 means 7~12 years old, 3 means 13~18
years old, 5 means 19~28 years old, 5 means 29~35 years old, 6 means
36~45 years old, 7 means 45~55 years old, 8 means 55~100 years old
gender int gender, 0 for unknown, 1 for male, 2 for female
arrive_count int Total number of arrivals
arrive_time int Timestamp of the last arrival
item1 string User-defined attribute 1, only returned if exist.
item2 string User-defined attribute 2, only returned if exist.
item3 string User-defined attribute 3, only returned if exist.
item4 string User-defined attribute 4, only returned if exist.
item5 string User-defined attribute 6, only returned if exist.

Request Example

POST openapi/face/getFaceIDList HTTP/1.1
Host: 192.168.0.1
Content-Type: application/x-www-form-urlencoded

app_id=mdk923idkf&random=289192&timestamp=15930292837&sign=IDKNFLK392038KDS932K& group_name=vip

Response Example

{
    "code": 0,
    "data": {
        "total_num": 2,
        "num": 2,
        "faceid_list": [
            {
                "arrive_time": 1566215929,
                "arrive_count": 2,
                "faceid": "3",
                "point": "113",
                "gender": 2,
                "vip_level": "3",
                "hobby": "tennis",
                "weight": "60",
                "height": "180",
                "age": 10,
                "age_range": 2
            },
            {
                "arrive_time": 1566215998,
                "arrive_count": 1,
                "faceid": "4",
                "point": "113",
                "gender": 1,
                "vip_level": "1",
                "hobby": "tennis",
                "weight": "60",
                "height": "180",
                "age": 10,
                "age_range": 2
            }
        ]
    }
}

14. Get Face Records That Don’t Arrive For The Longest Time

Description

Get list of last N face records sorted by the “last arrival” time.

Request Link

https://192.168.0.1/openapi/face/getFaceByArrival, 192.168.0.1 needs to be replaced with the actual IP address of IPC.

Request Parameters

Below are private parameters for this API, please refer to Public Parameters for more details.

ParameterTypeDescriptionRequiredExample
group_name string Name of group Y vip
num int Number of face records, range is 1~10, default is 1. N 2

Response Parameters

ParameterTypeDescription
code int Return code, represent the request result,
possible return codes are 0, 1, 2, 3, 5, 7, 207, 211, see Error Code for further details.
return_num int Number of face records currently returned
faceid string Face ID
age int Age, NULL means user has not set the age of the face record.
age_range int age range, 1 means 1~6 years old, 2 means 7~12 years old, 3 means 13~18
years old, 5 means 19~28 years old, 5 means 29~35 years old, 6 means
36~45 years old, 7 means 45~55 years old, 8 means 55~100 years old
gender int Gender, 0 for unknown, 1 for male, 2 for female
arrive_count int Total number of arrivals
arrive_time int Timestamp of the last arrival
item1 string User-defined attribute 1, only returned if exist.
item2 string User-defined attribute 2, only returned if exist.
item3 string User-defined attribute 3, only returned if exist.
item4 string User-defined attribute 4, only returned if exist.
item5 string User-defined attribute 5, only returned if exist.

Request Example

POST openapi/face/getFaceByArrival HTTP/1.1
Host: 192.168.0.1
Content-Type: application/x-www-form-urlencoded

app_id=mdk923idkf&random=289192&timestamp=15930292837&sign=IDKNFLK392038KDS932K& group_name=vip&num=2

Response Example

{
    "code": 0,
    "data": {
        "return_num": 2,
        "faceid_list": [
            {
                "faceid": "8",
                "arrive_time": 1566215929,
                "arrive_count": 7,
                "age_range": 5,
                "gender": 1,
                "age": 0,
                "item1": "value1",
                "item2": "value2",
                "item3": "value3",
                "item4": "value4",
                "item5": "value5"
            },
            {
                "faceid": "10",
                "arrive_time": 1566110525,
                "arrive_count": 6,
                "age_range": 4,
                "gender": 2,
                "age": 0,
                "item1": "value1",
                "item2": "value2",
                "item3": "value3",
                "item4": "value4",
                "item5": "value5"
            }
        ]
    }
}

15. Get Face Record By Picture

Description

Get information of face record by picture.

Request Type

Content-Type is multipart/form-data, and all arguments except file are signed according to the signature rules.

Request Link

https://192.168.0.1/openapi/face/getFaceByPicture, 192.168.0.1 needs to be replaced with the actual IP address of IPC.

Request Parameters

Below are private parameters for this API, please refer to Public Parameters for more details.

ParameterType DescriptionRequiredExample
pic file Face photo file in jpg/png format, maximum resulution is 1920*1080,
the size of file must not exceed 1M bytes.
Y 11024.jpg

Response Parameters

ParameterTypeDescriptionExample
code int Return code, represent the request result,
possible return codes are 0, 1, 2, 3, 5, 7, 210, 211, 283, see Error Code for further details.
faceid string Face ID
group_name string Group name
age int age, NULL means user has not set the age of the face record.
age_range int age range, 1 means 1~6 years old, 2 means 7~12 years old, 3 means 13~18
years old, 5 means 19~28 years old, 5 means 29~35 years old, 6 means
36~45 years old, 7 means 45~55 years old, 8 means 55~100 years old
gender int gender, 0 means unknown, 1 means male, 2 means female
arrive_count int Total number of arrivals
arrive_time int Timestamp of the last arrival
item1 string User-defined attribute 1, only returned if exist.
item2 string User-defined attribute 2, only returned if exist.
item3 string User-defined attribute 3, only returned if exist.
item4 string User-defined attribute 4, only returned if exist.
item5 string User-defined attribute 5, only returned if exist.

Request Example

POST /openapi/face/getFaceByPicture HTTP/1.1
Host: 192.168.0.1
Content-Type: multipart/form-data; boundary=————————–962974737227706390007700
Content-Length: 1683

—————————-962974737227706390007700
Content-Disposition: form-data; name=”app_id”

mdk923idk
—————————-962974737227706390007700
Content-Disposition: form-data; name=”random”  

289192
—————————-962974737227706390007700
Content-Disposition: form-data; name=”timestamp”  

15930292837
—————————-962974737227706390007700
Content-Disposition: form-data; name=”sign”  

IDKNFLK392038KDS932K
—————————-962974737227706390007700
Content-Disposition: form-data; name=”pic”; filename=”11024.jpg”
Content-Type: image/jpeg  

(binary data of picture)
—————————-962974737227706390007700–

Response Example

{
    "code": 0,
    "data": {
        "arrive_time": 1566215943,
        "arrive_count": 2,
        "faceid": "4",
        "group_name": "VIP",
        "point": "113",
        "gender": 1,
        "age": 10,
        "age_range": 2,
        "vip_level": "1",
        "hobby": "tennis",
        "weight": "60",
        "height": "180"
    }
}

Note

The above hobby, vip_level, weight and phone_num are user-defined attributes, should be added before using them.

Video Streaming

1.Get Live Streaming

Description

This API is used to get live streaming of the IPC.

Request link

https://192.168.0.1/openapi/media/getLiveStream, 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

ParameterTypeDescription
codeintReturn code, represent the request result,
possible return codes are 0, 1, 3, 5, 7, 232, see Error Code for further details.
hd_live_urlstringHigh-Definition live streaming of the IPC using RTSP.
fhd_live_urlstringFull High-Definition live streaming of the IPC using RTSP.

Request Example

POST /openapi/media/getLiveStreamHTTP/1.1
Host: 192.168.0.1
Content-Type: application/x-www-form-urlencoded

app_id=mdk923idkf&random=289192×tamp=1564565937&sign=IDKNFLK392038KDS932K

Response Example

{
   “code”:              0,
   “data”: {
      “hd_live_url”:  “rtsp://192.168.0.1/ed98eeead4c843f898fef1c203313364/live_hd.sdp”,
      “fhd_live_url”:  “rtsp://192.168.0.1/ed98eeead4c843f898fef1c203313364/live_fhd.sdp”
  }
}

2.Get Playback Streaming

Description

This API is used to get playback streaming of the IPC.

Request link

https://192.168.0.1/openapi/media/getPlaybackStream, 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.

ParameterTypeDescriptionRequiredExample
start_timelongStart time of the playback streaming, seconds in UNIX format.Y1578969264
end_timelongEnd time of the playback streaming, seconds in UNIX format.Y1579055640

Response Parameters

ParameterTypeDescription
codeintReturn code, represent the request result,
possible return codes are 0, 1, 3, 5, 7, 230, 235, see Error Code for further details.
playback_urlstringPlayback streaming of the IPC using RTSP.

Request Example

POST /openapi/media/getPlaybackStream HTTP/1.1
Host: 192.168.0.1
Content-Type: application/x-www-form-urlencoded

app_id=mdk923idkf&random=289192×tamp=1564565937&sign=IDKNFLK392038KDS932K&start_time=1564565637&end_time=1564565697

Response Example

{
   “code”:              0,
   “data”: {
       “playback_url”:  “rtsp://192.168.0.1/ed98eeead4c843f898fef1c203313364/pb.sdp”
    }
}

3.Get Record List

Description

This API is used to get record list of the IPC.

Request link

https://192.168.0.1/openapi/media/getRecordList, 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.

ParameterTypeDescriptionRequiredExample
start_timelongStart time of record files, seconds in UNIX format.Y1578969264
end_timelongEnd time of record files, seconds in UNIX format.Y1579055640
page_numintCurrent page, default is 1, minimum is 1.N1
page_sizeintNumber of record files in one page, default is 10, range is [0, 500].N10

Response Parameters

ParameterTypeDescription
codeintReturn code, represent the request result,
possible return codes are 0, 1, 3, 5, 7, 231, 234, 235, see Error Code for further details.
total_numintTotal number of the eligible record files, about one minute per record file.
return_numintReturned number this time.
start_timelongStart time of the record file.
end_timelongEnd time of the record file.
urlstringDownload address of the record file.

Request Example

POST /openapi/media/getRecordList HTTP/1.1
Host: 192.168.0.1
Content-Type: application/x-www-form-urlencoded

app_id=mdk923idkf&random=289192×tamp=1564565937&sign=IDKNFLK392038KDS932K&start_time=1564565216&end_time=1564565697&page_num=2&page_size=30

Response Example

{
   “code”:              0,
   “data”: {
    “total_num”: 100,
    “return_num”: 30,
    “record_list”:[{
    “start_time”: 1564565216,
    “end_time”: 1564565276,
    “url”:  “https://192.168.0.1/mnt/sd-card/sunmi_video/video_plan/20190731172656_20190731172756.flv?auth_key=1564643800-efc1f64efb0d1d8fab35f0fe8c823a34”}, …]
   }
}

4.Get Snapshot

Description

This API is used to get snapshot of the IPC.

Request link

https://192.168.0.1/openapi/media/getSnapshot, 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

ParameterTypeDescription
codeintReturn code, represent the request result,
possible return codes are 0, 1, 3, 5, 7, 233, see Error Code for further details.
snapshot_urlstringDownload address of the snapshot.

Request Example

POST /openapi/media/getSnapshot HTTP/1.1
Host: 192.168.0.1
Content-Type: application/x-www-form-urlencoded

app_id=mdk923idkf&random=289192×tamp=1564565937&sign=IDKNFLK392038KDS932K

Response Example

{
   “code”:              0,
   “data”: {
      “snapshot_url”:  “https://192.168.0.1/tmp/snapshot/FM0101122334455_20190726162335.jpg?auth_key=1564129415-215f61f3c5f552c5bf8f43ccef5c66a9”
  }
}

5.Get Video Clip

Description

Get a video clip before and after a period of time.

When this api called, the IPC will get a video clip which the period is a multiple of 4 seconds. The spanning of the video clip depends on the parameters passed in. The return parameter of the api is the download link of the video clip.

The download link of the video clip will take effect in 4 to 12 seconds. The Effective time is related to parameters passed in.

Request link

https://192.168.0.1/openapi/media/getCurVideos

Request Parameters

Blow are private parameters for this API, please refer to Public Parametersfor more details.

ParameterTypeDescriptionRequiredExample
precedingintTime period before current. 0, 4, and 8 allowed only. Y0
followingint Time period after current. 0, 4, and 8 allowed only. Y8

Response Parameters

ParameterTypeDescription
codeintReturn code, represent the request result, possible return codes are 0, 1, 2, 3, 5, 7, 236, 237, see Error Code for further details.
urlstringDownload link of the video clip, which will take effect after 4 to 12 seconds.

Request Example

POST /openapi/media/getCurVideos HTTP/1.1
Host: 10.10.61.206
Content-Type: application/json
Content-Length: 111
Connection: Keep-Alive
Accept-Encoding: gzip, deflate
Accept-Language: zh-CN,en,*
User-Agent: Mozilla/5.0
app_id=123&timestamp=1585743081&random=7783515117&following=0&preceding=0&sign=F4A04BDBE60D9C656A23CD945F703DA2

Response Example

{
“data”:
{
“url”:”https://10.10.63.19/mnt/sd-card/video_slicer/1585741874923_0_0.flv?auth_key=1585741878-c41f9a8751fe0c259b3d00b3842aa668″
},
“code”:0
}

Basic Configurations

  1. Set WIFI Configurations
  2. Set WIFI Configurations (without authentication)
  3. Get WIFI Configurations
  4. Get AP List
  5. Get AP List (without authentication)
  6. Get IP Configurations
  7. Set IP Configurations
  8. Set Zoom
  9. Manual Focus
  10. Automatic Focus
  11. Reset Zoom and Focus
  12. Get Zoom and Focus Configurations
  13. Set IR Mode
  14. Get IR Mode
  15. Set Dynamic Detect
  16. Get Dynamic Detect
  17. Set IPC Name
  18. Get IPC Name
  19. Set LED
  20. Get LED
  21. Set Rotation
  22. Get Rotation
  23. Get Rotation Angles
  24. Format SD-card
  25. Get SD-card Status
  26. Get Face Recognition Settings
  27. Set Face Recognition Settings

1. Set WIFI Configurations

Description

Set the SSID and password for Internet connection.

Request Link

https://192.168.0.1/openapi/config/setWifiConf, 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.

ParameterTypeDescriptionRequiredExample
ssid stringThe name of wireless network or “SSID” to connect, maximum 32 charactersY WeWork
password stringThe password of the AP to connect, left blank if no password is required, WEP is not supported, maximum 64 charactersY

Response Parameters

ParameterTypeDescription
code int Return code, represent the request result,
possible return codes are 0, 1, 2, 3, 5, 7, 100, 101, see Error Code for further details.

Request Example

POST /openapi/config/setWifiConf HTTP/1.1
Host: 192.168.0.1
Content-Type: application/x-www-form-urlencoded

app_id=mdk923idkf&random=289192&timestamp=15930292837&sign=IDKNFLK392038KDS932K& ssid=sunmi_ipc&password=1234567890

Response Example

{
    “code”: 0
}

2. Set WIFI Configurations (without authentication)

Description

Set the SSID and password for Internet connection before activation, invalid after activation.

Request Link

https://192.168.0.1/openapi/config/setWifiConfWithoutAuth, 192.168.0.1 should be replaced by the IP address of the IPC.

Request Parameters

This API requires no public parameter.

ParameterTypeDescriptionRequiredExample
ssid stringThe name of wireless network or “SSID” to connect, maximum 32 charactersY WeWork
password stringThe password of the AP to connect, left blank if no password is required, WEP is not supported, maximum 64 charactersY

Response Parameters

ParameterTypeDescription
code int Return code, represent the request result,
possible return codes are 0, 1, 2, 3, 5, 7, 12, 100, 101, see Error Code for further details.

Request Example

POST /openapi/config/setWifiConfWithoutAuth HTTP/1.1
Host: 192.168.0.1
Content-Type: application/x-www-form-urlencoded

ssid=sunmi_ipc&password=1234567890

Response Example

{
    “code”: 0
}

3. Get WIFI Configurations

Description

Get the WIFI configurations.

Request Link

https://192.168.0.1/openapi/config/getWifiConf, 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

ParameterTypeDescription
code int Return code, represent the request result,
possible return codes are 0, 1, 3, 5, 7, see Error Code for further details.
ssid string SSID
password string Password

Request Example

POST /openapi/config/getWifiConf 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,
    “data”: {
        “ssid”: “SUNMI_IPC”,
        “password”: “1234567890”
    }
}

4. Get AP List

Description

Get the AP list discovered by the IPC.

Request Link

https://192.168.0.1/openapi/config/getApList, 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

ParameterTypeDescription
code int Return code, represent the request result,
possible return codes are 0, 1, 3, 5, 7, see Error Code for further details.
num int Number of AP discovered
ssid string SSID
key_mgmt string Encryption method

Request Example

POST /openapi/config/getApList HTTP/1.1
Host: 192.168.0.1
Content-Type: application/x-www-form-urlencoded

app_id=mdk923idkf&random=289192&timestamp=15930292837&sign=IDKNFLK392038KDS932K

Response Example

{
    “code”:0,
    “data”: 
    {
        “num”: 3,
        “ap_list”:[
            {
                “ssid”: “TP-LINK_3475”,
                “key_mgmt”: “WPA-PSK”
            },
            {
                “ssid”: “WeWork”,
                “key_mgmt”: “WPA-PSK”
            },
            {
                “ssid”: “WeWorkCorp”,
                “key_mgmt”: “WPA-PSK”
            }
        ]
    }
}

5. Get AP List (without authentication)

Description

Get the AP list discovered by the IPC before activation, invalid after activation.

Request Link

https://192.168.0.1/openapi/config/getApListWithoutAuth, 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

ParameterTypeDescription
code int Return code, represent the request result,
possible return codes are 0, 1, 3, 5, 7, see Error Code for further details.
num int Number of AP discovered
ssid string SSID
key_mgmt string Encryption method

Request Example

POST /openapi/config/getApListWithoutAuth HTTP/1.1
Host: 192.168.0.1
Content-Type: application/x-www-form-urlencoded

app_id=mdk923idkf&random=289192&timestamp=15930292837&sign=IDKNFLK392038KDS932K

Response Example

{
    “code”:0,
    “data”: 
    {
        “num”: 3,
        “ap_list”:[
            {
                “ssid”: “TP-LINK_3475”,
                “key_mgmt”: “WPA-PSK”
            },
            {
                “ssid”: “WeWork”,
                “key_mgmt”: “WPA-PSK”
            },
            {
                “ssid”: “WeWorkCorp”,
                “key_mgmt”: “WPA-PSK”
            }
        ]
    }
}

6. Get IP Configurations

Description

Get IP Configurations of the IPC

Request Link

https://192.168.0.1/openapi/config/getIpConfiguration,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

ParameterTypeDescription
code intReturn code, represent the request result,
possible return codes are 0, 1, 3, 5, 7, see Error Code for further details.
proto string dhcp or static
ipaddr stringIP address of the IPC
netmask string Netmask
gateway string IP address of the gateway
dns1 string DNS address 1
dns2 string DNS address 2

Request Example

POST /openapi/config/getIpConfiguration HTTP/1.1
Host: 192.168.0.1
Content-Type: application/x-www-form-urlencoded

app_id=mdk923idkf&random=289192&timestamp=15930292837&sign=IDKNFLK392038KDS932K

Response Example

{
   “code”: 0,
   “data”: {
      “proto”: “dhcp”,
      “ipaddr”: “192.168.1.107”,
      “netmask”: “255.255.255.0”,
      “gateway”: “192.168.1.1” ,
      “dns1”: “202.96.128.86”,
      “dns2”: “202.96.134.166”,
     }
}

7. Set IP Configurations

Description

Set IP Configurations of the IPC.

Request Likn

https://192.168.0.1/openapi/config/setIpConfiguration,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.

ParameterTypeDescriptionRequiredExample
protostringdhcp or staticYstatic
ipaddrstringIP address of the IPCN192.168.1.110
netmaskstringNetmaskN255.255.255.0
gatewaystringIP address of the gatewayN192.168.1.100
dns1stringDNS address 1N202.96.128.86
dns2string DNS address 2 N202.96.134.166

Response Parameters

ParameterTypeDescription
codeint 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/config/setIpConfiguration HTTP/1.1
Host: 192.168.0.1
Content-Type: application/x-www-form-urlencoded

app_id=mdk923idkf&random=289192&proto=dhcp&timestamp=15930292837&sign=IDKNFLK392038KDS932K

Response Example

{
    “code”: 0
}

8. Set Zoom

Description

Set the zoom level of the lens.

Request Link

https://192.168.0.1/openapi/config/setZoom, 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.

ParameterTypeDescriptionRequiredExample
zoom int Zoom level, range is [0, 500]. Y 200

Response Parameters

ParameterTypeDescription
code int Return code, represent the request result,
possible return codes are 0, 1, 3, 5, 7, 110, see Error Code for further details.

Request Example

POST /openapi/config/setZoom HTTP/1.1
Host: 192.168.0.1
Content-Type: application/x-www-form-urlencoded

app_id=mdk923idkf&random=289192&timestamp=15930292837&sign=IDKNFLK392038KDS932K& zoom=100

Response Example

{
    “code”: 0
}

9. Manual Focus

Description

Set the focus level of the lens. This is used to manually adjust the focus level if automatic focus after zooming is not satisfying.

Request Link

https://192.168.0.1/openapi/config/manualFocus, 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.

ParameterTypeDescriptionRequiredExample
focus int Focus level, range is [0, 780]. Y 200

Response Parameters

ParameterTypeDescription
code int Return code, represent the request result,
possible return codes are 0, 1, 3, 5, 7, 111, see Error Code for further details.

Request Example

POST /openapi/config/manualFocus HTTP/1.1
Host: 192.168.0.1
Content-Type: application/x-www-form-urlencoded

app_id=mdk923idkf&random=289192&timestamp=15930292837&sign=IDKNFLK392038KDS932K& focus=100

Response Example

{
    “code”: 0
}

10. Automatic Focus

Description

Set to automatically focus to a given focus point.

Request Link

https://192.168.0.1/openapi/config/autoFocus, 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.

ParameterTypeDescriptionRequiredExample
focus_x int X-axis percentage of the focus point, range is [0, 100]. Y 50
focus_y int Y-axis percentage of the focus point, range is [0, 100]. Y 50

Response Parameters

ParameterTypeDescription
code int Return code, represent the request result,
possible return codes are 0, 1, 3, 5, 7, 112, see Error Code for further details.

Request Example

POST /openapi/config/autoFocus HTTP/1.1
Host: 192.168.0.1
Content-Type: application/x-www-form-urlencoded

app_id=mdk923idkf&random=289192&timestamp=15930292837&sign=IDKNFLK392038KDS932K& focus_x=50&focus_y=50

Response Example

{
    “code”: 0
}

11. Reset Zoom and Focus

Description

Reset zoom and focus levels to defaults.

Request Link

https://192.168.0.1/openapi/config/resetZoomFocus, 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

ParameterTypeDescription
code int Return code, represent the request result,
possible return codes are 0, 1, 3, 5, 7, see Error Code for further details.

Request Example

POST /openapi/config/resetZoomFocus HTTP/1.1
Host: 192.168.0.1
Content-Type: application/x-www-form-urlencoded

app_id=mdk923idkf&random=289192&timestamp=15930292837&sign=IDKNFLK392038KDS932K

Response Example

{
    “code”: 0
}

12. Get Zoom and Focus Configurations

Description

Get zoom and focus configurations.

Request Link

https://192.168.0.1/openapi/config/getZoomFocusConf, 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

ParameterTypeDescription
code int Return code, represent the request result,
possible return codes are 0, 1, 3, 5, 7, see Error Code for further details.
max_zoom int Maximum zoom level
max_focus int Maximum focus level
zoom int Current zoom level
focus int Current focus level
focus_x int X-axis percentage of the focus point
focus_y int Y-axis percentage of the focus point

Request Example

POST /openapi/config/getZoomFocusConf HTTP/1.1
Host: 192.168.0.1
Content-Type: application/x-www-form-urlencoded

app_id=mdk923idkf&random=289192&timestamp=15930292837&sign=IDKNFLK392038KDS932K

Response Example

{
    “code”: 0,
    “data”: {
        “zoom”: 0,
        “max_zoom”: 500,
        “max_focus”: 780,
        “focus”: 0,
        “focused_x”: 50,
        “focused_y”: 50
    }
}

13. Set IR Mode

Description

Set IR mode of the lens.

Request Link

https://192.168.0.1/openapi/config/setIrMode, 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.

ParameterTypeDescriptionRequiredExample
irmode int 0: off; 1: on; 2: auto. 2 is recommended. Y 2

Response Parameters

ParameterTypeDescription
code int Return code, represent the request result,
possible return codes are 0, 1, 3, 5, 7, 113, see Error Code for further details.

Request Example

POST /openapi/config/setIrMode HTTP/1.1
Host: 192.168.0.1
Content-Type: application/x-www-form-urlencoded

app_id=mdk923idkf&random=289192&timestamp=15930292837&sign=IDKNFLK392038KDS932K& irmode=1

Response Example

{
    “code”: 0
}

14. Get IR Mode

Description

Get IR mode of the lens.

Request Link

https://192.168.0.1/openapi/config/getIrMode, 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

ParameterTypeDescription
code int Return code, represent the request result,
possible return codes are 0, 1, 3, 5, 7, see Error Code for further details.
irmode int Current IR mode of the lens

Request Example

POST /openapi/config/getIrMode HTTP/1.1
Host: 192.168.0.1
Content-Type: application/x-www-form-urlencoded

app_id=mdk923idkf&random=289192&timestamp=15930292837&sign=IDKNFLK392038KDS932K

Response Example

{
    “code”: 0,
    “data”: {
          “irmode”: 1
    }
}

15. Set Dynamic Detect

Description

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 TypeDescriptionRequiredExample
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

ParameterTypeDescription
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

app_id=mdk923idkf&random=289192&timestamp=15930292837&sign=IDKNFLK392038KDS932K motion_level=1&audio_level=1&weekday=128&start_time=1260&stop_time=540

Response Example

{
    “code”: 0
}

16. Get Dynamic Detect

Description

Get configurations of the dynamic detection.

Request Link

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

ParameterTypeDescription
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


app_id=mdk923idkf&random=289192×tamp=15930292837&sign=IDKNFLK392038KDS932K

Response Example

{
    “code”: 0,
    “data”: {
          “motion_level”: 1,
         “audio_level”: 1,
         “weekday”: 7,
         “start_time”: 120
         “stop_time”: 240,
    }
}

17. Set IPC Name

Description

Set the name of the IPC.

Request Link

https://192.168.0.1/openapi/config/updateName, 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.

ParameterTypeDescriptionRequiredExample
name string Name, maximum 36 characters Y Camera1

Response Parameters

ParameterTypeDescription
code int Return code, represent the request result,
possible return codes are 0, 1, 3, 5, 7, 118, see Error Code for further details.

Request Example

POST /openapi/config/updateName HTTP/1.1
Host: 192.168.0.1
Content-Type: application/x-www-form-urlencoded

app_id=mdk923idkf&random=289192&timestamp=15930292837&sign=IDKNFLK392038KDS932K&
name=front_door

Response Example

{
    “code”: 0
}

18. Get IPC Name

Description

Get the name of the IPC.

Request Link

https://192.168.0.1/openapi/config/getName, 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

ParameterTypeDescription
code int Return code, represent the request result,
possible return codes are 0, 1, 3, 5, 7, see Error Code for further details.
name int Name

Request Example

POST /openapi/config/getName HTTP/1.1
Host: 192.168.0.1
Content-Type: application/x-www-form-urlencoded

app_id=mdk923idkf&random=289192&timestamp=15930292837&sign=IDKNFLK392038KDS932K

Response Example

{
    “code”: 0,
    “data”: {
         “name”: “front_door”
    }
}

19. Set LED

Description

Set the LED on the IPC.

Request Link

https://192.168.0.1/openapi/config/setLedSwitch, 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.

ParameterTypeDescriptionRequiredExample
led_switch int 0: disable, 1: enable Y 1

Response Parameters

ParameterTypeDescription
code int Return code, represent the request result,
possible return codes are 0, 1, 3, 5, 7, 119, see Error Code for further details.

Request Example

POST /openapi/config/setLedSwitch HTTP/1.1
Host: 192.168.0.1
Content-Type: application/x-www-form-urlencoded

app_id=mdk923idkf&random=289192&timestamp=15930292837&sign=IDKNFLK392038KDS932K& led_switch=1

Response Example

{
    “code”: 0
}

20. Get LED

Description

Get the setting of the LED on the IPC.

Request Link

https://192.168.0.1/openapi/config/getLedSwitch, 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

ParameterTypeDescription
code int Return code, represent the request result,
possible return codes are 0, 1, 3, 5, 7, see Error Code for further details.
led_switch int 0: disable, 1: enable

Request Example

POST /openapi/config/getLedSwitch HTTP/1.1
Host: 192.168.0.1
Content-Type: application/x-www-form-urlencoded

app_id=mdk923idkf&random=289192&timestamp=15930292837&sign=IDKNFLK392038KDS932K

Response Example

{
    “code”: 0,
    “data”: {
         “led_switch”: 1
    }
}

21. Set Rotation

Description

Set the orientation of image, use Get Rotation Angles to get available angles.

Request Link

https://192.168.0.1/openapi/config/setRotation, 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.

ParameterTypeDescriptionRequiredExample
rotation int The orientation of image Y 180

Response Parameters

ParameterTypeDescription
code int Return code, represent the request result,
possible return codes are 0, 1, 3, 5, 7, 120, see Error Code for further details.

Request Example

POST /openapi/config/setRotation HTTP/1.1
Host: 192.168.0.1
Content-Type: application/x-www-form-urlencoded

app_id=mdk923idkf&random=289192&timestamp=15930292837&sign=IDKNFLK392038KDS932K& rotation=180

Response Example

{
    “code”: 0
}

22. Get Rotation

Description

Get the orientation of image,.

Request Link

https://192.168.0.1/openapi/config/getRotation, 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

ParameterTypeDescription
code int Return code, represent the request result,
possible return codes are 0, 1, 3, 5, 7, see Error Code for further details.
rotation int The orientation of image

Request Example

POST /openapi/config/getRotation HTTP/1.1
Host: 192.168.0.1
Content-Type: application/x-www-form-urlencoded

app_id=mdk923idkf&random=289192&timestamp=15930292837&sign=IDKNFLK392038KDS932K

Response Example

{
    “code”: 0,
    “data”: {
        “rotation”: 180
    }

23. Get Rotation Angles

Description

Get supported rotation angles of image.

Request Link

https://192.168.0.1/openapi/config/getRotationAngles, 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

ParameterTypeDescription
code int Return code, represent the request result,
possible return codes are 0, 1, 3, 5, 7, see Error Code for further details.
angles string list List of supported rotation angles of image

Request Example

POST /openapi/config/getRotation HTTP/1.1
Host: 192.168.0.1
Content-Type: application/x-www-form-urlencoded

app_id=mdk923idkf&random=289192&timestamp=15930292837&sign=IDKNFLK392038KDS932K

Response Example

{
    “code”: 0,
    “data”: {
        “angles”: [
            “0”,
            “90”,
            “180”,
            “270”
        ]
    }
}

24. Format SD-card

Description

Format the SD-card in the IPC.

Request Link

https://192.168.0.1/openapi/config/formatMemoryCard, 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

ParameterTypeDescription
code int Return code, represent the request result,
possible return codes are 0, 1, 3, 5, 7, 220, 221, see Error Code for further details.

Request Example

POST /openapi/config/formatMemoryCard HTTP/1.1
Host: 192.168.0.1
Content-Type: application/x-www-form-urlencoded

app_id=mdk923idkf&random=289192&timestamp=15930292837&sign=IDKNFLK392038KDS932K

Response Example

{
    “code”: 0
}

25. Get SD-card Status

Description

Get the status of the SD-card in the IPC.

Request Link

https://192.168.0.1/openapi/config/getMemoryCardStatus, 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

ParameterTypeDescription
code int Return code, represent the request result,
possible return codes are 0, 1, 3, 5, 7, see Error Code for further details.
status int 0: unplugged, 1: unformatted, 2: working;3: unknown

Request Example

POST /openapi/config/getMemoryCardStatus HTTP/1.1
Host: 192.168.0.1
Content-Type: application/x-www-form-urlencoded

app_id=mdk923idkf&random=289192&timestamp=15930292837&sign=IDKNFLK392038KDS932K

Response Example

{
    “code”: 0,
    “data”: {
         “status”: 2
    }
}

26. Get Face Recognition Settings

Description

Get face recognition settings, only FM020 is supported.

Request Link

https://192.168.0.1/openapi/config/getAiFaceConfig, 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.
optimize_seconds int The time of face optimality analysis in seconds.

Request Example

POST /openapi/config/getAiFaceConfig 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,
    "data": {
      "optimize_seconds": 2
    }
} 

27. Set Face Recognition Settings

Description

Set face recognition settings, only FM020 is supported.

Request Link

https://192.168.0.1/openapi/config/setAiFaceConfig, 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.

ParameterTypeDescriptionRequiredExample
optimize_secondsintThe time of face optimality analysis in seconds, the range is [1, 6]. Y6

Response Parameters

ParameterTypeDescription
code int Return code, represent the request result,
possible return codes are 0, 1, 3, 5, 7, see Error Code for further details.
optimize_seconds int The time of face optimality analysis in seconds.

Request Example

POST /openapi/config/setAiFaceConfig HTTP/1.1
Host: 192.168.0.1
Content-Type: application/x-www-form-urlencoded

app_id=mdk923idkf&random=289192×tamp=15930292837&optimize_seconds=6&sign=IDKNFLK392038KDS932K

Response Example

{
  "code": 0,
    "data": {
      "optimize_seconds": 2
    }
} 

Device Management

1.Activation

Description

This API is used to activate the IPC, connected to the Internet is required.

All of the existing groups and records will be deleted after the activation and two default groups will be created: stranger and regulart.

Request link

https://192.168.0.1/openapi/device/activate, 192.168.0.1 should be replaced by the IP address of the IPC.

Request Parameters

ParameterTypeDescriptionRequired
app_idstringUser application ID, used as public parameterY
timestamplongUnix timestamp in secondY
randomlongA 6-10 digits random numberY
snstringDevice SNY
signstringSignature of the requestY

Please refer to 1.5.4 Signature Rules and replace the Secret Key with the OpenAPI Activation Number to generate the signature.

For example, if you have the following parameters:

app_id: JO83UNV983U9OR
random: 289192
sn: FS101D8BS00106
timestamp: 1593029283

The OpenAPI Activation Number is 12345678

Then the signature is:

str1=”app_id=JO83UNV983U9OR&random=289192&sn=FS101D8BS00106&timestamp=1593029283″
str2 = str1 + “&key=12345678”
sign = MD5(str2).upper()

The parameters in the final HTTP request are:

app_id:JO83UNV983U9OR
random:289192
sn:FS101D8BS00106
timestamp:1593029283
sign:72CB1C1031D3BA103D2FA1A57E171C2D

Response Parameters

ParameterTypeDescription
codeintReturn code, represent the request result,
possible return codes are 0, 1, 2, 3, 4, 8, 9, 10, 11, see Error Code for further details.

Request Example

POST /openapi/device/activate HTTP/1.1
Host: 192.168.0.1
Content-Type: application/x-www-form-urlencoded
app_id=JO83UNV983U9OR&random=289192&sn=FS101D8BS00106&timestamp=1593029283&sign=72CB1C1031D3BA103D2FA1A57E171C2D

Response Example

{
    “code”:          0,
}

2.Get Basic Informations

Description

This API is used to get basic informations of the IPC.

Request link

https://192.168.0.1/openapi/device/getInfo, 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

ParameterTypeDescription
codeintReturn code, represent the request result,
possible return codes are 0, 1, 2, 3, 5, 7, see Error Code for further details.
snstringDevice SN
model_namestringModel name
namestringDevice name
software_versionstringSoftware version
hardware_versionstringHardware version
ipstringIP address
macstringMAC address

Request Example

POST /openapi/device/getInfo HTTP/1.1
Host: 192.168.0.1
Content-Type: application/x-www-form-urlencoded
app_id=mdk923idkf&random=289192&timestamp=15930292837&sign=IDKNFLK392038KDS932K&

Response Example

{
    “code”: 0,
    “data”: {
        “sn”: “SS101D8BS00083”,
        “model_name”: “FS”,
        “name”: “My FS”,
        “software_version”: “1.1.0”,
        “hardware_version”: “1.0.0”,
        “ip”: “192.168.0.1”,
        “mac”: “04:12:24:E3:45:12 “
    }
}

3.Restore Factory Settings

Description

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

ParameterTypeDescription
codeintReturn 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&timestamp=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

ParameterTypeDescription
codeintReturn 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&timestamp=15930292837&sign=IDKNFLK392038KDS932K

Response Example

{
    “code”:          0,
}

Initial Configurations

  1. Wired Network
  2. Wireless Network
  3. Get the Device’s IP address
  4. SUNMI Device Discovery Protocol

In order to use the IPC through OpenAPI, the user need to get the IP address of the IPC first.

The first step is to connect the IPC to the network. There are two ways to connect the device to Internet, wired and wireless. Wired network is preferred for its high stability and reliability.

1. Wired Network

For an IPC device with an Ethernet Port, you can connect it to a gateway, such as a wireless router, with an Ethernet cable, then the device will obtain an IP address from the DHCP server.

If the network is available, the LED on the IPC will soon turn blue, indicating the IPC has connected to the Internet.

2. Wireless Network

The steps to connect to a wireless network are as follows:

  1. Use your mobile phone or PC to scan the wireless hotspot of the IPC. The SSID of the wireless hotspot is SUNMI_XXXX, where XXXX is the hexadecimal number of the last 2 bytes of the MAC address. The MAC address can be found on the label on the back of the device or on the packaging box.
  2. Use your mobile phone or PC to connect to the wireless hotspot. The mobile phone or PC will obtain an IP address assigned by the IPC, which is usually 192.168.200.XXX. The gateway address of mobile phone or PC is the address of IPC, which is usually 192.168.200.1.
  3. Use the wireless configuration API to connect to wireless network. If everything is done correctly, the IPC will obtain the IP address from the gateway.
  4. If the network is available, the LED on the IPC will soon turn blue, indicating that the IPC has connected to the Internet.

3. Get the Device’s IP address

After the setup of IPC’s network, the next step is to get the IP address of the IPC.

SUNMI provides Device Discovery Protocol for discovering all SUNMI devices that support this protocol on the same LAN. It’s used to scan and collect the basic information of the SUNMI devices, including serial number and IP addresss.

4. SUNMI Device Discovery Protocol

The SUNMI Device Discovery Protocol is for one device to broadcast UDP messages to find SUNMI devices in the same LAN, and other devices supporting this protocol will respond to those messages, which include basic informations of themselves.

4.1 Message Format

The Payload of UDP message is shown in the figure below. The whole message consists of header, Payload and CRC checksum.

4.1.1 Header

The Message Header, including flag, protocol version, message type and length.

Flag: currently fixed to 0xFFFF33FF.

Version: protocol version, currently only version 0x1 is supported.

Type: message type, 0x1 for the discovery request message and 0x2 for the discovery response message.

Len: length of the payload after base64 encoding.

4.1.2 Payload

This field contains the final payload. The raw data is in json format, and it needs to be base64 encoded before put on the payload.

4.1.3 CRC

This field contains the CRC32 (32-bit Cyclic Redundancy Check) value calculated from the header and payload fields. The receiver use this value to verify the message.

4.2 Protocol Port

Both sender and receiver use port 10001.

4.3 Discovery Request

When the sender wants to find devices support the SUNMI Device Discovery Protocol in the LAN, it need to send UDP broadcast message. The details are as follows:

In this message, field Type is 0x01, Len is 0x0, it means that the payload is empty.

4.4 Discovery Response

This message is sent by the receiver. It is used to tell the sender the informations of itself. The type is 0x02, and the length is calculated according to the data.

The payload content is shown in the figure below, which is the device information in json format.

ip: the IP address of the device.

mac: the MAC address of the device.

firmware: the firmware version of the device, such as 1.0.0

name: device name, currently fixed as SUNMI.

model: device model, such as FM020.

type: device type, currently fixed as IPC.

network: the mode of network connection about the sender. If the sender is connected to the wireless hotspot of IPC, the value is “AP”. If the sender is connected to same LAN of router with IPC, the value is “LAN”.

deviceid: device serial number.

4.5 Timeout handling

It is suggested to send Discovery Request messages with an interval of 1s, and 3 times at most. This is to prevent loss of messages from some devices.

After sending 3 Request Messages, the sender should set a timeout period of 2s, after which the Discovery Response message will not be received. That means the Discovery Response message can only be received in 5s after the first Discovery Request message.

After receiving a Discovery Request message, the receiver should reply with a Discovery Response message in unicast mode immediately.