Access Standard Product MQTT Protocol-V2 (DejaOS Version)

# MQTT Protocol Documentation

## 1. Overview

This document defines a standard interface for DW205 devices to push and retrieve device information. After purchasing a device, you can develop a complete access control or related application system according to this specification. The interface uses the MQTT protocol and can connect to any standard MQTT broker, or the broker we recommend.

**Document Version: V2**

#### Application Scenario

When integrating with your own business system, you can communicate with the device directly via MQTT using these APIs.

#### Interface Specification

The interface uses MQTT and is divided into uplink and downlink:

Uplink: device sends messages to the backend or application.

Downlink: backend or application sends messages to the device.

Communication goes through an MQTT broker. Each message has a topic and payload in the following format:

1. Message topic

> Message title. For both uplink and downlink, the command and its reply follow the pattern "command" and "command_reply". Format:

- Downlink: `access_device/v2/cmd/{#device_sn}/xxxx`, corresponding reply (uplink): `access_device/v2/cmd/xxxx_reply`
- Uplink: `access_device/v2/event/yyyy`, corresponding reply (downlink): `access_device/v2/event/{#device_sn}/yyyy_reply`

Note: `access_device/v2` is the API version prefix. `cmd` means the backend or application actively sends a command to the device; `event` means the device actively sends a message or triggers an event to the backend or application.

2. Message payload

Text payload in JSON format.

a) Request message

```json
{   
    "serialNo": "6w8keif5g6",
    "uuid": "0a1b2c3d",
    "time":1647580466, 
    "sign":"e0k4jrir85tje8ru4jrur499r99ii4ur",
       "data": {
        ...
    }
}
```

b) Response message

```json
{   
    "serialNo": "6w8keif5g6",
    "uuid": "0a1b2c3d",
    "code": "000000",
    "time":1647580466, 
    "sign":"e0k4jrir85tje8ru4jrur499r99ii4ur",
       "data": {
        ...
    },
    "message": ""
}

```

| Parameter | Description | Type | Required | Notes |
| -------- | ----------- | ---- | -------- | ----- |
| serialNo | Serial number | string | Yes | A unique serial number (max 32 chars) must be sent from backend/app to device; the device uses the same serial number in the reply, and vice versa. |
| uuid | Device unique ID | string | Yes | String longer than 8 characters. |
| data | Message body | object | Yes | JSON object; format varies by message type. API sections below describe this field in detail. |
| time | Timestamp | long | Yes | 10-digit Unix timestamp in seconds. |
| sign | Message signature | string | No | Required when signing is enabled, to verify payload integrity. See Appendix: Signature Algorithm. |
| code | Result code | string | No | Responses must include `code`. See [Appendix 1](#appendix-1-code-reference). |

**Note:** All field names in the message payload start with a lowercase letter; camelCase may follow.

## 2. Device Management and Event APIs

#### 2.1 Query Configuration

- Backend or application to device

| Message topic | topic: `access_device/v2/cmd/{#uuid}/getConfig` |
| --------- | --------------------------------------------- |

Request `data` parameters

| Parameter | Type | Required | Notes |
| :----- | ----- | -------- | ----- |
| data | array | Y | Configuration keys to query |

Request examples:

```json
// Get all configuration
{
    "serialNo": "6w8keif5g6",
    "uuid": "e4720000964b5c00",
    "time": 1647580466,
    "data": "",
    "sign": ""
}

// Get a single configuration group
{
	"serialNo": "6w8keif5g6",
	"uuid": "e4720000964b5c00",
	"time": 1647580466,
	"data":"sys",
	"sign": ""
}
```

- Device reply to backend or application

| Message topic | topic: `access_device/v2/cmd/getConfig_reply` |
| --------- | ------------------------------------------- |

`data` parameters

| Parameter | Description | Type | Required | Notes |
| ------ | -------- | ------ | ---- | -------- |
| data | Configuration data | Object | Y | See examples |

Response example:

```json
{
	"serialNo": "6w8keif5g6",
	"uuid": "e4720000964b5c00",
	"code": "000000",
    "time": 1701061767,
    "sign": "",
	"message": "success",
	"data": {
		"nfc": {
			"xx": 1,
			"xxx": 0
		}
	}
}
```

#### 2.2 Update Configuration

- **Backend or application to device**

| Message topic | topic: `access_device/v2/cmd/{#uuid}/setConfig` |
| --------- | --------------------------------------------- |

`data` parameters

| Parameter | Description | Type | Required | Notes                                                     |
| ------ | -------- | ------ | ---- | ------------------------------------------------------------ |
| data | Configuration data | Object | N | Configuration object; if empty or omitted, the device makes no configuration changes. |

<a id="config">Optional device configuration fields in `data`</a>

+ Note: Configuration uses two-level grouping; field names use camelCase starting with a lowercase letter.
+ For details see [VF105 Access Control Standard Configuration Items](http://wiki.koodle.cn:10086/doc/694/)

Request examples:

```json
{
    "serialNo": "6w8keif5g6",
    "uuid": "e4720000964b5c00",
    "sign": "",
    "code": "000000",
    "data": {
        "net": {
            "gateway": "192.168.60.1",
            "mac": "ee:ed:00:00:5b:c1",
            "password": "",
            "ip": "192.168.63.171",
            "type": 1,
            "mask": "255.255.252.0",
            "dns": "218.4.4.4,218.2.2.2",
            "dhcp": 2,
            "ssid": ""
        },
        "base": {
            "showSn": 1,
            "screenOff": 0,
            "brightness": 100,
            "language": "CN",
            "showIp": 1,
            "screensaver": 0,
            "password": "123",
            "volume": 50,
            "brightnessAuto": 1
        },
        "sys": {
            "uuid": "e4720000964b5c00",
            "model": "vf205",
            "sn": "e45a00005bc17400",
            "status": 1,
            "appVersion": "",
            "version": "vf105_v11_access_2.0.0",
            "releaseTime": "2024-09-13 09:52:00"
        },
        "face": {
            "showNir": 1,
            "livenessVal": 0.6,
            "similarity": 0.6,
            "voiceMode": 1,
            "stranger": 1,
            "livenessOff": 1,
            "detectMask": 0
        },
        "ntp": {
            "interval": 1440,
            "server": "182.92.12.11",
            "gmt": 8,
            "ntp": 1
        },
        "mqtt": {
            "qos": 1,
            "onlinecheck": 0,
            "clientId": "e45a00005bc17400",
            "prefix": "",
            "username": "",
            "willTopic": "access_device/v2/event/offline",
            "addr": "192.168.62.110:1883",
            "password": ""
        },
        "passwordAccess": {
            "passwordAccess": 1
        },
        "access": {
            "offlineAccessNum": 2000,
            "relayTime": 2000,
            "tamperAlarm": 1
        }
    },
    "time": 1736755758
}
```

- **Device reply to backend or application**

| Message topic | topic: `access_device/v2/cmd/setConfig_reply` |
| --------- | ------------------------------------------- |

Response parameters

| Parameter | Description | Type | Required | Notes           |
| ------ | -------- | ------ | ---- | ------------------ |
| data | Configuration data | Object | Y | Result set of applied configuration |

Response example

```json
{

"serialNo": "6w8keif5g6",
	"uuid": "e4720000964b5c00",
	"time": 0,
	"code": "000000",
	"message": "success",
    "sign": "",
	"data": {
		"channel": {
			"enable": 1,
			"tcpAddr": "10.200.52.151",
			"tcpPort": 8060,
			"rs485Bps": "115200-8-N-1",
			"wg": 34
		},
		"qr": {
			"enable": 1,
			"preSufFt": 1,
			"prefix": "",
			"suffix": "",
			"qrCr": 0,
			"qrNl": 0,
			"qrFt": 0
		},
		"nfc": {
			"enable": 1,
			"nfcFt": 0,
			"nfcOrd": 0,
			"preSufFt": 1,
			"prefix": "",
			"suffix": "",
			"nfcCr": 0,
			"nfcNl": 0,
			"IdCard": 0
		},
		"customer": {
			"cusTag0": "1",
			"cusTag1": "0",
			"cusTag2": "cus_tag2",
			"cusTag3": "cus_tag3",
			"cusTag4": "cus_tag4"
		}
	}
}
```

#### 2.3 Firmware Upgrade

- Backend or application to device

| Message topic | topic: `access_device/v2/cmd/{#uuid}/upgradeFirmware` |
| --------- | --------------------------------------------------- |

`data` parameters

| Parameter | Description | Type | Required | Notes |
| ------ | ------------------- | ------ | ---- | ------------------------------------------------------------ |
| type | Package type | Int | Yes | Strict validation: `0` = local firmware upgrade; `10` = resource upgrade (not supported in current version) |
| url | OTA download URL | String | Y | Device attempts to download from this URL when the API is called. If the URL is unreachable, the API returns "URL access failed, device cannot download". If reachable, download starts; file integrity is not guaranteed—check the device UI for install result. |
| md5 | Package MD5 | string | Y | MD5 verification of the upgrade package |
| extra | Extension fields | Object | Y | |

When `type=10`, `extra` is required. Supported JSON fields:

Request example:

```json
{
	"serialNo": "6w8keif5g6",
	"uuid": "e4720000964b5c00",
    "time": 0,
    "sign": "",
	"data": {
        "type": 0,
		"url": "http://10.102.106.165/aio.tar.xz",
		"md5": "521c2bdc835d4f13b5f9d6db164f0881"
	}
}
```

- Device reply to backend or application

| Message topic | topic: `access_device/v2/cmd/upgradeFirmware_reply` |
| --------- | ------------------------------------------------- |

Response example

```json
{
	"serialNo": "6w8keif5g6",
	"uuid": "e4720000964b5c00",
	"time": 0,
    "sign": "",
	"code": "000000",
	"message": "success"
}
```

#### 2.4 Remote Control

- Backend or application to device

| Message topic | topic: `access_device/v2/cmd/{#uuid}/control` |
| --------- | ------------------------------------------- |

`data` parameters

| Parameter | Description | Type | Required | Notes                                                     |
| ------- | -------- | ------ | ---- | ------------------------------------------------------------ |
| command | Command | Int | Y | `0`: reboot; `1`: remote door open; `4`: factory reset; `12`: fingerprint enrollment |
| extra | Extension fields | String | Y | See extra table below |

extra extension table

| Parameter | Description | Type | Required | Notes |
| ------------ | ---------------- | ------ | ----- | ------------------------------------------------------------ |
| fingerprintAction | Fingerprint enrollment action | int | No | When `command=12`: `0` start enrollment, `1` cancel enrollment |

Request example:

```json
{
    
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
    "time": 0,
    "sign": "",
	"data": {
		"command": 1
	}
}

// Start fingerprint enrollment
{
    "serialNo": "0000000001",
    "uuid": "e4720000964b5c00",
    "time": 0,
    "sign": "",
    "data": {
        "command":12,
        "extra": {
            "fingerprintAction": 0
        }
    }
}

}
```

- Device reply to backend or application

| Message topic | topic: `access_device/v2/cmd/control_reply` |
| --------- | ----------------------------------------- |
| `data` parameters  |                                           |

| Parameter | Description | Type | Required | Notes                         |
| ---------- | ----------------------------- | ------ | ---- | -------------------------------- |
| faceBase64 | Base64 of face JPG when remote capture | String | No | Returned when `command=8` |
| keyId | Credential ID for remote capture | String | No | Returned when `command=8`; matches input |

Response example

```json
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"time": 0,
    "sign": "",
	"code": "000000",
	"message": "success"
}

// Fingerprint enrollment
{
    "serialNo": "0000000001",
    "uuid": "e4720000964b5c00",
    "time": 0,
    "sign": "",
    "code": "000000",
    "data": {
        "fingerFeature": "fingerprint feature value",
      
    },
    "message": "success"
}
```

#### 2.5 Alarm

- Device to backend or application

| Message topic | topic: `access_device/v2/event/alarm` |
| --------- | ----------------------------------- |

`data` parameters

| Parameter | Description | Type | Required | Notes                                                   |
| ------ | -------- | ------ | ---- | ---------------------------------------------------------- |
| type | Report type | Int | Y | See [Appendix 2 Device Alarm Types](#appendix-2-device-alarm-types) |
| value | Report status | String | N | |

Request example:

```json
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
    "time": 0,
    "sign": "",
	"data": {
		"type": 1,
		"status": 1,
        "timeStamp":1785963258
	}
}
```

- Backend or application reply to device

| Message topic | topic: access_device/v2/event/{#uuid}/alarm_reply |
| --------- | ------------------------------------------------- |

Response example

```json
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"time": 0,
    "sign": "",
	"code": "000000",
	"message": "success"
}
```

#### 2.6 Heartbeat

- Device to backend or application

| Message topic | topic: access_device/v2/event/heartbeat |
| --------- | --------------------------------------- |

Request example:

```json
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
    "time": 0,
    "sign": ""
}
```

- Backend or application reply to device (no response required)

| Message topic | topic: access_device/v2/event/{#uuid}/heartbeat_reply |
| --------- | ----------------------------------------------------- |

#### 2.7 Last Will (Offline)

- Device to backend or application

| Message topic | topic: access_device/v2/event/offline |
| --------- | ------------------------------------- |

Request example:

```json
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
    "time": 0,
    "sign": ""
}
```

#### 2.8 Connection Report

- Device to backend or application

| Message topic | topic: access_device/v2/event/connect |
| --------- | ------------------------------------- |

`data` parameters

| Parameter | Description | Type | Required | Notes                        |
| ---------- | ---------------------------- | ------ | ---- | ------------------------------- |
| appVersion | Application version | String | Y | Application version |
| btMac | Bluetooth MAC | String | Y | Bluetooth MAC address |
| mac | Device hardware unique ID | String | N | Device hardware unique ID |
| clientId | MQTT client ID, default same as device address | String | Y | MQTT client ID |
| type | Network type | Int | Y | `0`: Ethernet; `1`: Wi-Fi; `2`: 4G |
| ssid | Wi-Fi SSID | String | Y | Wi-Fi name |
| pwd | Wi-Fi password | String | Y | Wi-Fi password |
| dhcp | DHCP mode | Int | Y | `1`: DHCP; `0`: static IP |
| ip | IP address | String | Y | IP address |
| gateway | Gateway | String | Y | Gateway |
| dns | DNS servers | String | Y | DNS server(s) |
| subnetMask | Subnet mask | String | Y | Subnet mask |
| netMac | NIC MAC | String | Y | Network interface MAC |

Request example:

```json
{
  "serialNo": "0000000001",
  "uuid": "e4720000964b5c00",
  "time": 1737364204,
  "data": {
    "appVersion": "DW205_v20xxxx",
    "btMac": "000000000000",
    "mac": "e4ff00009df1d100",
    "clientId": "e4720000964b5c00",
    "name": "TODO",
    "type": 1,
    "ssid": "",
    "pwd": "",
    "dhcp": 1,
    "ip": "10.102.106.24",
    "gateway": "10.102.106.124",
    "dns": "10.102.106.124",
    "netMac": "ee:28:00:00:9d:f1"
  }
}
```

- Backend or application reply to device (no reply required)

| Message topic | topic:face_device/v2/event/connect_reply |
| --------- | ---------------------------------------- |

#### 2.9 Online Verification

- Device to backend or application

| Message topic | topic: `access_device/v2/event/access_online` |
| --------- | ------------------------------------------- |

`data` parameters

| Parameter | Description | Type | Required | Notes |
| :------ | :------- | :----- | ---- | --------------------------------------------------- |
| code | Credential | String | Yes | Empty for face recognition |
| type | Credential type | Int | Yes | See Appendix 3 Credential Types, `num` column |
| index | Door controller index | String | No | e.g. for 4-door controller: `1`,`2`,`3`,`4`; may be empty |
| time | Access time | Long | Yes | Unix timestamp in seconds |
| extra | Extra fields | Object | No | Extensible; often raw data such as original QR content |
| srcData | Raw data | String | No | Original data |

Request example:

```json
{
    "serialNo": "0000000001",
    "uuid": "e4720000964b5c00",
    "data": {
        "code":"s345463434gg",
        "type": 103,
        "time": 1640917147,
        "extra":{
          "srcData" : "vg://v203AQAGAHZndWFuZwIAQAAlcOsQMXN9TJGCK5Afs14p4orxE+QnmI4gb2F85pvrvbQW1/+CyPEE1Bi3X4T3SYFZRoheykjICfdwWU+kw/Vf2965"
        }
    },
    "time": 1647580466,
    "sign": ""
}
```

- Backend or application reply to device

| Message topic | topic: access_device/v2/event/{#uuid}/access_online_reply |
| --------- | --------------------------------------------------------- |

Response example

```json
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"time": 1640917147,
    "sign": "",
	"code": "000000",
	"message": "success"
}
```

## 3. Authorized User Provisioning Flow

#### 3.1 Flow Diagram

```mermaid
flowchart TD
 A([Start])
 B[Prepare user data]
 C[Push users insertUser]
 D{Wait for reply insertUser_reply}
 E[Users stored]
 F[Log failed batch]
 G[Prepare face credentials]
 H[Push credentials insertKey]
 I{Wait for reply insertKey_reply}
 J[Credentials stored]
 K[Log failed batch]
 L[Prepare permission data]
 M[Push permissions insertPermission]
 N{Wait for reply insertPermission_reply}
 O[Permissions applied]
 P[Log failed batch]
 Q([Done])

#### 3.2 Flow Notes

* `insertUser` and `insertKey` are linked by the `userId` field; `insertUser` and `insertPermission` are linked by `permissionIds`
* For fingerprint, QR code, or card access: use the same `userId` in `insertUser` and `insertKey`, and the same `permissionIds` in `insertUser` as `permissionId` in `insertPermission`. All three APIs are required.
* Call order among the three APIs is not enforced; the device does not validate `userId`/`permissionIds` linkage. Recommended order: user → credential → permission.
* In `insertUser`, `userId` is the primary key. Avoid duplicates in batch push or existing users are updated. `permissionIds` must map 1:1 to `permissionId` in `insertPermission`.
* In `insertKey`, `keyId` is the primary key. Avoid duplicates or credentials are updated. `userId` must match a user from `insertUser`.
* In `insertPermission`, `permissionId` is the primary key. Avoid duplicates or permissions are updated.
* Do not use the same value for `userId`, `keyId`, and `permissionId` for one person. Use distinct IDs and map them explicitly, especially when one person has multiple QR codes, cards, or permissions.

## 4. User Management APIs

#### 4.1 Add User

- Backend or application to device

| Message topic | topic: access_device/v2/cmd/{#uuid}/insertUser |
| --------- | ---------------------------------------------- |

`data` parameters (max 100 per request)

| Parameter | Description | Type | Required | Notes                                               |
| ------------- | -------- | ------ | ---- | ------------------------------------------------------ |
| userId | User ID | String | Y | Unique, alphanumeric only, max 128 bytes, e.g. SW200 |
| name | User name | String | Y | Required, non-empty, max 128 bytes. |
| permissionIds | Permission IDs | Array | Y | Maps user to permissions; matches `permissionId` in `insertPermission` |
| extra | Extra fields | Object | No | Additional user attributes |

- If a user with the same `userId` already exists, the device updates all fields for that user.

Request example:

```json
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"data": [{
			"userId": "20190101120101",
        	"permissionIds":["6584132"],
			"name": "Zhang San",
			"extra": {
				"xxxx": xxxx
			}
		},
		{
			"userId": "20190101120102",
			"name": "Li Si",
            "permissionIds":["6584132"],
			"extra": {
				"xxxx": "xxxx"
			}
		}
	],
	"time": 1647580466,
	"sign": ""
}
```

- Device reply to backend or application

| Message topic | topic: access_device/v2/cmd/insertUser_reply |
| --------- | -------------------------------------------- |

- Common `data` fields (present only on failure):

| Parameter | Description | Type | Notes                         |
| ------ | -------- | ------ | -------------------------------- |
| userId | User ID | String | Failed user ID |
| errmsg | Error message | String | Specific failure reason, e.g. parse error |

Success response example

```json
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"time": 0,
    "sign": "",
	"code": "000000",
	"message": "success"
}
```

Failure response example

```json
{
    "serialNo": "0000000001",
    "uuid": "e4720000964b5c00",
    "code": "C00001",
    "time": 1761275206,
    "sign": "",
    "message": "insertUser: Failed to insert user",
    "data": [
        {
            "userId": "20190101120101",
            "errmsg": "user array parse (0) failed"
        },
        {
            "userId": "20190101120102",
            "errmsg": "user array parse (1) failed"
        }
    ]
}
```

#### 4.2 Delete User

- Backend or application to device

| Message topic | topic: access_device/v2/cmd/{#uuid}/delUser |
| --------- | ------------------------------------------- |

`data` parameters

| Parameter | Description | Type | Required | Notes           |
| ------ | ------- | ----- | ---- | ------------------ |
| data | User IDs | array | Y | Each element is a user ID |

Request example:

```json
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"time": 0,
	"sign": "",
	"data": ["001","002","003"]
}
```

- Device reply to backend or application

| Message topic | topic: access_device/v2/cmd/delUser_reply |
| --------- | ----------------------------------------- |

- Common `data` fields (present only on failure):

| Parameter | Description | Type | Notes                         |
| ------ | -------- | ------ | -------------------------------- |
| userId | User ID | String | Failed user ID |
| errmsg | Error message | String | Specific failure reason, e.g. parse error |

Success response example

```json
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"time": 0,
    "sign": "",
	"code": "000000",
	"message": "success"
}
```

Failure response example

```json
{
    "serialNo": "0000000001",
    "uuid": "f47b00008ee62a00",
    "code": "C00001",
    "time": 1761275616,
    "sign": "",
    "message": "delUser: Failed to delete user",
    "data": [
        {
            "userId": "001",
            "errmsg": "delete userId:001 failure"
        },
        {
            "userId": "002",
            "errmsg": "delete userId:002 failure"
        }
    ]
}
```

#### 4.3 Clear All Users

- Backend or application to device

| Message topic | topic: access_device/v2/cmd/{#uuid}/clearUser |
| --------- | --------------------------------------------- |

Request example:

```json
{
    "serialNo": "0000000001",
    "uuid": "e4720000964b5c00",
    "time": 1754032384,
    "sign": ""
}
```

- Device reply to backend or application

| Message topic | topic: access_device/v2/cmd/clearUser_reply |
| --------- | ------------------------------------------- |

Response example

```json
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"code": "000000",
	"time": 1754032640,
	"sign": "",
	"message": "success"
}
```

#### 4.4 Query Users

- Backend or application to device

| Message topic | topic: access_device/v2/cmd/{#uuid}/getUser |
| --------- | ------------------------------------------- |

`data` parameters

| Parameter | Description | Type | Required | Notes                                |
| ------ | ------------ | ------ | ---- | --------------------------------------- |
| userId | User ID | String | N | Query by user ID |
| name | User name | String | N | If omitted, name filter is not applied |
| size | Page size | int | Y | Range (0, 100] |
| page | Page index | int | Y | Zero-based page number |

Request example:

```json
{
    "serialNo": "0000000001",
    "uuid": "e4720000964b5c00",
    "time": 1751538000,
    "sign": "",
    "data": {
        "userId": "",
        "name": "",
        "page": 0,
        "size": 10
    }
}
```

- Device reply to backend or application

| Message topic | topic: access_device/v2/cmd/getUser_reply |
| --------- | ----------------------------------------- |

Query response `data` parameters

| Parameter | Description | Type | Required | Notes                                     |
| --------- | ---------------- | ----- | ---- | -------------------------------------------- |
| page | Current page | Int | Y | Current page index |
| size | Page size | Int | Y | Items per page |
| total | Total count | Int | Y | Total records |
| totalPage | Total pages | Int | Y | Total page count |
| count | Result count | Int | Y | Length of `content` array (≤ `size`) |
| content | User array | Array | Y | See content table |

content fields

| Parameter | Description | Type | Required | Notes |
| ------------- | -------- | ------ | ---- | -------- |
| userId | User ID | String | Y | |
| name | User name | String | Y | |
| permissionIds | Permission IDs | Array | Y | |
| extra | Extension fields | Object | Y | See extra table |

extra table

| Parameter | Description | Type | Required | Notes |
| -------- | -------- | ---- | ---- | -------- |
| userType | User type | Int | Y | |
| addSrc | Registration source | Int | Y | |
| addTime | Registration time | Int | Y | |

Response example

```json
When user query succeeds:
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"code": "000000",
	"time": 1754032390,
	"sign": "",
	"message": "Success",
	"data": {
		"page": 0,
		"size": 10,
		"total": 5,
		"totalPage": 0,
		"count": 5,
		"content": [{
			"userId": "1",
			"name": "James",
            "permissionIds":["6584132"],
			"extra": {
				"userType": 1,
				"addSrc": 0,
				"addTime": 1754027509921
			}
		}, {
			"userId": "2",
			"name": "Lily",
			"permissionIds":["6584132"],
			"extra": {
				"userType": 1,
				"addSrc": 1,
				"addTime": 1754027489423
			}
		}, {
			"userId": "3",
			"name": "Grace",
			"permissionIds":["6584132"],
			"extra": {
				"userType": 0,
				"addSrc": 1,
				"addTime": 1754027489433
			}
		}, {
			"userId": "4",
			"name": "Wendy",
            "permissionIds":["6584132"],
			"extra": {
				"userType": 0,
				"addSrc": 1,
				"addTime": 1754027489443
			}
		}, {
			"userId": "5",
			"name": "Emma",
            "permissionIds":["6584132"],
			"extra": {
				"userType": 0,
				"addSrc": 1,
				"addTime": 1754027489458
			}
		}]
	}
}
When no users match:
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"code": "C00001",
	"time": 1754032816,
	"sign": "",
	"message": "selectUser: no data as this select condition"
}
```

#### 4.5 Modify User

- Backend or application to device

| Message topic | topic: access_device/v2/cmd/{#uuid}/modifyUser |
| --------- | ---------------------------------------------- |

`data` parameters (max 100 per request)

| Parameter | Description | Type | Required | Notes                                               |
| ------------- | -------- | ------ | ---- | ------------------------------------------------------ |
| userId | User ID | String | Y | Unique, alphanumeric only, max 128 bytes, e.g. SW200 |
| name | User name | String | N | If provided, must be non-empty, max 128 bytes. |
| permissionIds | Permission IDs | Array | N | Maps user to permissions; matches `permissionId` in `insertPermission` |
| extra | Extra fields | Object | N | Additional user attributes |

- Only users already provisioned with the given `userId` can be modified.

Request example:

```json
{
	"serialNo": "6w8keif5g6",
	"uuid": "e4720000964b5c00",
	"data": [{
			"userId": "20190101120101",
            "name":"Li Si"
        	"permissionIds":["6584133"],
		},
		{
			"userId": "20190101120102",
			"name": "Wang Erma",
			"extra": {
				"xxxx": "xxxx"
			}
		}
	],
	"time": 1647580466,
	"sign": ""
}
```

- Device reply to backend or application

| Message topic | topic: access_device/v2/cmd/modifyUser_reply |
| --------- | -------------------------------------------- |

- Common `data` fields (present only on failure):

| Parameter | Description | Type | Notes                         |
| ------ | -------- | ------ | -------------------------------- |
| userId | User ID | String | Failed user ID |
| errmsg | Error message | String | Specific failure reason, e.g. parse error |

Success response example

```json
{
	"serialNo": "6w8keif5g6",
	"uuid": "e4720000964b5c00",
	"time": 0,
    "sign": "",
	"code": "000000",
	"message": "success"
}
```

Failure response example

```json
{
    "serialNo": "6w8keif5g6",
    "uuid": "e4720000964b5c00",
    "code": "C00001",
    "time": 1761275206,
    "sign": "",
    "message": "modifyUser: Failed to modifyUser",
    "data": [
        {
            "userId": "20190101120101",
            "errmsg": "user array parse (0) failed"
        },
        {
            "userId": "20190101120102",
            "errmsg": "user array parse (1) failed"
        }
    ]
}
```

## 5. Credential Management APIs

#### 5.1 Add Credential

- Backend or application to device

| Message topic | topic:access_device/v2/cmd/{#uuid}/insertKey |
| --------- | -------------------------------------------- |

`data` parameters (max 100 per request)

| Parameter | Required | Type | Description | Notes |
| ------ | -------- | ------ | ---- | -------------------------------- |
| keyId | Credential ID | String | Yes | Unique credential identifier |
| userId | User ID | String | Yes | Unique user identifier |
| type | Credential type | String | Yes | See [Appendix 3 Credential Types](#appendix-3-credential-types), `num` column |
| code | Credential data | String | Yes | For face type: Base64 of face JPG image |
| extra | Extra fields | Object | No | Additional credential attributes |

- `userId` must match the user ID from `insertUser`.
- If a credential with the same `keyId` exists, the device updates it.
- Credentials are registered one by one. Failures are recorded in real time and returned in full after the batch completes.

Request example:

```json
{
    "serialNo": "0000000001",
    "uuid": "e4720000964b5c00",
    "data": [{
            "keyId": "20190101120101",
            "userId": "20190101120101",
            "type": "300",
            "code": "ZnNmZHNmYXNkZmFzZGY=........",
        	"extra":{
                "faceType":"0"
            }
        },
        {
            "keyId": "20190101120101",
            "userId": "20190101120102",
            "type": "500",
            "code": "xxxxx" // fingerprint feature value
        }
    ],
    "time": 1647580466,
    "sign": ""
}
```

- Device reply to backend or application

| Message topic | topic: access_device/v2/cmd/insertKey_reply |
| --------- | ------------------------------------------- |

- Common `data` fields (present only on failure):

| Parameter | Description | Type | Notes                         |
| ------ | -------- | ------ | -------------------------------- |
| keyId | Credential ID | String | Failed credential ID |
| errmsg | Error message | String | Specific failure reason, e.g. parse error |

Success response example

```json
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"time": 0,
    "sign": "",
	"code": "000000",
	"message": "success"
}
```

Failure response example

```json
{
    "serialNo": "0000000001",
    "uuid": "f47b00008ee62a00",
    "code": "C00001",
    "time": 1761275488,
    "sign": "",
    "message": "insertKey: Failed to insert credential",
    "data": [
        {
            "keyId": "20190101120101",
            "errmsg": "key array parse (0) failed"
        },
        {
            "keyId": "20190101120102",
            "errmsg": "key array parse (1) failed"
        }
    ]
}
```

#### 5.2 Query Credentials

- Backend or application to device

| Message topic | topic: access_device/v2/cmd/{#uuid}/getKey |
| --------- | ------------------------------------------ |

`data` parameters

| Parameter | Description | Type | Required | Notes                                                     |
| ------ | ------------------ | ------ | ---- | ------------------------------------------------------------ |
| keyId | Credential ID | String | N | Credential unique ID |
| userId | User ID | String | N | User unique ID |
| type | Filter by credential type | int | N | See [Appendix 3 Credential Types](#appendix-3-credential-types)                              |
| size | Page size | int | Y | Range (0, 100] |
| page | Page index | int | Y | Zero-based; must be less than `totalPage` |

Request example:

```json
{
    "serialNo": "0000000001",
    "uuid": "e4720000964b5c00",
    "data":{
      "keyId": "20190101120101",
      "userId": "20190101120101",
      "type":500,
      "page": 0,
      "size": 10
    },
    "time": 1647580466,
    "sign": ""
}
```

- Device reply to backend or application

| Message topic | topic: access_device/v2/cmd/getKey_reply |
| --------- | ---------------------------------------- |

Query response `data` parameters

| Parameter | Description | Type | Required | Notes                                     |
| --------- | ---------------- | ----- | ---- | -------------------------------------------- |
| page | Current page | Int | Y | Current page index |
| size | Page size | Int | Y | Items per page |
| total | Total count | Int | Y | Total records |
| totalPage | Total pages | Int | Y | Total page count |
| count | Result count | Int | Y | Length of `content` array (≤ `size`) |
| content | Credential array | Array | Y | See content table                       |

content fields

| Parameter | Required | Type | Description | Notes                            |
| :----- | :------- | :----- | ---- | ------------------------------- |
| keyId | Credential ID | String | Y | Unique credential ID |
| userId | User ID | String | Y | Unique user identifier |
| type | Credential type | int | Y | See Appendix 3 |
| code | Credential data | String | Y | Face: Base64 image |
| extra | Extra fields | Object | N | Additional credential attributes |

Response example

```json
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"result": 0,
	"code": "000000",
	"message": "success",
	"data": {
		"page": 0,
		"size": 20,
		"total": 2,
		"totalPage": 1,
		"count": 2,
		"content": [{
				"keyId": "100001",
            	"userId": "13",
				"type": "",
				"code": "card credential value",
            	"extra": {
					"xxxx":xxx
                }
			},
			{
				"keyId": "100002",
                "userId": "12",
				"type": "",
				"code": "QR credential value"
			}
		]
	}
}
```

#### 5.3 Delete Credential

- Backend or application to device

| Message topic | topic: access_device/v2/cmd/{#uuid}/delKey |
| --------- | ------------------------------------------ |

`data` parameters

| Parameter | Required | Type | Required | Notes |
| :------ | :----- | :---- | ---- | ---------------- |
| keyIds | Credential IDs | array | No | Credential unique IDs |
| userIds | User IDs | array | No | User unique IDs |

- `keyIds` and `userIds` may be sent together. Duplicate or non-existent deletions do not cause errors.

Request example:

```json
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"time": 0,
	"sign": "",
	"data": {
        "keyIds":["20190101120101","20190101120102"],
        "userIds":["20190101120101","20190101120102"]
    }
}
```

- Device reply to backend or application

| Message topic | topic: access_device/v2/cmd/delKey_reply |
| --------- | ---------------------------------------- |

- Common `data` fields (present only on failure):

| Parameter | Description | Type | Notes                         |
| ------ | -------- | ------ | -------------------------------- |
| keyId | Credential ID | String | Failed credential ID |
| errmsg | Error message | String | Specific failure reason, e.g. parse error |

Response example

```json
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"time": 0,
    "sign": "",
	"code": "000000",
	"message": "success"
}
```

Failure response example

```json
{
    "serialNo": "0000000001",
    "uuid": "f47b00008ee62a00",
    "code": "C00001",
    "time": 1761275488,
    "sign": "",
    "message": "delKey: Failed to delete credential",
    "data": [
        {
            "keyId": "20190101120101",
            "errmsg": "delKey by userId: 20190101120101 error"
        },
        {
            "keyId": "invalid",
            "errmsg": "array item:1's userId is invalid"
        }
    ]
}
```

#### 5.4 Clear All Credentials

- Backend or application to device

| Message topic | topic: access_device/v2/cmd/{#uuid}/clearKey |
| --------- | -------------------------------------------- |

Request example:

```json
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"time": 0,
	"sign": ""
}
```

- Device reply to backend or application

| Message topic | topic: access_device/v2/cmd/clearKey_reply |
| --------- | ------------------------------------------ |

Response example

```json
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"time": 0,
    "sign": "",
	"code": "000000",
	"message": "success"
}
```

#### 5.5 Modify Credential

- Backend or application to device

| Message topic | topic:access_device/v2/cmd/{#uuid}/modifyKey |
| --------- | -------------------------------------------- |

`data` parameters (max 100 per request)

| Parameter | Required | Type | Description | Notes                                                         |
| ------ | -------- | ------ | ---- | ------------------------------------------------------------ |
| keyId | Credential ID | String | Y | Unique credential ID |
| userId | User ID | String | N | Unique user identifier |
| type | Credential type | int | N | See Appendix 3                             |
| code | Credential data | String | N | Face: Base64 (other registration modes may apply). Face credentials must be sent alone, not mixed with other types in one batch. |
| extra | Extra fields | Object | N | Additional credential attributes |

extra table

| Parameter | Description | Type | Required | Notes                                   |
| -------- | ------------ | ------ | ---- | ------------------------------------------ |
| faceType | Face registration mode | String | Y | `0`: Base64; `1`: feature vector; `2`: URL download; `3`: ZIP package |

- When changing `userId`, ensure the user exists or access will fail.
- Only credentials already provisioned with the given `keyId` can be modified.

Request example:

```json
{
    "serialNo": "6w8keif5g6",
    "uuid": "e4720000964b5c00",
    "data": [{
            "keyId": "20190101120101",
            "userId": "20190101120101",
            "type": "300",
            "code": "ZnNmZHNmYXNkZmFzZGY=........",
        	"extra":{
                "faceType":"301"
            }
        },
        {
            "keyId": "20190101120101",
            "userId": "20190101120102",
            "type": "103",
            "code": "1233456"
        }
    ],
    "time": 1647580466,
    "sign": ""
}
```

- Device reply to backend or application

| Message topic | topic: access_device/v2/cmd/modifyKey_reply |
| --------- | ------------------------------------------- |

- Common `data` fields (present only on failure):

| Parameter | Description | Type | Notes                         |
| ------ | -------- | ------ | -------------------------------- |
| keyId | Credential ID | String | Failed credential ID |
| errmsg | Error message | String | Specific failure reason, e.g. parse error |

Success response example

```json
{
	"serialNo": "6w8keif5g6",
	"uuid": "e4720000964b5c00",
	"time": 0,
    "sign": "",
	"code": "000000",
	"message": "success"
}
```

Failure response example

```json
{
    "serialNo": "6w8keif5g6",
    "uuid": "f47b00008ee62a00",
    "code": "C00001",
    "time": 1761275488,
    "sign": "",
    "message": "modifyKey: Failed to modifyKey",
    "data": [
        {
            "keyId": "20190101120101",
            "errmsg": "key array parse (0) failed"
        },
        {
            "keyId": "20190101120102",
            "errmsg": "key array parse (1) failed"
        }
    ]
}
```

## 6. Permission Management APIs

#### 6.1 Add Permission

- Backend or application to device

| Message topic | topic: access_device/v2/cmd/{#uuid}/insertPermission |
| --------- | ---------------------------------------------------- |

`data` parameters (max 100 per request)

| Parameter | Description | Type | Required | Notes |
| :----------- | :------- | :----- | ---- | ------------------------------------------------------------ |
| permissionId | Permission ID | String | Y | Unique permission ID; recommended 32-char random string |
| time | Time window | Object | N | See [Appendix 4 Time Window](#appendix-4-time-window) |
| extra | Extra fields | Object | N | Reserved, optional |

Request example:

```json
{
	"scerialNo": "0000000001",
	"sign": "",
	"time": 1704866881,
	"uuid": "e4720000964b5c00",
	"data": [{
		"permissionId": "6584132",
		"time": {
			"type": 3,
			"weekPeriodTime": {
				"1": "9:00-14:05",
				"2": "12:00-13:30|15:00-16:30"
			},
			"range": {
				"beginTime": 1640917147,
				"endTime": 1790917147
			}
		}
	}]

}
```

- Device reply to backend or application

| Message topic | topic: access_device/v2/cmd/insertPermission_reply |
| --------- | -------------------------------------------------- |

- Common `data` fields (present only on failure):

| Parameter | Description | Type | Notes                         |
| ------------ | -------- | ------ | -------------------------------- |
| permissionId | Permission ID | String | Failed permission ID |
| errmsg | Error message | String | Specific failure reason |

Success response example

```json
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"time": 0,
    "sign": "",
	"code": "000000",
	"message": "success"
}
```

Failure response example

```json
{
    "serialNo": "0000000001",
    "uuid": "f47b00008ee62a00",
    "code": "C00001",
    "time": 1761275616,
    "sign": "",
    "message": "insertPermission: Failed to insert permission",
    "data": [
        {
            "permissionId": "6584132",
            "errmsg": "permission array parse (0) failed"
        },
        {
            "permissionId": "6584133",
            "errmsg": "permission array parse (1) failed"
        }
    ]
}
```

#### 6.2 Query Permissions

- Backend or application to device

| Message topic | topic: access_device/v2/cmd/{#uuid}/getPermission |
| --------- | ------------------------------------------------- |

`data` parameters

| Parameter | Description | Type | Required | Notes                                                     |
| ------------ | ------------ | ------ | ---- | ------------------------------------------------------------ |
| permissionId | Permission ID | String | N | |
| page | Page index | Int | Y | Range (0, 100] |
| size | Page size | Int | Y | Zero-based; must be less than total pages |

Request example:

```json
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"time": 0,
	"sign": "",
	"data": {
        "page": 0,
		"size": 100
	}
}
```

- Device reply to backend or application

| Message topic | topic: access_device/v2/cmd/getPermission_reply |
| --------- | ----------------------------------------------- |

Query response `data` parameters

| Parameter | Description | Type | Required | Notes                                     |
| --------- | ---------------- | ----- | ---- | -------------------------------------------- |
| page | Current page | Int | Y | Current page index |
| size | Page size | Int | Y | Items per page |
| total | Total count | Int | Y | Total records |
| totalPage | Total pages | Int | Y | Total page count |
| count | Result count | Int | Y | Length of `content` array (≤ `size`) |
| content | User array | Array | Y | See content table |

content fields

| Parameter | Description | Type | Required | Notes                             |
| ------------ | -------- | ------ | ---- | ------------------------------------ |
| permissionId | Permission ID | String | Y | |
| time | Time window | String | Y | See Appendix 4 |
| extra | Extension fields | Object | N | |

Response example

```json
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"sign": "",
	"code": "000000",
	"data": {
		"content": [{
			"permissionId": "6584132",
			"time": {
				"type": 3,
				"range": {
					"beginTime": 1640917147,
					"endTime": 1790917147
				},
				"weekPeriodTime": {
					"1": "9:00-14:05",
					"2": "12:00-13:30|15:00-16:30"
				}
			}
		}],
		"page": 0,
		"size": 200,
		"total": 1,
		"totalPage": 1,
		"count": 1
	},
	"message": "success",
	"time": 1711595116
}
```

#### 6.3 Delete Permission

- Backend or application to device

| Message topic | topic: access_device/v2/cmd/{#uuid}/delPermission |
| --------- | ------------------------------------------------- |

`data` parameters

| Parameter | Description | Type | Required | Notes |
| :------------ | :----- | :---- | ---- | -------------- |
| permissionIds | Permission IDs | array | No | Permission unique IDs |
| Request example:    |        |       |      |                |

```json
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"data": {
		"permissionIds": ["20190101120101", "20190101120102"]
	},
	"time": 1647580466,
	"sign": ""
}
```

- Device reply to backend or application

| Message topic | topic: access_device/v2/cmd/delPermission_reply |
| --------- | ----------------------------------------------- |

- Common `data` fields (present only on failure):

| Parameter | Description | Type | Notes                         |
| ------------ | -------- | ------ | -------------------------------- |
| permissionId | Permission ID | String | Failed permission ID |
| errmsg | Error message | String | Specific failure reason |

Success response example

```json
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"time": 0,
    "sign": "",
	"code": "000000",
	"message": "success"
}
```

Failure response example

```json
{
    "serialNo": "0000000001",
    "uuid": "f47b00008ee62a00",
    "code": "C00001",
    "time": 1761275488,
    "sign": "",
    "message": "delPermission: Failed to delete permission",
    "data": [
        {
            "permissionId": "20190101120101",
            "errmsg": "delete permission by userId:20190101120101 failed"
        },
        {
            "permissionId": "invalid",
            "errmsg": "get array item:1 failure"
        }
    ]
}
```

#### 6.4 Clear All Permissions

- Backend or application to device

| Message topic | topic: access_device/v2/cmd/{#uuid}/clearPermission |
| --------- | --------------------------------------------------- |

Request example:

```json
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"time": 0,
	"sign": ""
}
```

- Device reply to backend or application

| Message topic | topic: access_device/v2/cmd/clearPermission_reply |
| --------- | ------------------------------------------------- |

Response example

```json
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"time": 0,
    "sign": "",
	"code": "000000",
	"message": "success"
}
```

#### 6.5 Modify Permission

- Backend or application to device

| Message topic | topic: access_device/v2/cmd/{#uuid}/modifyPermission |
| --------- | ---------------------------------------------------- |

`data` parameters (max 100 per request)

| Parameter | Description | Type | Required | Notes |
| :----------- | :------- | :----- | ---- | ------------------------------------------------------------ |
| permissionId | Permission ID | String | Y | Unique permission ID; recommended 32-char random string |
| time | Time window | Object | N | See [Appendix 4 Time Window](#appendix-4-time-window) |
| extra | Extra fields | Object | N | Reserved, optional |

Request example:

```json
{
	"scerialNo": "123456",
	"sign": "",
	"time": 1704866881,
	"uuid": "e4720000964b5c00",
	"data": [{
		"permissionId": "6584132",
		"time": {
			"type": 0,
		}
	}]
}
```

- Device reply to backend or application

| Message topic | topic: access_device/v2/cmd/modifyPermission_reply |
| --------- | -------------------------------------------------- |

- Common `data` fields (present only on failure):

| Parameter | Description | Type | Notes                         |
| ------------ | -------- | ------ | -------------------------------- |
| permissionId | Permission ID | String | Failed permission ID |
| errmsg | Error message | String | Specific failure reason |

Success response example

```json
{
	"serialNo": "123456",
	"uuid": "e4720000964b5c00",
	"time": 0,
    "sign": "",
	"code": "000000",
	"message": "success"
}
```

Failure response example

```json
{
    "serialNo": "123456",
    "uuid": "e4720000964b5c00",
    "code": "C00001",
    "time": 1761275616,
    "sign": "",
    "message": "insertPermission: Failed to modifyPermission",
    "data": [
        {
            "permissionId": "6584132",
            "errmsg": "permission array parse (0) failed"
        },
        {
            "permissionId": "6584133",
            "errmsg": "permission array parse (1) failed"
        }
    ]
}
```

## 7. Security Key Management APIs

#### 7.1 Add Security Key

- Backend or application to device

| Message topic | topic: access_device/v2/cmd/{#uuid}/insertSecurity |
| --------- | -------------------------------------------------- |

`data` parameters (max 100 per request)

| Parameter | Description | Type | Required | Notes                         |
| ---------- | --------- | ------ | ---- | -------------------------------- |
| securityId | Security key ID | String | Y | Unique key identifier |
| type | Key type | String | Y | e.g. RSA, AES |
| key | Key code | String | Y | Key vendor/code, e.g. vguang |
| value | Key value | String | Y | |
| startTime | Start time | Int | Y | Key valid-from, Unix seconds |
| endTime | Expiry time | Int | Y | Key valid-until, Unix seconds |

Request example:

```json
{
    "serialNo": "0000000001",
    "uuid": "e4720000964b5c00",
    "data": [{
            "type": "RSA",
            "securityId": "213v",
            "key": "vguang",
            "value": "MFwwDQYJKoZIhvcNAQEBBQADSwAwSAJBAIhGA5XLhPR22MRf7ms4R3NeUyV4UvnUiu2YIrxB4RMojK8QY90760Otx6fWZsEi0gY5ysLWPZSZdu92vA4s1BsCAwEAAQ==",
            "startTime": 1560303425,
            "endTime": 1683918932
        },
        {
            "type": "RSA",
            "securityId": "213t",
            "key": "test",
            "value": "MFwwDQYJKoZIhvcNAQEBBQADSwAwSAJBAIhGA5XLhPR22MRf7ms4R3NeUyV4UvnUiu2YIrxB4RMojK8QY90760Otx6fWZsEi0gY5ysLWPZSZdu92vA4s1BsCAwEAAQ==",
            "startTime": 1560303425,
            "endTime": 1683918932
        }
    ],
    "time": 1647580466,
    "sign": ""
}
```

- Device reply to backend or application

| Message topic | topic: access_device/v2/cmd/insertSecurity_reply |
| --------- | ------------------------------------------------ |

Response example

```json
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"time": 0,
    "sign": "",
	"code": "000000",
	"message": "success"
}
```

#### 7.2 Query Security Keys

- Backend or application to device

| Message topic | topic: access_device/v2/cmd/{#uuid}/getSecurity |
| --------- | ----------------------------------------------- |

`data` parameters

| Parameter | Description | Type | Required | Notes                                                     |
| ---------- | ------------ | ------ | ---- | ------------------------------------------------------------ |
| securityId | Security key ID | String | Y | Unique key identifier |
| type | Key type | String | Y | e.g. RSA, AES |
| code | Key code | String | Y | Key vendor/code, e.g. vguang |
| page | Page index | Int | Y | Range (0, 100] |
| size | Page size | Int | Y | Zero-based; must be less than total pages |

Request example:

```json
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"time": 0,
	"sign": "",
	"data": {
        "securityId": "001",
		"type": "RSA",
		"code": "vguang",
		"startTime": 1640917147,
		"endTime": 1672453147
	}
}
```

- Device reply to backend or application

| Message topic | topic: access_device/v2/cmd/getSecurity_reply |
| --------- | --------------------------------------------- |

`data` parameters

| Parameter | Description | Type | Required | Notes                                     |
| --------- | ---------------- | ----- | ---- | -------------------------------------------- |
| page | Current page | Int | Y | Current page index |
| size | Page size | Int | Y | Items per page |
| total | Total count | Int | Y | Total records |
| totalPage | Total pages | Int | Y | Total page count |
| count | Result count | Int | Y | Length of `content` array (≤ `size`) |
| content | Security key array | Array | Y | See content table                       |

content fields

| Parameter | Description | Type | Required | Notes                         |
| --------- | -------- | ------ | ---- | -------------------------------- |
| type | Key type | String | Y | e.g. RSA, AES |
| code | Key code | String | Y | Key vendor/code, e.g. vguang |
| key | Key value | String | Y | |
| startTime | Start time | Int | Y | Key valid-from, Unix seconds |
| endTime | Expiry time | Int | Y | Key valid-until, Unix seconds |

Response example

```json
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"time": 0,
	"sign": "",
	"code": "000000",
	"message": "success",
	"data": {
		"page": 0,
		"size": 20,
		"total": 1,
		"totalPage": 1,
		"count": 1,
		"content": [{
            "securityId": "001",
			"type": "RSA",
			"code": "vguang",
			"key": "MFwwDQYJKoZIhvcNAQEBBQADSwAwSAJBAIhGA5XLhPR22MRf7ms4R3NeUyV4UvnUiu2YIrxB4RMojK8QY90760Otx6fWZsEi0gY5ysLWPZSZdu92vA4s1BsCAwEAAQ==",
			"startTime": 1563456783,
			"endTime": 1963456783
		}， {
            "securityId": "002",
			"type": "RSA",
			"code": "vguang",
			"key": "MFwwDQYJKoZIhvcNAQEBBQADSwAwSAJBAIhGA5XLhPR22MRf7ms4R3NeUyV4UvnUiu2YIrxB4RMojK8QY90760Otx6fWZsEi0gY5ysLWPZSZdu92vA4s1BsCAwEAAQ==",
			"startTime": 1563456783,
			"endTime": 1963456783
		}]
	}
}
```

#### 7.3 Delete Security Key

- Backend or application to device

| Message topic | topic: access_device/v2/cmd/{#uuid}/delSecurity |
| --------- | ----------------------------------------------- |

`data` parameters

| Parameter | Description | Type | Required | Notes       |
| ------ | ------- | ----- | ---- | -------------- |
| data | Security key IDs | array | Y | Each element is a key ID |

Request example:

```json
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"time": 0,
	"sign": "",
	"data": ["001","002","003"]
}
```

- Device reply to backend or application

| Message topic | topic: access_device/v2/cmd/delSecurity_reply |
| --------- | --------------------------------------------- |

Response example

```json
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"time": 0,
    "sign": "",
	"code": "000000",
	"message": "success"
}
```

#### 7.4 Clear All Security Keys

- Backend or application to device

| Message topic | topic: access_device/v2/cmd/{#uuid}/clearSecurity |
| --------- | ------------------------------------------------- |

Request example:

```json
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"time": 0,
	"sign": ""
}
```

- Device reply to backend or application

| Message topic | topic: access_device/v2/cmd/clearSecurity_reply |
| --------- | ----------------------------------------------- |

Response example

```json
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"time": 0,
    "sign": "",
	"code": "000000",
	"message": "success"
}
```

## 8. Recognition Records

#### 8.1 Query Recognition Records

- Backend or application to device

| Message topic | topic: access_device/v2/cmd/{#uuid}/getRecords |
| --------- | ---------------------------------------------- |

`data` parameters

| Parameter | Description | Type | Required | Notes                                                     |
| --------- | ------------ | ------ | ---- | ------------------------------------------------------------ |
| recordId | Access record ID | String | N | Unique access record ID |
| userId | User IDs | array | N | Filter by user; pass `-1` to query all users |
| name | User name | String | N | If omitted, name filter is not applied |
| startTime | Start time | Int | N | Omit if not filtering by time; otherwise Unix timestamp |
| endTime | End time | Int | N | Omit if not filtering by time; otherwise Unix timestamp |
| page | Page index | Int | Y | With images: (0, 50]; without images: (0, 1000] |
| size | Page size | Int | Y | Zero-based |

Request example:

```json
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"time": 0,
	"sign": "",
	"data": {
		"userId": ["001","002"],
		"name": "",
		"startTime": -1,
		"endTime": -1,
		"page": 0,
		"size": 100
	}
}
```

- Device reply to backend or application

| Message topic | topic: access_device/v2/cmd/getRecords_reply |
| --------- | -------------------------------------------- |

`data` fields

Query response `data` parameters

| Parameter | Description | Type | Required | Notes                                     |
| --------- | ---------------- | ----- | ---- | -------------------------------------------- |
| page | Current page | Int | Y | Current page index |
| size | Page size | Int | Y | Items per page |
| total | Total count | Int | Y | Total records |
| totalPage | Total pages | Int | Y | Total page count |
| count | Result count | Int | Y | Length of `content` array (≤ `size`) |
| content | Record array | Array | Y | See content table                       |

content fields

| Parameter | Description | Type | Required | Notes                                                     |
| --------- | ---------------------------- | ------ | ---- | ------------------------------------------------------------ |
| recordId | Access record ID | String | Y | Unique access record ID |
| userId | User ID | String | Y | |
| type | Credential type | Int | Y | See Appendix 3. Combined face+card: `301`; face+QR: `302` |
| timeStamp | Access timestamp | Int | Y | |
| result | Access result | Int | Y | `0` = success; non-zero = failure |
| name | User name | String | N | |
| code | Photo/card/QR/password/BLE | String | Y/N | Types 300/301/302: see spec; others: Base64 photo or credential value |
| extra | Extra data | Object | N | For combined face+card/QR: card or QR value; may include temperature |
| error | Error message | String | N | |

extra table

| Parameter | Description | Type | Required | Notes                        |
| ----------- | ---------------------------- | ------ | ---- | ------------------------------- |
| temperature | Body temperature | Float | N | |
| code | Card/QR value | String | N | For combined face+card/QR verification |

Response example

```json
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"result": 0,
	"code": "000000",
	"message": "success",
	"data": {
		"index": 0,
		"length": 100,
		"total": 3,
		"totalPage": 1,
		"size": 3,
		"content": [{
			"recordId": "6w8keif5g6",
			"userId": "100002",
			"name": "Chang Yongbin",
			"timeStamp": 1639475284,
			"code": "xxx"
		},
		{
			"recordId": "6w8keif5g7",
			"userId": "100002",
			"name": "Chang Yongbin",
			"timeStamp": 1639475288,
			"code": "XXXX"
		},
		{
			"recordId": "6w8keif5g8",
			"userId": "100002",
			"name": "Chang Yongbin",
			"timeStamp": 1639475291,
			"code": "XXX"
		}]
	}
}
```

#### 8.2 Delete Recognition Records

- Backend or application to device

| Message topic | topic: access_device/v2/cmd/{#uuid}/delRecords |
| --------- | ---------------------------------------------- |

`data` parameters

| Parameter | Description | Type | Required | Notes                                                     |
| --------- | ---------- | ----- | ---- | ------------------------------------------------------------ |
| recordId | Access record IDs | array | N | Unique access record IDs |
| userId | User IDs | array | N | |
| startTime | Start time | Int | N | If > 0, delete records after this time; if ≤ 0 or omitted, delete all (with other filters) |
| endTime | End time | Int | N | If > 0, delete records before this time; if ≤ 0 or omitted, delete all (with other filters) |

Request example

```json
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"time": 0,
	"sign": "",
	"data": {
		"recordId": ["6w8keif5g8"]
	}
}
```

- Device reply to backend or application

| Message topic | topic: access_device/v2/cmd/delRecords_reply |
| --------- | -------------------------------------------- |

Response example

```json
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"time": 0,
    "sign": "",
	"code": "000000",
	"message": "success"
}
```

####

#### 8.3 Access Record Upload

- Device to backend or application

| Message topic | topic: `access_device/v2/event/access` |
| --------- | ------------------------------------ |

Response parameters

`data` parameters

| Parameter | Description | Type | Required | Notes                                                     |
| --------- | ---------------------------- | ------ | ---- | ------------------------------------------------------------ |
| userId | User ID | String | Y | |
| type | Credential type | Int | Y | See Appendix 3. Combined face+card: `301`; face+QR: `302` |
| timeStamp | Access timestamp | Int | Y | |
| result | Access result | Int | Y | `0` = success; non-zero = failure |
| name | User name | String | N | |
| code | Photo/card/QR/password/BLE | String | Y/N | Types 300/301/302: see spec; others: Base64 photo or credential value |
| extra | Extra data | Object | N | For combined face+card/QR: card or QR value |
| error | Error message | String | N | |

extra table

| Parameter | Description | Type | Required | Notes                        |
| ------ | ---------------------------- | ------ | ---- | ------------------------------- |
| code | Card/QR value | String | N | For combined face+card/QR verification |

Request example:

```json
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"time": 0,
	"sign": "",
	"data": [{
		"userId": "412725202101011234",
		"type": 500,
		"timeStamp": 1639475284,
		"result": 0,
		"error": "success",
		"name": "Zhang San",
		"code": "XXXX",
		"extra": {
			"code": "XXXX"
		}
	}]
}
```

- Backend or application reply to device

| Message topic | topic: access_device/v2/event/{#uuid}/access_reply |
| --------- | -------------------------------------------------- |

Response example

```json
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"code": "000000",
	"message": "success"
}
```

## Appendix 1 Code Reference
<a id="appendix-1-code-reference"></a>

| Category | code | Message | Description |
| -------- | ------------- | ---------------------- | ---------------------------------------------------------- |
| Success | 000000 | Command executed successfully | None |
| General error | 100000 | Unknown error | None |
| General error | 100001 | Device disabled | Many commands are blocked when the device is disabled |
| General error | 100002 | Device busy, try again later | Device is upgrading, configuring network, or busy |
| General error | 100003 | Signature verification failed | None |
| General error | 100004 | Timeout | None |
| General error | 100005 | Device offline | None |
| Parameter error | 200000-299999 | Invalid parameters | Per-command parameter rules in each API section |
| Other error | 300000-399999 | Other known errors | Per-command error details in each API section |

## Appendix 2 Device Alarm Types
<a id="appendix-2-device-alarm-types"></a>

| Type | type | value | door |
| -------- | ---- | -------------------- | ------------ |
| Door sensor | 0 | `0`: open, `1`: closed | Door index |

## Appendix 3 Credential Types
<a id="appendix-3-credential-types"></a>

| type | num | Description |
| ----------- | ------------- | ------------------------------------------------------------ |
| Finger | 500 | Fingerprint |
| qrcode | 100, 101, 103 | `100`: passthrough QR; `101`: static QR; `103`: dynamic QR |
| password | 400 | Password (6 digits) |
| card | 200 | `200`: plain card; `201`: CPU encrypted card; `202`: sector encrypted card (send uppercase card number; lowercase is stored as uppercase) |

## Appendix 4 Time Window
<a id="appendix-4-time-window"></a>

Four time window modes are supported:

- 1. Default: no time limit, always valid

```json
{
    "type": 0
}
```

- 2. Range mode: valid between start and end

```json
{
    "type": 1,
    "range": {
      "beginTime": 1640917147,
      "endTime": 1690917147
    }
}
```

- 3. Daily mode: valid only during specified periods each day (non-overlapping, max 5 periods). `dayPeriodTime` format: `"HH:MM-HH:MM"` (24-hour). Example: `"08:00-09:30|10:00-11:30"`. `"00:00-24:00"` means all day. Separate periods with `|` (no spaces). Max 5 periods per day.

```json
{
	"type": 2,
	"dayPeriodTime": "12:00-13:30|15:00-16:30",
	"range": {
		"beginTime": 1640917147,
		"endTime": 1690917147
	}
}
```

- 4. Weekly repeat mode: valid on selected weekdays during specified periods (max 5 per day, non-overlapping). `weekPeriodTime` keys `1`–`7` (Mon–Sun); at least one day required. Same time format as daily mode.

```json
{
    "type": 3,
    "weekPeriodTime":{
      "1":"9:00-10:00",
      "2":"12:00-13:30|15:00-16:30"
    },
    "range": {
      "beginTime": 1640917147,
      "endTime": 1690917147
    }
}
```

## 9. Revision History

| Version | Date | Author | APIs affected | Changes |
| ------- | ---------- | ------ | ------------------------------ | ------------------------------------------------------------ |
| V1.0.15 | 2025-11-20 | Ma Zhixiang | Initial document | - |