请求URL

https://wdev.wmj.com.cn/deviceApi/register

请求方式

POST

请求格式

json

参数

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}"
}

返回示例

{
  "code": 0,
  "msg": "注册成功"
}

简要描述

查询设备是否连接硬件云。本接口只读取平台在线记录，不向设备发送命令。

请求URL

https://wdev.wmj.com.cn/deviceApi/getOnLine

请求方式

POST

请求格式

json

参数

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}"
}

返回示例

{
  "code": 0,
  "msg": "查询成功",
  "data": {
    "on_line": 1
  }
}

简要描述

查询型号、软硬件版本、4G 信号和门禁输入输出状态。设备必须在线。

请求URL

https://wdev.wmj.com.cn/deviceApi/send

请求方式

POST

请求格式

json

参数

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "getdevinfo",
    "info": {}
  }
}

返回示例

{
  "code": 0,
  "data": {
    "device_sn": "{{device_sn}}",
    "cmd_type": "getdevinfo",
    "info": {
      "code": 0,
      "msg": "OK",
      "model": "W76R",
      "hw": "1.0.0",
      "sw": "0.1.11",
      "fwVer": "0.1.11",
      "rssi": -55,
      "csq": 24,
      "ber": 0,
      "doorstate": 0,
      "relayStatus": 0
    }
  }
}

响应可能同时包含设备和 SIM 网络标识字段。客户系统应按最小必要原则保存，不应公开这些标识。

简要描述

获取设备最近一次成功读取的 EPC、芯片 TID 和本地授权数量。该接口不会自动注册标签，也不会主动开门。发卡时请确保天线有效读区内只有一张待发标签。

请求URL

https://wdev.wmj.com.cn/deviceApi/send

请求方式

POST

请求格式

json

参数

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "rfid_tag_get",
    "info": {}
  }
}

返回示例

{
  "code": 0,
  "data": {
    "device_sn": "{{device_sn}}",
    "cmd_type": "rfid_tag_get",
    "info": {
      "code": 0,
      "msg": "OK",
      "epc": "{{tag_epc}}",
      "tid": "{{tag_tid}}",
      "card_count": 1250,
      "registry_ready": 1,
      "registry_last_error": 0,
      "storage_free": 40960,
      "auto_authorize_feedback": 1,
      "tid_read_ok": 17,
      "tid_read_failed": 2,
      "tid_retry_recovered": 6,
      "tid_last_attempts": 1,
      "tid_last_status": 0,
      "tid_last_tag_error": 0
    }
  }
}

• 尚未成功读到标签时，epc 和 tid 为空字符串。
• EPC、TID 不带 0x、空格或分隔符。
• 返回的是最近一次成功读取结果，发卡软件应提示操作员核对当前标签。
• 固件 0.1.16 起会在 M100 盘存功放切换稳定后读取 TID，并对瞬时未响应进行有界重试。固件 0.1.17 起，最终读取失败仅记录诊断，不再播放“标签读取失败”；排障时应结合 tid_read_ok、tid_read_failed、tid_retry_recovered 和最近状态字段判断。

简要描述

按当前 EPC 选中读区内标签并改写 EPC 存储区。多数项目可直接使用标签出厂 EPC，无需改写。

改写 EPC 不会改变 TID，也不会自动授权。写入后必须回读确认，再用原 TID 与新 EPC 调用“新增或更新车辆标签”。

请求URL

https://wdev.wmj.com.cn/deviceApi/send

请求方式

POST

请求格式

json

参数

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "rfid_tag_epc_write",
    "info": {
      "current_epc": "{{current_tag_epc}}",
      "new_epc": "{{new_tag_epc}}",
      "access_password": 0
    }
  }
}

EPC 必须为偶数字节长度的十六进制字符串。写入时读区内只能有一张目标标签。本接口不开放标签锁定、销毁或修改 TID。

返回示例

{
  "code": 0,
  "data": {
    "device_sn": "{{device_sn}}",
    "cmd_type": "rfid_tag_epc_write",
    "info": {
      "code": 0,
      "msg": "OK"
    }
  }
}

简要描述

以芯片 TID 为唯一键，在目标 W76R 本地新增或更新授权记录。相同请求可以安全重试。

请求URL

https://wdev.wmj.com.cn/deviceApi/send

请求方式

POST

请求格式

json

参数

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "rfid_card_upsert",
    "info": {
      "card_id": "EV-000001",
      "tid": "{{tag_tid}}",
      "epc": "{{tag_epc}}",
      "enabled": 1,
      "valid_from": 0,
      "valid_until": 0
    }
  }
}

valid_from 和 valid_until 同时非零时，开始时间不得晚于结束时间。同一 EPC 不能绑定到另一个 TID。

返回示例

{
  "code": 0,
  "data": {
    "device_sn": "{{device_sn}}",
    "cmd_type": "rfid_card_upsert",
    "info": {
      "code": 0,
      "msg": "OK"
    }
  }
}

多设备部署时，本地授权库不会自动互相复制。客户平台应保存“标签—设备”关系，并向所有允许通行的 W76R 分别下发授权。

简要描述

分页查询目标 W76R 的本地授权记录，用于发卡结果确认、设备迁移和数据核对。

请求URL

https://wdev.wmj.com.cn/deviceApi/send

请求方式

POST

请求格式

json

参数

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "rfid_card_list",
    "info": {
      "offset": 0,
      "limit": 5
    }
  }
}

返回示例

{
  "code": 0,
  "data": {
    "device_sn": "{{device_sn}}",
    "cmd_type": "rfid_card_list",
    "info": {
      "code": 0,
      "msg": "OK",
      "total": 1,
      "offset": 0,
      "limit": 5,
      "cards": [
        {
          "card_id": "EV-000001",
          "tid": "{{tag_tid}}",
          "epc": "{{tag_epc}}",
          "enabled": 1,
          "valid_from": 0,
          "valid_until": 0
        }
      ]
    }
  }
}

offset 或 limit 超出范围、不是整数时，设备返回 data.info.code=-1 和明确的参数错误说明，不会静默改用默认值。此行为要求固件 0.1.8 或更高版本。

简要描述

按 TID 修改一条授权记录的启用状态，不删除车辆信息。

请求URL

https://wdev.wmj.com.cn/deviceApi/send

请求方式

POST

请求格式

json

参数

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "rfid_card_enable",
    "info": {
      "tid": "{{tag_tid}}",
      "enabled": 0
    }
  }
}

返回示例

{
  "code": 0,
  "data": {
    "device_sn": "{{device_sn}}",
    "cmd_type": "rfid_card_enable",
    "info": {
      "code": 0,
      "msg": "OK"
    }
  }
}

简要描述

按 TID 删除目标 W76R 中的一条本地授权记录。删除后该标签在该设备上立即失去通行权限。

请求URL

https://wdev.wmj.com.cn/deviceApi/send

请求方式

POST

请求格式

json

参数

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "rfid_card_delete",
    "info": {
      "tid": "{{tag_tid}}"
    }
  }
}

返回示例

{
  "code": 0,
  "data": {
    "device_sn": "{{device_sn}}",
    "cmd_type": "rfid_card_delete",
    "info": {
      "code": 0,
      "msg": "OK"
    }
  }
}

固件 0.1.12 起，设备默认音量提高为 80%，并支持后台持久设置。音量配置保存在设备文件系统中，重启或断网后仍然生效。

设置音量时发送 setting，volume_percent 为 0～100 的整数：

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "setting",
    "info": {"volume_percent": 80}
  }
}

成功响应中的 data.info.volume 是设备实际应用的百分比音量。查询当前值时发送：

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {"cmd_type": "get_play_status", "info": {}}
}

旧字段 volume=1～10 保留十档兼容语义；新系统应使用 volume_percent，避免 1～10 数值产生歧义。播放命令携带的音量只修改当前运行音量，不写入持久配置；设备重启后恢复后台持久设置值。

固件 0.1.14 起，自动登记业务可同时设置未知标签的本地提示方式：

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "setting",
    "info": {"auto_authorize_feedback": 1}
  }
}

auto_authorize_feedback=1 时，设备首次识别未知标签会播报“标签读取成功”，但仍不输出开门信号；业务平台收到 unknown_card 回调后建档并下发授权，标签再次进入识别区才按正常授权开门。设为 0 时恢复“未授权，禁止通行”。该设置持久保存，重启后继续生效。可用 rfid_tag_get 返回的 auto_authorize_feedback、registry_ready 和 registry_last_error 核对设置与本地卡库状态。

W76R 识别标签后依次检查：

1. TID 是否存在于本地授权库；
2. 当前 EPC 是否与该 TID 保存的 EPC 一致；
3. 授权记录是否启用；
4. 当前时间是否处于有效期；
5. 授权库是否可以正常读取。

全部通过后，设备输出约 1 秒开门信号。未注册、已停用、未生效、已过期、TID/EPC 不一致或定时授权无法取得有效时间时，均不输出开门信号。

固件 0.1.10 起，语音在本地鉴权完成后播放，并与实际结果一致：

这些短语音随固件内置，启动时写入设备文件系统，断网时仍可播放，不需要现场实时合成。固件 0.1.9 起，每次完成本地鉴权后都会按下一节格式上报允许或拒绝结果。

简要描述

W76R 完成本地 RFID 鉴权后，主动向硬件云发布 type=2、cmd_type=rfid_passage 消息。硬件云再以 HTTP POST 转发到开放平台应用配置的回调地址。

回调链路为：

W76R设备 → MQTT → 微门禁硬件云 → HTTP POST → 客户业务系统

设备不会直接请求客户业务系统。允许和拒绝事件都会回调；只有允许事件会输出开门信号。

回调方式

• 请求方式：POST
• 请求格式：application/json
• 回调地址：开放平台应用中配置的 Callback URL
• 版本要求：W76R 固件 0.1.9 或更高版本

回调示例

{
  "device_sn": "{{device_sn}}",
  "type": 2,
  "msg_id": 125,
  "cmd_type": "rfid_passage",
  "info": {
    "event_uid": "{{device_sn}}-1787220000-84215-125-A1B2C3D4",
    "event_time": 1787220000,
    "card_id": "EV-000001",
    "tag_tid": "{{tag_tid}}",
    "tag_epc": "{{tag_epc}}",
    "rssi": -48,
    "pass_result": 1,
    "auth_result": 0,
    "reason": "granted",
    "relay_output": 1
  }
}

字段说明

鉴权结果

业务系统处理要求

1. 收到事件后应尽快返回 HTTP 2xx，不要在回调请求中执行耗时任务。
2. 使用 device_sn + event_uid 建立唯一约束；重复事件直接返回成功。
3. 以 pass_result 判断是否放行，不要以语音提示、card_id 是否为空代替。
4. event_time=0 时可使用业务系统接收时间，但应保留原始值用于排查。
5. 本地鉴权和开门不依赖回调。设备离线时仍可本地通行，但当前版本不会持久化补传离线期间的通行事件。

• TID 通常由标签芯片提供且不可改写，EPC 可以改写。W76R 同时校验 TID 和 EPC，降低只复制 EPC 获得权限的风险。
• EPC 改写后，仍保存旧 EPC 的设备会拒绝通行，必须重新下发授权。
• RFID 管理命令应通过本文 HTTPS 接口发送，不支持客户直接向设备发送明文管理命令。
• 发卡区应限制射频覆盖范围，并确保一次只有一张标签。
• 客户平台应保存原始 TID、当前 EPC、业务卡号、授权设备和有效期，设备更换或恢复时据此重新下发。
• 3000 张以上标签建议使用后台任务队列逐台、逐条下发，保存每条命令的双层返回，并在完成后分页核对总数与抽样数据。

平台层常见返回

设备命令失败时，以 data.info.code 和 data.info.msg 为准。管理命令返回 -403 表示未通过受保护通道，请使用本文的 /deviceApi/send，不要绕过硬件云协议。

写入 EPC 成功后为什么不能开门？

写入 EPC 不等于授权。请先回读确认，再把原 TID、新 EPC 写入每台需要放行的 W76R。

一台 W76R 写的标签能否在另一台使用？

可以。写标签设备不限制通行设备，但另一台设备必须保存相同 TID 与 EPC 的有效授权。

设备离线时车辆还能通行吗？

已保存且仍有效的授权可在本地判断。新增、修改、停用或删除授权需要设备重新在线后下发。

读标签接口为什么返回空字符串？

设备还没有成功读取标签，或标签不在有效读区。请调整距离和方向，并确保读区内只有目标标签。

简要描述

解除 W76R 与当前账号的绑定。解绑不会清空本地 RFID 授权库，不能用解绑代替删除标签。

请求URL

https://wdev.wmj.com.cn/deviceApi/logout

请求方式

POST

请求格式

json

参数

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}"
}

返回示例

{
  "code": 0,
  "msg": "解绑成功"
}