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.

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.

API Call Method

There are two ways to call OpenAPI: synchronous HTTPS Interfaces and asynchronous Message Channel.

HTTPS Interfaces

APIs that return synchronously after called.

Please refer to HTTPS Request.

Message Channel

Messages pushed by the IPC need to be received through Message Channel, so as to ensure real-time.

Please refer to Message Channel.

HTTP Request

  1. Public Parameters
  2. Request Structure
  3. Sign Rules
  4. Example

1.Public Parameters

Public Parameters are required when an API is called. As shown in the table below.

Parameter Type Description Required
app_id string User application ID, used as public parameter Y
timestamp long Unix timestamp in second Y
random long A 6-10 digits random number Y
sign string Signature of the request Y

2.Request Structure

Address

The URL is used to identify which interface is called.

OpenAPI URLs looks like https://ip/openapi/apiType/action

The fields of URL are described as follows:

ip The IPC’s IP address
openapi A uniform identifier that represents it is an OpenAPI URL
apiType API functional types
action the name of the corresponding interface

Protocol

  For security, all APIs use HTTPS Protocol.

Request method

Only HTTP POST method is supported to call the interfaces. The Message content-type is application/x-www-form-urlencoded. Special cases will be described in the corresponding API.

Request parameters

Each interface should be called with parameters. There are public parameters (please refer to Public Parameters ) and private parameters according to the interface.

3. Sign Rules

Each HTTPS request message needs to be signed, and the IPC will verify the signature.

SUNMI store open platform will assign the following parameters to all OpenAPI users:

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

Sign rules

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

Validation

After receiving the request message, the IPC will use the same rules to check if the sign is valid.

Sign example

Suppose the parameter of the request is the following:

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

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

str1=”app_id=2039dds&content=newproductmask&environment=test&product_id=389238&random=289192&timestamp=1593029283&user_id=29389″
str2=str1 + “&key=kdsofkdsnflke9382938k”
sign=MD 5(str2).upper()

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

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

4. Example

Request Example

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

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

Response Example

The response to the HTTP request is in json format. Here is a simple example.

As follows, the “code” field always exists, which presents the result of calling. The “data” field is optional depend on different APIs.

{
    "code": 0,
    "data": {
        "ssid": "SUNMI_IPC",
        "password": "1234567890"
    }
}