Access control standard MQTT protocol document

# MQTT Protocol Documentation

## 1. Overview

This document provides a set of standard interfaces for facial recognition devices, used to push and acquire device information. After purchasing the device, users can directly perform custom development for a complete access control or related application system based on these interface specifications. The interfaces use the MQTT communication protocol, which can connect with various general MQTT brokers, or you can use our recommended MQTT broker.

**Document Version: V2**

#### Application Scenarios

When you need to integrate with your own business system, you can communicate directly with the device via the MQTT protocol using these interfaces.

#### Interface Specifications

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

- **Uplink (Upstream):** Refers to the device sending messages to the backend or application.
- **Downlink (Downstream):** Refers to the backend or application sending messages to the device.

Communication goes through an MQTT broker. A message contains a message topic and message content, formatted as follows:

1. **Message Topic**

> Message title. Whether it is uplink or downlink, the rule for sending commands and returning commands is "command" and "command_reply". The format is as follows:

- **Downlink:** `access_device/v2/cmd/{#device_sn}/xxxx`, corresponding return command (Uplink): `access_device/v2/cmd/xxxx_reply`
- **Uplink:** `access_device/v2/event/yyyy`, corresponding return command (Downlink): `access_device/v2/event/{#device_sn}/yyyy_reply`

*Note: `access_device/v2` is a specific identifier for the interface version. `cmd` indicates that the backend or application actively sends commands to the device. `event` indicates that the device actively sends messages or triggers events to the backend or application.*

1. **Message Content**

The message content is in text format, specifically JSON.

a) Sending Message

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

b) Return Message

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

| **Parameter** | **Description**   | **Type** | **Required** | **Remarks**                                                  |
| ------------- | ----------------- | -------- | ------------ | ------------------------------------------------------------ |
| serialNo      | Serial Number     | string   | Yes          | The backend or app must pass a unique serial number (up to 32 chars) when sending a message. The device will use the same serialNo when returning the result. Vice versa. |
| uuid          | Device Unique ID  | string   | Yes          | String longer than 8 characters.                             |
| data          | Message Body      | object   | Yes          | JSON format. The format varies for different message types. Details are listed in the interface sections. |
| time          | Timestamp         | long     | Yes          | 10-digit timestamp, in seconds.                              |
| sign          | Message Signature | string   | No           | If signature validation is enabled, this value is required to verify data legitimacy. For rules, refer to Appendix - [Signature Algorithm]. |
| code          | Result Code       | string   | No           | Return data must include a `code`. Different codes indicate different results. Refer to [Appendix Table 1](https://gemini.google.com/app/d6f4564b6aa19f74#appendix-table-1-code-overview) for details. |

**Note:** Every item in the message content should start with a lowercase letter (camelCase).

## 2. Device Management and Event Interfaces

#### 2.1 Query Configuration

- **Backend/App to Device**

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

Data Parameter Description:

| **Parameter** | **Type** | **Required** | **Remarks**                 |
| ------------- | -------- | ------------ | --------------------------- |
| data          | array    | Yes          | Configuration info to query |

Send Example:

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

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

- **Device feedback to Backend/App**

| **Message Topic** | **topic: access_device/v2/cmd/getConfig_reply** |
| ----------------- | ----------------------------------------------- |
|                   |                                                 |

Data Parameters:

| **Parameter** | **Description** | **Type** | **Required** | **Remarks** |
| ------------- | --------------- | -------- | ------------ | ----------- |
| data          | Config Data     | Object   | Yes          | See example |

Return Example:

```
{
	"serialNo": "6w8keif5g6",
	"uuid": "e4720000964b5c00",
	"code": "000000",
    "time": 1701061767,
    "sign": "",
	"message": "success",
	"data": {
		"nfc": {
			"nfcEn": 1,
			"nfcFt": 0,
			"nfcOrd": 0,
			"nfcAffixesFt": 1,
			"nfcPrefix": "",
			"nfcPostfix": "",
			"nfcCr": 0,
			"nfcNl": 0,
			"nfcReadIdNum": 0
		}
	}
}
```

#### 2.2 Modify Configuration

- **Backend/App to Device**

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

Data Parameter Description:

| **Parameter** | **Description** | **Type** | **Required** | **Remarks**                                                  |
| ------------- | --------------- | -------- | ------------ | ------------------------------------------------------------ |
| data          | Config Data     | Object   | No           | Configuration set. Can be empty or omitted, in which case the device makes no changes. |

Optional parameters for Device Configuration data field

- Note: Configurations use a two-level grouping format. Each level field uses camelCase starting with a lowercase letter.
- For details, refer to the VF105 Access Control Standard Configuration Document.

Send Example:

```
{
    "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 feedback to Backend/App**

| **Message Topic** | **topic: access_device/v2/cmd/setConfig_reply** |
| ----------------- | ----------------------------------------------- |
|                   |                                                 |

Message Parameter Description:

| **Parameter** | **Description** | **Type** | **Required** | **Remarks**                         |
| ------------- | --------------- | -------- | ------------ | ----------------------------------- |
| data          | Config Data     | Object   | Yes          | Result set of configuration changes |

Return Example:

```
{
	"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 Device Upgrade

- **Backend/App to Device**

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

Data Parameters:

| **Parameter** | **Description**  | **Type** | **Required** | **Remarks**                                                  |
| ------------- | ---------------- | -------- | ------------ | ------------------------------------------------------------ |
| type          | Package Type     | Int      | Yes          | `0`: Local upgrade, `10`: Resource upgrade (Not supported in current version) |
| url           | OTA Download URL | String   | Yes          | The device accesses this URL. If accessible, download begins. If not, an error is returned. Successful download doesn't mean successful installation; check the UI. |
| md5           | Package MD5      | string   | Yes          | MD5 validation for the upgrade package.                      |
| extra         | Extended Field   | Object   | Yes          |                                                              |

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

| **Parameter**   | **Description** | **Type** | **Required** | **Remarks** |
| --------------- | --------------- | -------- | ------------ | ----------- |
| bg Image, Audio | File Name       | String   | No           | File name   |

Send Example:

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

- **Device feedback to Backend/App**

| **Message Topic** | **topic: access_device/v2/cmd/upgradeFirmware_reply** |
| ----------------- | ----------------------------------------------------- |
|                   |                                                       |

Return Example:

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

#### 2.4 Remote Control

- **Backend/App to Device**

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

Data Parameters:

| **Parameter** | **Description** | **Type** | **Required** | **Remarks**                                                  |
| ------------- | --------------- | -------- | ------------ | ------------------------------------------------------------ |
| command       | Command         | Int      | Yes          | `0`: Reboot, `1`: Remote Door Open, `4`: Device Reset`5`: Play Audio, `6`: Show Image, `7`: Show Text`8`: Remote Face Capture`9`: Log`10`: Issue Mini-program Code`11`: WeCom (Internal API only)`13`: Change Screensaver Image(Currently only supports 0, 1, 4, 8, 13) |
| extra         | Extended Field  | String   | Yes          | See the extra extension table                                |

Extra Extension Table:

| **Parameter**   | **Description**   | **Type** | **Required** | **Remarks**                                                  |
| --------------- | ----------------- | -------- | ------------ | ------------------------------------------------------------ |
| wav             | Audio filename    | String   | No           | Passed when `command=5`. Plays specified audio. Files uploaded via firmware upgrade. |
| image           | Image filename    | String   | No           | Passed when `command=6`. Shows specified image on screen. Files uploaded via firmware upgrade. |
| timeout         | Display Time      | Int      | No           | Passed when `command=6`. Unit: `ms`. Default if absent: `1500ms`. |
| msg             | Prompt Msg        | String   | No           | Passed when `command=7`. Pops up specified message on screen. |
| timeout         | Prompt Time       | Int      | No           | Passed when `command=7`. Unit: `ms`. UI display time for `msg`. Default: `1500ms`. |
| log             | Log Command       | Int      | No           | Passed when `command=9`. `0`: Get device log (Max 10K clear text), `1`: Clear log. |
| qrCodeBase64    | Mini-program Code | String   | No           | Passed when `command=10`.                                    |
| keyId           | Credential ID     | String   | No           | Passed when `command=8` (Remote capture).                    |
| weComStatus     | WeCom Status      | Int      | No           | Passed when `command=11`. `0`: Unbound, `1`: Bound (Internal API only). |
| WeComBindQr     | WeCom Bind Code   | Int      | No           | Passed when `command=11` and `weComStatus=0`. Used for bind UI (Internal API only). |
| wallpaperBase64 | Screensaver Image | String   | No           | Passed when `command=13`. Pass an 800*1280 base64 image.     |

Send Example:

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

// Face Capture
{
    "serialNo": "0000000001",
    "uuid": "e4720000964b5c00",
    "time": 0,
    "sign": "",
    "data": {
        "command": 8,
        "extra": {
            "keyId": "12345678"
        }
    }
}

// WeCom (Internal)
{
    "serialNo": "0000000001",
    "uuid": "e4720000964b5c00",
    "time": 0,
    "sign": "",
    "data": {
        "command": 11,
        "extra": {
            "weComStatus": 0,
            "WeComBindQr": "[https://open.work.weixin.qq.com/connect/hardware?hw_code=](https://open.work.weixin.qq.com/connect/hardware?hw_code=)..."
        }
    }
}
```

- **Device feedback to Backend/App**

| **Message Topic** | **topic: access_device/v2/cmd/control_reply** |
| ----------------- | --------------------------------------------- |
|                   |                                               |

Data Parameters:

| **Parameter** | **Description**          | **Type** | **Required** | **Remarks**                                        |
| ------------- | ------------------------ | -------- | ------------ | -------------------------------------------------- |
| faceBase64    | Captured Face JPG Base64 | String   | No           | Returned when `command=8`                          |
| keyId         | Credential ID            | String   | No           | Returned when `command=8`, matches the input value |

Return Example:

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

// Face Capture Return
{
    "serialNo": "0000000001",
    "uuid": "e4720000964b5c00",
    "time": 0,
    "sign": "",
    "code": "000000",
    "data": {
        "faceBase64": "/9j/4AAQSkZJRgABAQAAAQABAAD/2wBDAAIBAQEBA/......2Q==",
        "keyId": "12345678"
    },
    "message": "success"
}
```

#### 2.5 Alarm

- **Device to Backend/App**

| **Message Topic** | **topic: access_device/v2/event/alarm** |
| ----------------- | --------------------------------------- |
|                   |                                         |

Data Parameters:

| **Parameter** | **Description** | **Type** | **Required** | **Remarks**                                                  |
| ------------- | --------------- | -------- | ------------ | ------------------------------------------------------------ |
| type          | Report Type     | Int      | Yes          | Refer to [Appendix Table 2 Device Alarm Types](https://gemini.google.com/app/d6f4564b6aa19f74#appendix-table-2-device-alarm-types) |
| value         | Report Status   | String   | No           |                                                              |

Send Example:

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

- **Backend/App feedback to Device**

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

Return Example:

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

#### 2.6 Heartbeat

- **Device to Backend/App**

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

Send Example:

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

- **Backend/App feedback to Device (No reply needed)**

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

#### 2.7 Last Will (Offline)

- **Device to Backend/App**

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

Send Example:

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

#### 2.8 Connection Report

- **Device to Backend/App**

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

Data Parameters:

| **Parameter** | **Description**     | **Type** | **Required** | **Remarks**                       |
| ------------- | ------------------- | -------- | ------------ | --------------------------------- |
| appVersion    | Application Version | String   | Yes          | Application version number        |
| btMac         | Bluetooth MAC       | String   | Yes          | Bluetooth MAC address             |
| mac           | Device Hardware ID  | String   | No           | Device hardware unique identifier |
| clientId      | Client ID           | String   | Yes          | Default matches device address    |
| type          | Network Type        | Int      | Yes          | `0`: Ethernet, `1`: WIFI, `2`: 4G |
| ssid          | WIFI SSID           | String   | Yes          | WIFI Name                         |
| pwd           | WIFI Password       | String   | Yes          | WIFI Password                     |
| dhcp          | DHCP Mode           | Int      | Yes          | `1`: Dynamic, `0`: Static         |
| ip            | IP Address          | String   | Yes          | IP address                        |
| gateway       | Gateway             | String   | Yes          | Gateway                           |
| dns           | DNS Server          | String   | Yes          | DNS server                        |
| subnetMask    | Subnet Mask         | String   | Yes          | Subnet mask                       |
| netMac        | Network Card MAC    | String   | Yes          | Network card MAC                  |

Send Example:

```
{
  "serialNo": "0000000001",
  "uuid": "e4720000964b5c00",
  "time": 1737364204,
  "data": {
    "appVersion": "vf203_v11_reader_1.0.0",
    "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/App feedback to Device (No reply needed)**

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

#### 2.9 Online Verification

- **Device to Backend/App**

| **Message Topic** | **topic: access_device/v2/event/access_online** |
| ----------------- | ----------------------------------------------- |
|                   |                                                 |

Data Parameters:

| **Parameter** | **Description**    | **Type** | **Required** | **Remarks**                                                  |
| ------------- | ------------------ | -------- | ------------ | ------------------------------------------------------------ |
| code          | Access Credential  | String   | Yes          | Empty if it's facial recognition                             |
| type          | Credential Type    | Int      | Yes          | Refer to Appendix Table 3 - `num` column                     |
| index         | Door Control Index | String   | No           | e.g., if one device controls four doors, index might be 1, 2, 3, 4. Can be empty. |
| time          | Access Time        | Long     | Yes          | Timestamp in seconds                                         |
| extra         | Extra Parameters   | Object   | No           | Extensible, usually stores raw data like the original QR code string. |
| srcData       | Source Data        | String   | No           | Raw data                                                     |

Send Example:

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

- **Backend/App feedback to Device**

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

Return Example:

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

#### 2.10 Enterprise WeChat / WeCom (Internal API only)

- **Device to Backend/App**

| **Message Topic** | **topic: access_device/v2/event/wecom** |
| ----------------- | --------------------------------------- |
|                   |                                         |

Data Parameters:

| **Parameter** | **Description**  | **Type** | **Required** | **Remarks**                     |
| ------------- | ---------------- | -------- | ------------ | ------------------------------- |
| type          | Business Type    | Int      | Yes          | `0`: Query WeCom binding status |
| extra         | Extra Parameters | Object   | No           | Extensible                      |

Send Example:

```
{
    "serialNo": "0000000001",
    "uuid": "e4720000964b5c00",
    "data": {
        "type": 0
    },
    "time": 1647580466,
    "sign": ""
}
```

- **Backend/App feedback to Device**

| **Message Topic** | **topic: access_device/v2/event/{#uuid}/wecom_reply** |
| ----------------- | ----------------------------------------------------- |
|                   |                                                       |

Data Parameters:

| **Parameter** | **Description**                       | **Type** | **Required** | **Remarks**                              |
| ------------- | ------------------------------------- | -------- | ------------ | ---------------------------------------- |
| status        | WeCom Status (Required when `type=0`) | Int      | No           | `0`: Unbound, `1`: Bound                 |
| bindQr        | WeCom Bind QR                         | String   | No           | Required if unbound, shown on device UI. |

Return Example:

```
{
    "serialNo": "0000000001",
    "uuid": "e4720000964b5c00",
    "time": 1647580466,
    "sign": "",
    "code": "000000",
    "data": {
        "status": 0,
        "bindQr": "[https://open.work.weixin.qq.com/connect/hardware?hw_code=ZxjdiTaAJ6tX702PJg1z1e_iAdM_WH7r-qYUWMBIJJY](https://open.work.weixin.qq.com/connect/hardware?hw_code=ZxjdiTaAJ6tX702PJg1z1e_iAdM_WH7r-qYUWMBIJJY)"
    },
    "message": "success"
}
```

## 3. Workflow for Issuing Passable Personnel

#### 3.1 Flowchart Example

```
flowchart TD
 A([Start])
 B[Prepare User Data]
 C[Issue User insertUser]
 D{Wait for Reply insertUser_reply}
 E[User Stored]
 F[Record Failed Batch]
 G[Prepare Face Credential]
 H[Issue Face Credential insertKey]
 I{Wait for Reply insertKey_reply}
 J[Face Stored]
 K[Record Failed Batch]
 L[Prepare Permission Data]
 M[Issue Permission insertPermission]
 N{Wait for Reply insertPermission_reply}
 O[Permission Issued]
 P[Record Failed Batch]
 Q([Finish])

#### 3.2 Workflow Description

- The Add User and Add Credential interfaces are linked via the `userId` field. The Add User and Add Permission interfaces are linked via the `permissionIds` field.
- To register a face | QR Code | Card, you must pass the identical `userId` in both Add User and Add Credential interfaces, and pass the identical `permissionIds` in Add Permission as in Add User. All three interfaces must be called.
- There is no strict order for calling the Add User, Add Credential, and Add Permission interfaces. The device does not check if `userId` and `permissionIds` are problematic or associated immediately. However, the recommended order is Add User -> Add Credential -> Add Permission.
- In Add User, `userId` is the primary key. Make sure it is unique during batch issuing; otherwise, user data with the same `userId` will be updated. The `permissionIds` in the payload must strictly correspond to the `permissionId` in the Add Permission interface.
- In Add Credential, `keyId` is the primary key. Make sure it is unique during batch issuing; otherwise, credential data with the same `keyId` will be updated. The `userId` must strictly correspond to the `userId` in the previously added user.
- In Add Permission, `permissionId` is the primary key. Make sure it is unique during batch issuing; otherwise, data with the same `permissionId` will be updated.
- It is not recommended to use the exact same value for `userId`, `keyId`, and `permissionId` for the same person. Doing so requires special handling if a single person has multiple QR codes, cards, or permissions. It is recommended to use different values for these three IDs and map them accordingly.

## 4. User Management Interfaces

#### 4.1 Add User

- **Backend/App to Device**

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

Data Parameters (Limit up to 100 per request):

| **Parameter** | **Description** | **Type** | **Required** | **Remarks**                                                  |
| ------------- | --------------- | -------- | ------------ | ------------------------------------------------------------ |
| userId        | User ID         | String   | Yes          | Unique, no duplicates. Alphanumeric only, up to 128 bytes. E.g. SW200 |
| name          | User Name       | String   | Yes          | Must not be empty. Up to 128 bytes.                          |
| permissionIds | Permission ID   | Array    | Yes          | Maps user to permissions. Corresponds to `permissionId` in Issue Permission. |
| extra         | Extra Params    | Object   | No           | Other user attributes.                                       |

- When issuing a user with a `userId` that already exists on the device, the device will automatically update all information for that user based on the `userId`.

Send Example:

```
{
	"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 feedback to Backend/App**

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

- Common `data` field description (Exists only on failure):

| **Parameter** | **Description** | **Type** | **Remarks**                                     |
| ------------- | --------------- | -------- | ----------------------------------------------- |
| userId        | User ID         | String   | The failed `userId`                             |
| errmsg        | Error Msg       | String   | Specific error reason, such as parsing failure. |

Return Success Example:

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

Return Failure Example:

```
{
    "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/App to Device**

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

Data Parameters:

| **Parameter** | **Description** | **Type** | **Required** | **Remarks**             |
| ------------- | --------------- | -------- | ------------ | ----------------------- |
| data          | User ID list    | array    | Yes          | Each item is a `userId` |

Send Example:

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

- **Device feedback to Backend/App**

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

- Common `data` field description (Exists only on failure):

| **Parameter** | **Description** | **Type** | **Remarks**                                     |
| ------------- | --------------- | -------- | ----------------------------------------------- |
| userId        | User ID         | String   | The failed `userId`                             |
| errmsg        | Error Msg       | String   | Specific error reason, such as parsing failure. |

Return Success Example:

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

Return Failure Example:

```
{
    "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 Users

- **Backend/App to Device**

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

Send Example:

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

- **Device feedback to Backend/App**

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

Return Example:

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

#### 4.4 Query Users

- **Backend/App to Device**

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

Data Parameters:

| **Parameter** | **Description**    | **Type** | **Required** | **Remarks**                               |
| ------------- | ------------------ | -------- | ------------ | ----------------------------------------- |
| userId        | User ID            | String   | No           | Query info of a specified user.           |
| name          | User Name          | String   | No           | If empty, query isn't restricted by name. |
| size          | Max items per page | int      | Yes          | Range: (0, 100]                           |
| page          | Page Number        | int      | Yes          | Starts from 0.                            |

Send Example:

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

- **Device feedback to Backend/App**

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

User Query Data Parameters:

| **Parameter** | **Description** | **Type** | **Required** | **Remarks** |
| ------------- | ------------------ | -------- | ------------ | ---------------------------------------- |
| page | Current page | Int | Yes | Current page |
| size | Page size | Int | Yes | Current page size |
| total | Total records | Int | Yes | Total records |
| totalPage | Total pages | Int | Yes | Total pages |
| count | Query result count | Int | Yes | Array length, <= size. (e.g., last page) |
| content | User Array | Array | Yes | See `<content data>` below |

Content Data:

| **Parameter** | **Description** | **Type** | **Required** | **Remarks**          |
| ------------- | --------------- | -------- | ------------ | -------------------- |
| userId        | User ID         | String   | Yes          |                      |
| name          | User Name       | String   | Yes          |                      |
| permissionIds | Permission ID   | Array    | Yes          |                      |
| extra         | Extra fields    | Object   | Yes          | Refer to extra table |

Extra Table:

| **Parameter** | **Description** | **Type** | **Required** | **Remarks** |
| ------------- | --------------- | -------- | ------------ | ----------- |
| userType      | User Type       | Int      | Yes          |             |
| addSrc        | Reg Source      | Int      | Yes          |             |
| addTime       | Reg Time        | Int      | Yes          |             |

Return Example:

```
// Query Success:
{
	"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
			}
		}]
	}
}

// No registered user:
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"code": "C00001",
	"time": 1754032816,
	"sign": "",
	"message": "selectUser: no data as this select condition"
}
```

#### 4.5 Modify User

- **Backend/App to Device**

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

Data Parameters (Limit up to 100 per request):

| **Parameter** | **Description** | **Type** | **Required** | **Remarks**                                                |
| ------------- | --------------- | -------- | ------------ | ---------------------------------------------------------- |
| userId        | User ID         | String   | Yes          | Unique, no duplicates. Alphanumeric only, up to 128 bytes. |
| name          | User Name       | String   | No           | Must not be empty if passed. Up to 128 bytes.              |
| permissionIds | Permission ID   | Array    | No           | Maps user to permissions.                                  |
| extra         | Extra Params    | Object   | No           | Other user attributes.                                     |

- Can only modify information for users whose `userId` already exists on the device.

Send Example:

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

- **Device feedback to Backend/App**

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

- Common `data` field description (Exists only on failure):

| **Parameter** | **Description** | **Type** | **Remarks**            |
| ------------- | --------------- | -------- | ---------------------- |
| userId        | User ID         | String   | The failed `userId`    |
| errmsg        | Error Msg       | String   | Specific error reason. |

Return Success Example:

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

Return Failure Example:

```
{
    "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 Interfaces

#### 5.1 Add Credential

- **Backend/App to Device**

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

Data Parameters (Limit up to 100 per request):

| **Parameter** | **Required** | **Type** | **Description** | **Remarks**                                   |
| ------------- | ------------ | -------- | --------------- | --------------------------------------------- |
| keyId         | Yes          | String   | Credential ID   | Unique ID for the credential                  |
| userId        | Yes          | String   | User ID         | Unique ID for the user                        |
| type          | Yes          | String   | Credential Type | Refer to Appendix Table 3 - `num` column      |
| code          | Yes          | String   | Credential Data | Base64 of the JPG image if facial recognition |
| extra         | No           | Object   | Extra Params    | Other credential attributes                   |

Extra Table:

| **Parameter** | **Description** | **Type** | **Required** | **Remarks**                                                  |
| ------------- | --------------- | -------- | ------------ | ------------------------------------------------------------ |
| faceType      | Reg Face Type   | String   | Yes          | `0`: base64, `1`: feature value, `2`: URL download (Not supported), `3`: zip package (Not supported). (Face types must be issued in batches of the same type, and cannot be mixed with other credential types in the same payload). |

- The `userId` must match the `userId` in "Add User".
- When issuing a credential with a `keyId` that already exists, the device will auto-update it based on `keyId`.
- The device processes the batch sequentially; if any credential fails, it records the failure, and returns all failure records together once the whole batch finishes processing.

Send Example:

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

- **Device feedback to Backend/App**

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

- Common `data` field description (Exists only on failure):

| **Parameter** | **Description** | **Type** | **Remarks**            |
| ------------- | --------------- | -------- | ---------------------- |
| keyId         | Credential ID   | String   | The failed `keyId`     |
| errmsg        | Error Msg       | String   | Specific error reason. |

Return Success Example:

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

Return Failure Example:

```
{
    "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 Credential

- **Backend/App to Device**

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

Data Parameters:

| **Parameter** | **Description** | **Type** | **Required** | **Remarks**                                               |
| ------------- | --------------- | -------- | ------------ | --------------------------------------------------------- |
| keyId         | Credential ID   | String   | No           | Unique ID for the credential                              |
| userId        | User ID         | String   | No           | Unique ID for the user                                    |
| type          | Query by type   | int      | No           | Refer to Appendix Table 3 - `num` column                  |
| size          | Page size       | int      | Yes          | Range: (0, 100]                                           |
| page          | Page Number     | int      | Yes          | Starts from 0. Input index must be less than total pages. |

Send Example:

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

- **Device feedback to Backend/App**

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

Query Data Parameters:

| **Parameter** | **Description** | **Type** | **Required** | **Remarks** |
| ------------- | ------------------ | -------- | ------------ | -------------------------- |
| page | Current page | Int | Yes | Current page |
| size | Page size | Int | Yes | Current page size |
| total | Total records | Int | Yes | Total records |
| totalPage | Total pages | Int | Yes | Total pages |
| count | Query result count | Int | Yes | Array length, <= size. |
| content | Credential Array | Array | Yes | See `<content data>` below |

Content Data:

| **Parameter** | **Required** | **Type** | **Description** | **Remarks**                              |
| ------------- | ------------ | -------- | --------------- | ---------------------------------------- |
| keyId         | Yes          | String   | Credential ID   | Unique ID for the credential             |
| userId        | Yes          | String   | User ID         | Unique ID for the user                   |
| type          | Yes          | int      | Credential Type | Refer to Appendix Table 3 - `num` column |
| code          | Yes          | String   | Credential Data | Base64 if facial recognition             |
| extra         | No           | Object   | Extra Params    | Other credential attributes              |

Return Example:

```
{
	"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 Value",
            	"extra": {
					"xxxx": "xxx"
                }
			},
			{
				"keyId": "100002",
                "userId": "12",
				"type": "",
				"code": "QR Code Value"
			}
		]
	}
}
```

#### 5.3 Delete Credential

- **Backend/App to Device**

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

Data Parameters:

| **Parameter** | **Required** | **Type** | **Required** | **Remarks**         |
| ------------- | ------------ | -------- | ------------ | ------------------- |
| keyIds        | No           | array    | No           | Credential ID array |
| userIds       | No           | array    | No           | User ID array       |

- It is allowed to pass both `keyIds` and `userIds` simultaneously. Deleting a non-existent credential or repeatedly deleting will not cause an error.

Send Example:

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

- **Device feedback to Backend/App**

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

- Common `data` field description (Exists only on failure):

| **Parameter** | **Description** | **Type** | **Remarks**            |
| ------------- | --------------- | -------- | ---------------------- |
| keyId         | Credential ID   | String   | The failed `keyId`     |
| errmsg        | Error Msg       | String   | Specific error reason. |

Return Example:

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

Return Failure Example:

```
{
    "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 Credentials

- **Backend/App to Device**

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

Send Example:

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

- **Device feedback to Backend/App**

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

Return Example:

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

#### 5.5 Modify Credential

- **Backend/App to Device**

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

Data Parameters (Limit up to 100 per request):

| **Parameter** | **Required** | **Type** | **Description** | **Remarks**                                                  |
| ------------- | ------------ | -------- | --------------- | ------------------------------------------------------------ |
| keyId         | Yes          | String   | Credential ID   | Unique ID for the credential                                 |
| userId        | No           | String   | User ID         | Unique ID for the user                                       |
| type          | No           | int      | Credential Type | Refer to Appendix Table 3 - `num` column                     |
| code          | No           | String   | Credential Data | Base64 if facial recognition. Face types only support single payload issuance, and cannot be mixed with other types. |
| extra         | No           | Object   | Extra Params    | Other credential attributes                                  |

Extra Table:

| **Parameter** | **Description** | **Type** | **Required** | **Remarks**                                                  |
| ------------- | --------------- | -------- | ------------ | ------------------------------------------------------------ |
| faceType      | Reg Face Type   | String   | Yes          | `0`: base64, `1`: feature value, `2`: URL download, `3`: zip package |

- When modifying `userId`, ensure that the `userId` actually exists in User Management; otherwise, access will not work normally.
- Can only modify information for credentials whose `keyId` already exists.

Send Example:

```
{
    "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 feedback to Backend/App**

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

- Common `data` field description (Exists only on failure):

| **Parameter** | **Description** | **Type** | **Remarks**            |
| ------------- | --------------- | -------- | ---------------------- |
| keyId         | Credential ID   | String   | The failed `keyId`     |
| errmsg        | Error Msg       | String   | Specific error reason. |

Return Success Example:

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

Return Failure Example:

```
{
    "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 Interfaces

#### 6.1 Add Permission

- **Backend/App to Device**

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

Data Parameters (Limit up to 100 per request):

| **Parameter** | **Description** | **Type** | **Required** | **Remarks**                                                  |
| ------------- | --------------- | -------- | ------------ | ------------------------------------------------------------ |
| permissionId  | Permission ID   | String   | Yes          | Unique ID for permission. Used for adding and deleting. Recommend a 32-bit random value. |
| time          | Time Range      | Object   | No           | [See Time Range Description](https://gemini.google.com/app/d6f4564b6aa19f74#appendix-table-4-time-range-description) |
| extra         | Extra Params    | Object   | No           | Reserved, can be omitted                                     |

Send Example:

```
{
	"serialNo": "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 feedback to Backend/App**

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

- Common `data` field description (Exists only on failure):

| **Parameter** | **Description** | **Type** | **Remarks**               |
| ------------- | --------------- | -------- | ------------------------- |
| permissionId  | Permission ID   | String   | The failed `permissionId` |
| errmsg        | Error Msg       | String   | Specific error reason.    |

Return Success Example:

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

Return Failure Example:

```
{
    "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 Permission

- **Backend/App to Device**

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

Data Parameters:

| **Parameter** | **Description** | **Type** | **Required** | **Remarks**     |
| ------------- | --------------- | -------- | ------------ | --------------- |
| permissionId  | Permission ID   | String   | No           |                 |
| size          | Page size       | Int      | Yes          | Range: (0, 100] |
| page          | Page Number     | Int      | Yes          | Starts from 0.  |

Send Example:

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

- **Device feedback to Backend/App**

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

Query Data Parameters:

| **Parameter** | **Description** | **Type** | **Required** | **Remarks** |
| ------------- | ------------------ | -------- | ------------ | -------------------------- |
| page | Current page | Int | Yes | Current page |
| size | Page size | Int | Yes | Current page size |
| total | Total records | Int | Yes | Total records |
| totalPage | Total pages | Int | Yes | Total pages |
| count | Query result count | Int | Yes | Array length, <= size. |
| content | Permission Array | Array | Yes | See `<content data>` below |

Content Data:

| **Parameter** | **Description** | **Type** | **Required** | **Remarks**                                                  |
| ------------- | --------------- | -------- | ------------ | ------------------------------------------------------------ |
| permissionId  | Permission ID   | String   | Yes          |                                                              |
| time          | Time Range      | String   | Yes          | [See Time Range Description](https://gemini.google.com/app/d6f4564b6aa19f74#appendix-table-4-time-range-description) |
| extra         | Extra Fields    | Object   | No           |                                                              |

Return Example:

```
{
	"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/App to Device**

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

Data Parameters:

| **Parameter** | **Description** | **Type** | **Required** | **Remarks**              |
| ------------- | --------------- | -------- | ------------ | ------------------------ |
| permissionIds | Permission ID   | array    | No           | Unique ID for permission |

Send Example:

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

- **Device feedback to Backend/App**

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

- Common `data` field description (Exists only on failure):

| **Parameter** | **Description** | **Type** | **Remarks**               |
| ------------- | --------------- | -------- | ------------------------- |
| permissionId  | Permission ID   | String   | The failed `permissionId` |
| errmsg        | Error Msg       | String   | Specific error reason.    |

Return Success Example:

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

Return Failure Example:

```
{
    "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 Permissions

- **Backend/App to Device**

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

Send Example:

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

- **Device feedback to Backend/App**

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

Return Example:

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

#### 6.5 Modify Permission

- **Backend/App to Device**

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

Data Parameters (Limit up to 100 per request):

| **Parameter** | **Description** | **Type** | **Required** | **Remarks**                                                  |
| ------------- | --------------- | -------- | ------------ | ------------------------------------------------------------ |
| permissionId  | Permission ID   | String   | Yes          | Unique ID for permission                                     |
| time          | Time Range      | Object   | No           | [See Time Range Description](https://gemini.google.com/app/d6f4564b6aa19f74#appendix-table-4-time-range-description) |
| extra         | Extra Params    | Object   | No           | Reserved, can be omitted                                     |

Send Example:

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

- **Device feedback to Backend/App**

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

- Common `data` field description (Exists only on failure):

| **Parameter** | **Description** | **Type** | **Remarks**               |
| ------------- | --------------- | -------- | ------------------------- |
| permissionId  | Permission ID   | String   | The failed `permissionId` |
| errmsg        | Error Msg       | String   | Specific error reason.    |

Return Success Example:

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

Return Failure Example:

```
{
    "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 Interfaces

#### 7.1 Add Security Key

- **Backend/App to Device**

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

Data Parameters (Limit up to 100 per request):

| **Parameter** | **Description** | **Type** | **Required** | **Remarks**                                     |
| ------------- | --------------- | -------- | ------------ | ----------------------------------------------- |
| securityId    | Security ID     | String   | Yes          | Unique ID for the security key                  |
| type          | Key Type        | String   | Yes          | Key type, such as RSA, AES, etc.                |
| key           | Key Code        | String   | Yes          | Key code corresponding to the key, e.g., vguang |
| value         | Key Value       | String   | Yes          |                                                 |
| startTime     | Start Time      | Int      | Yes          | Valid from timestamp (seconds)                  |
| endTime       | Expire Time     | Int      | Yes          | Valid until timestamp (seconds)                 |

Send Example:

```
{
    "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 feedback to Backend/App**

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

Return Example:

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

#### 7.2 Query Security Key

- **Backend/App to Device**

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

Data Parameters:

| **Parameter** | **Description** | **Type** | **Required** | **Remarks**                      |
| ------------- | --------------- | -------- | ------------ | -------------------------------- |
| securityId    | Security ID     | String   | Yes          | Unique ID for the security key   |
| type          | Key Type        | String   | Yes          | Key type, such as RSA, AES, etc. |
| code          | Key Code        | String   | Yes          | Key code, e.g., vguang           |
| size          | Page size       | Int      | Yes          | Range: (0, 100]                  |
| page          | Page Number     | Int      | Yes          | Starts from 0.                   |

Send Example:

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

- **Device feedback to Backend/App**

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

Data Parameters:

| **Parameter** | **Description** | **Type** | **Required** | **Remarks** |
| ------------- | ------------------ | -------- | ------------ | -------------------------- |
| page | Current page | Int | Yes | Current page |
| size | Page size | Int | Yes | Current page size |
| total | Total records | Int | Yes | Total records |
| totalPage | Total pages | Int | Yes | Total pages |
| count | Query result count | Int | Yes | Array length, <= size. |
| content | Dynamic Code Array | Array | Yes | See `<content data>` below |

Content Data:

| **Parameter** | **Description** | **Type** | **Required** | **Remarks**                      |
| ------------- | --------------- | -------- | ------------ | -------------------------------- |
| type          | Key Type        | String   | Yes          | Key type, such as RSA, AES, etc. |
| code          | Key Code        | String   | Yes          | Key code                         |
| key           | Key Value       | String   | Yes          |                                  |
| startTime     | Start Time      | Int      | Yes          | Valid from timestamp (seconds)   |
| endTime       | Expire Time     | Int      | Yes          | Valid until timestamp (seconds)  |

Return Example:

```
{
	"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/App to Device**

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

Data Parameters:

| **Parameter** | **Description** | **Type** | **Required** | **Remarks**        |
| ------------- | --------------- | -------- | ------------ | ------------------ |
| data          | Security ID     | array    | Yes          | Each item is an ID |

Send Example:

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

- **Device feedback to Backend/App**

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

Return Example:

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

#### 7.4 Clear Security Keys

- **Backend/App to Device**

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

Send Example:

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

- **Device feedback to Backend/App**

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

Return Example:

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

## 8. Recognition Records

#### 8.1 Query Recognition Records

- **Backend/App to Device**

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

Data Parameters:

| **Parameter** | **Description**   | **Type** | **Required** | **Remarks**                                                  |
| ------------- | ----------------- | -------- | ------------ | ------------------------------------------------------------ |
| recordId      | Record ID         | String   | No           | Access record unique identifier                              |
| userId        | Unique Credential | array    | No           | Query recognition records for specific credential IDs. Pass `-1` to query all user records. |
| name          | User Name         | String   | No           | If empty, query isn't restricted by name.                    |
| startTime     | Record Start Time | Int      | No           | Pass timestamp to query by time. Omit if not querying by time. |
| endTime       | Record End Time   | Int      | No           | Pass timestamp to query by time. Omit if not querying by time. |
| size          | Page size         | Int      | Yes          | Range (0, 50] to return images. Range (0, 1000] to not return images. |
| page          | Page Number       | Int      | Yes          | Starts from 0.                                               |

Send Example:

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

- **Device feedback to Backend/App**

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

Data Parameters:

| **Parameter** | **Description** | **Type** | **Required** | **Remarks** |
| ------------- | ------------------ | -------- | ------------ | -------------------------- |
| page | Current page | Int | Yes | Current page |
| size | Page size | Int | Yes | Current page size |
| total | Total records | Int | Yes | Total records |
| totalPage | Total pages | Int | Yes | Total pages |
| count | Query result count | Int | Yes | Array length, <= size. |
| content | Record Array | Array | Yes | See `<content data>` below |

Content Data:

| **Parameter** | **Description**      | **Type** | **Required** | **Remarks**                                                  |
| ------------- | -------------------- | -------- | ------------ | ------------------------------------------------------------ |
| recordId      | Record ID            | String   | Yes          | Access record unique identifier                              |
| userId        | User ID              | String   | Yes          |                                                              |
| type          | Permission Type      | Int      | Yes          | Refer to Appendix Table 3 - `num` column. If Face+Card combined, fill `301`. If Face+QR combined, fill `302`. |
| timeStamp     | Access Timestamp     | Int      | Yes          |                                                              |
| result        | Access Result        | Int      | Yes          | `0`=Success, non-`0`=Failure                                 |
| name          | User Name            | String   | No           |                                                              |
| code          | Photo/Card/QR/Pwd/BT | String   | Y/N          | When type=300/301/302, fill with Base64 photo data. For other types, fill with corresponding credential value. |
| extra         | Other Data           | Object   | No           | When Face+Card/Face+QR combined, fill with Card or QR value. Can also include temperature info. |
| error         | Error Info           | String   | No           |                                                              |

Extra Table:

| **Parameter** | **Description**      | **Type** | **Required** | **Remarks**                                                  |
| ------------- | -------------------- | -------- | ------------ | ------------------------------------------------------------ |
| temperature   | Body Temperature     | Float    | No           |                                                              |
| code          | Photo/Card/QR/Pwd/BT | String   | No           | During Face+Card or Face+QR verification, fill with Card or QR value. |

Return Example:

```
{
	"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": "/9j/4AAQSkZJRgABAQAAAQABAAD…"
		},
		{
			"recordId": "6w8keif5g7",
			"userId": "100002",
			"name": "Chang Yongbin",
			"timeStamp": 1639475288,
			"code": "/9j/4AAQSkZJRgABAQAAAQABAAD…"
		},
		{
			"recordId": "6w8keif5g8",
			"userId": "100002",
			"name": "Chang Yongbin",
			"timeStamp": 1639475291,
			"code": "/9j/4AAQSkZJRgABAQAAAQABAAD…"
		}]
	}
}
```

#### 8.2 Delete Recognition Records

- **Backend/App to Device**

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

Data Parameters:

| **Parameter** | **Description** | **Type** | **Required** | **Remarks** |
| ------------- | ----------------- | -------- | ------------ | ------------------------------------------------------------ |
| recordId | Record ID | array | No | Access record unique identifier |
| userId | Unique Credential | array | No | |
| startTime | Start Time | Int | No | Pass a value > 0 to delete records AFTER startTime. If <= 0 or omitted, all are deleted. |
| endTime | End Time | Int | No | Pass a value > 0 to delete records BEFORE endTime. If <= 0 or omitted, all are deleted. |

Send Example:

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

- **Device feedback to Backend/App**

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

Return Example:

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

#### 8.3 Report Access Record

- **Device to Backend/App**

| **Message Topic** | **topic: access_device/v2/event/access** |
| ----------------- | ---------------------------------------- |
|                   |                                          |

Message Parameter Description:

| **Parameter** | **Description**      | **Type** | **Required** | **Remarks**                                                  |
| ------------- | -------------------- | -------- | ------------ | ------------------------------------------------------------ |
| userId        | User ID              | String   | Yes          |                                                              |
| type          | User Type            | Int      | Yes          | Refer to Appendix Table 3 - `num` column. If Face+Card combined, fill `301`. If Face+QR combined, fill `302`. |
| timeStamp     | Access Timestamp     | Int      | Yes          |                                                              |
| result        | Access Result        | Int      | Yes          | `0`=Success, non-`0`=Failure                                 |
| name          | User Name            | String   | No           |                                                              |
| code          | Photo/Card/QR/Pwd/BT | String   | Y/N          | When type=300/301/302, fill with Base64 photo data. For other types, fill with corresponding credential value. |
| extra         | Other Data           | Object   | No           | When Face+Card/Face+QR combined, fill with Card or QR value. |
| error         | Error Info           | String   | No           |                                                              |

Extra Table:

| **Parameter** | **Description**      | **Type** | **Required** | **Remarks**                                                  |
| ------------- | -------------------- | -------- | ------------ | ------------------------------------------------------------ |
| code          | Photo/Card/QR/Pwd/BT | String   | No           | During Face+Card or Face+QR verification, fill with Card or QR value. |

Send Example:

```
{
	"serialNo": "0000000001",
	"uuid": "e4720000964b5c00",
	"time": 0,
	"sign": "",
	"data": [{
		"userId": "412725202101011234",
		"type": 302,
		"timeStamp": 1639475284,
		"result": 0,
		"error": "success",
		"name": "Zhang San",
		"code": "/9j/4AAQSkZJRgABAQEAYABgAAD…",
		"extra": {
			"code": "&llgyAQASADQxMjcyNTIwMjEwMTAxMTIzNA==@3Fa"
		}
	}]
}
```

- **Backend/App feedback to Device**

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

Return Example:

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

## Appendix Table 1: Code Overview

| **Type**      | **code**        | **Message**                              | **Description**                                              |
| ------------- | --------------- | ---------------------------------------- | ------------------------------------------------------------ |
| Success       | `000000`        | Successfully executed command            | None                                                         |
| General Error | `100000`        | Unknown Error                            | None                                                         |
| General Error | `100001`        | Device Disabled                          | Many commands cannot execute when the device is disabled     |
| General Error | `100002`        | Device is busy, try again later          | Device is upgrading, configuring network, or running another task process |
| General Error | `100003`        | Signature Verification Failed            | None                                                         |
| General Error | `100004`        | Timeout Error                            | None                                                         |
| General Error | `100005`        | Device Offline                           | None                                                         |
| Param Error   | `200000-299999` | Parameter Exception                      | Different commands have different parameter specifications; refer to the description after each interface. |
| Other Error   | `300000-399999` | Other Exceptions caused by known reasons | Different commands map to different exceptions; refer to the description after each interface. |

## Appendix Table 2: Device Alarm Types

| **Type**           | **type** | **value**                                      | **door**                    |
| ------------------ | -------- | ---------------------------------------------- | --------------------------- |
| Door Sensor Status | `0`      | `0`: Door sensor open, `1`: Door sensor closed | Sequence number of the door |
| Fire Alarm Status  | `1`      | `1`: Warning                                   | None                        |

## Appendix Table 3: Credential Type Description

| **type** | **num**             | **Description**                                              |
| -------- | ------------------- | ------------------------------------------------------------ |
| face     | `300`               | `300`: Facial Data                                           |
| qrcode   | `100`, `101`, `103` | `100`: Passthrough code, `101`: Static code, `103`: Dynamic code |
| password | `400`               | `400`: Password data, Password length: 6 digits              |
| card     | `200`               | `200`: Standard card number, `201`: CPU encrypted card, `202`: Sector encrypted card (Requires issuing forward uppercase card number; passing lowercase will default to uppercase storage) |

## Appendix Table 4: Time Range Description

Supports the following four time range settings:

- **1. Default Mode**: No time limit, always valid.

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

- **2. Normal Mode**: Valid from a start time to an end time.

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

- **3. Daily Mode**: Valid from a specific time to a specific time every day. Invalid at other times. (Multiple time periods per day cannot overlap, up to 5 groups are supported). The `dayPeriodTime` parameter format is: "HH:MM-HH:MM", 24-hour format. E.g.: "08:00-09:30|10:00-11:30" maximum 5 periods. "00:00-24:00": means valid all day. Separate multiple periods with `|` without spaces. Maximum 5 periods per day. E.g., "08:00-09:30|10:00-11:30|12:00-13:30|15:00-16:30|17:00-18:30"

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

- **4. Weekly Repeat Mode**: Valid from a specific time to a specific time from Monday to Sunday. Invalid at other times. (Multiple time periods per day cannot overlap, up to 5 groups are supported). The `weekPeriodTime` parameter format is: "HH:MM-HH:MM", 24-hour format. E.g.: "08:00-09:30|10:00-11:30" max 5 periods. At least one day (1~7) must be passed, missing a day means no permission. "00:00-24:00": means valid all day. Separate multiple periods with `|` without spaces. Maximum 5 periods per day. E.g., "08:00-09:30|10:00-11:30|12:00-13:30|15:00-16:30|17:00-18:30"

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

## 9. Modification Log

| **Version** | **Date**   | **Editor**  | **Related Interface** | **Description** |
| ----------- | ---------- | ----------- | --------------------- | --------------- |
| V1.0.15     | 2025.11.20 | Ma Zhixiang | Initial Document      | -               |

|      |      |      |      |      |
| ---- | ---- | ---- | ---- | ---- |
|      |      |      |      |      |