将设备绑定到开发者账号。注册成功后才能调用云端设备接口。

请求URL

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

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

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

请求URL

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

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

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

online=1 表示在线，online=0 表示离线。部分旧版服务可能返回同义字段 on_line。

请求URL

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

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "open",
    "info": {
      "sn": "{{device_sn}}",
      "relay_ms": 1000,
      "tts": "核验成功，祝您游玩愉快",
      "volume": 6
    }
  }
}

{
  "code": 0,
  "data": {
    "device_sn": "{{device_sn}}",
    "cmd_type": "open",
    "info": {
      "sn": "{{device_sn}}",
      "relay_ms": 1000,
      "code": 0,
      "msg": ""
    }
  }
}

设备处于常开模式时只播放提示，不重复执行继电器脉冲。

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

主要返回字段

离线二维码密钥和偏移量不会返回。业务日志如需保存本接口响应，应对 IMEI、ICCID 和核验地址进行脱敏。

命令类型固定为 setting。只需传入要修改的字段；未传字段保持不变。

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "setting",
    "info": {
      "qrcode_reader_power": 1,
      "qrcode_reader_baud": 9600,
      "qrcode_reader_frame_timeout": 200,
      "qrcode_reader_max_length": 512,
      "qrcode_reader_dedupe_seconds": 20,
      "qrcode_reader_debug": 0,
      "scan_api_mode": "direct",
      "scan_api_url": "https://example.com/api/device/scan",
      "scan_api_timeout_ms": 40000
    }
  }
}

读头供电或波特率变化后设备延迟约 3 秒重启。收到成功响应后，应等待重连并通过 getdevinfo 回读。

当 scan_api_mode=direct 时，设备向 scan_api_url 发起 HTTPS POST，并在 X-Device-Token 请求头携带设备访问令牌。核验服务应校验设备身份、二维码时效和业务余额，并保证同一请求的扣费幂等。

请求体

{
  "device_sn": "{{device_sn}}",
  "qr_code": "{{qrcode_content}}"
}

成功放行响应

{
  "code": 0,
  "action": "open",
  "scan_id": "{{scan_id}}",
  "relay_ms": 1000,
  "message": "核验成功，已扣除1积分，祝您游玩愉快",
  "volume": 6
}

只有 HTTP 200、合法 JSON、code=0 且 action=open 同时满足时才开闸。relay_ms 有效范围为 200～30000 ms，message 最长 256 UTF-8 字节，volume 为 0～7。任何超时、格式错误或扣费结果不确定都必须保持闸机关闭。

失败时可返回非零 code 和面向游客的 message：

{
  "code": 1002,
  "action": "deny",
  "message": "抱歉，您的积分不足"
}

设备不会在直连失败后自动改走 MQTT，以免同一会员码被两条链路重复扣费。

设置继电器脉冲时长

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "set_relay",
    "info": {
      "relay1": 1000
    }
  }
}

relay1 必须为数字，范围 1000～30000 ms。

设置常开/常闭

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

type=0 为常闭，type=1 为常开。设置会立即改变继电器状态并持久保存。

立即播放TTS

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "play_tts",
    "info": {
      "tts": "设备维护中，请稍候",
      "volume": 6
    }
  }
}

tts 为 1～256 UTF-8 字节，volume 为 0～7。命令成功表示设备接受播放请求，不代表扬声器已完整播放结束。

配置默认提示

将 cmd_type 改为 set_audio，info 可包含 pass_tts、no_pass_tts、launch_tts 和 volume。文本长度为 1～256 UTF-8 字节；传单个空格可清除对应自定义值。

支持 card_add、card_edit、card_del、card_find、card_sum、card_clr。

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "card_add",
    "info": {
      "card_id": "27598FAF",
      "start_time": 0,
      "end_time": 2147483647
    }
  }
}

card_del、card_find 需要 card_id；card_sum、card_clr 的 info 可为空对象。清空操作不可撤销。

synccards 用于分批全量同步。第一批会清空设备现有卡片，业务端必须固定本次同步的 total_batches 并严格按 batch_num 从 1 递增；失败时不要跳过批次。

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "synccards",
    "info": {
      "batch_num": 1,
      "total_batches": 1,
      "cards": [
        {
          "card_id": "27598FAF",
          "start_time": 0,
          "end_time": 2147483647
        }
      ]
    }
  }
}

响应包含 batch_success、batch_failed、total_processed、progress、is_completed 和 total_cards_in_device。只有最后一批返回 is_completed=true 才表示本次同步完成。

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "device_add_card",
    "info": {
      "state": 1,
      "start_time": 0,
      "end_time": 2147483647
    }
  }
}

state=1 进入发卡模式，state=0 退出。进入后应在业务完成时主动退出。

发卡成功后，平台向开发者回调地址推送：

{
  "cmd_type": "add_card_notify",
  "device_sn": "{{device_sn}}",
  "info": {
    "card_id": "27598FAF",
    "start_time": 0,
    "end_time": 2147483647
  }
}

门磁变化时平台向开发者回调地址推送：

{
  "cmd_type": "door_state_notify",
  "device_sn": "{{device_sn}}",
  "info": {
    "state": 0
  }
}

state=0 和 state=1 分别对应设备检测到的两种门磁电平；安装后应根据现场接线确认开门、关门语义。

本地认证或云端开门成功后推送 open_notify：

{
  "cmd_type": "open_notify",
  "device_sn": "{{device_sn}}",
  "info": {
    "type": "member_qrcode",
    "data": "{{scan_id}}"
  }
}

常见 type 包括 open_cmd、card、temporary_passwd、bluetooth、member_qrcode 和 offline_admin_qrcode。业务系统应按敏感数据处理 info.data，不得直接写入公开日志。

管理员离线二维码用于工作人员在断网时扫码通行。管理平台为每个闸机配置独立密钥，生成带编号、生效时间、失效时间和签名的二维码；设备本地完成解密、签名、时间和废除列表校验。固件 1.0.3 或以上不存在通用默认密钥，只有显式配置后才启用；Air724 设备应升级至 1.0.7 或以上。管理员码走本地优先通道，不播放云端核验等待语音，校验成功后立即播放放行语音并开门；不受普通二维码防重扫时间或会员云核验忙状态限制。

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "set_offline_qrcode",
    "info": {
      "header": "{{offline_qrcode_header}}",
      "sm4_key": "{{16_byte_secret_key}}",
      "sm4_offset": "{{16_byte_secret_iv}}"
    }
  }
}

header 为 1～64 字节，sm4_key 和 sm4_offset 必须分别为 16 字节。三个值应由管理平台随机分配、加密保存，禁止使用示例值投入生产。重新配置密钥会使以前生成的管理员二维码全部失效。设备不会通过 getdevinfo 回传密钥或偏移量。

废除指定管理员二维码：

{
  "app_id": "{{wmjv2appid}}",
  "app_secret": "{{wmjv2appsecret}}",
  "device_sn": "{{device_sn}}",
  "type": 1,
  "data": {
    "cmd_type": "revoke_offline_qrcode",
    "info": {
      "id": "A1B2C3D4E5F6",
      "expire_at": 1798761600
    }
  }
}

id 为 12 位十六进制编号，expire_at 为该二维码的 Unix 失效时间。设备只保留尚未自然过期的废除记录，最多 64 条；达到上限时应更换密钥。废除必须以设备返回业务码 0 为生效依据；设备离线时管理平台应显示“废除待同步”，不能把平台记录更新当成设备已废除。

管理员码校验和开门均在设备本地完成，不依赖联网。设备可异步向所配置的管理平台记录校验成功、失败原因和二维码编号；日志上报不阻塞开门，且不包含二维码原文、密钥或签名。

先调用 POST https://wdev.wmj.com.cn/deviceApi/TPassword 获取一次性临时密码：

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

通过 BLE 向写特性 FEE1 写入：

{
  "cmd_type": "ble_pwd_open_lock",
  "info": {
    "data": "12345678"
  }
}

设备通过通知特性 FEE2 返回执行结果。临时密码带滚码状态，成功使用后不可重复使用。

远程重启使用 restart：

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

reset 会清空本地卡片和设备配置后重启，属于不可撤销操作。调用前必须由业务系统进行二次确认，并先保存需要恢复的配置。

• W76S 没有显示屏和摄像头，不支持 W766 的 set_qrcode 或屏幕二维码字段。
• UART3 已用于二维码读头，不支持 W766 键盘配置字段。
• W76S 无键盘，不支持 pwd_add、pwd_edit、pwd_del、pwd_find、pwd_sum 和 pwd_clr。
• test_card_add 和 sm4_encrypt 是已禁用的遗留调试命令，固件 1.0.3 或以上返回设备业务码 2。
• 平台返回成功但配置未变化：检查 data.info.code，等待设备重连后用 getdevinfo 回读。
• 设备离线：调用 getOnLine，不要用开门、重启或语音命令探活。
• 扫码提示后未开门：检查核验服务 HTTP 状态、响应 JSON、code、action 和扣费幂等日志。
• HTTP 或 MQTT 应答只表示命令链路完成；真实开闸仍应结合门磁、继电器和现场行为验证。

解除设备与当前开发者账号的绑定。解绑后该账号不能再控制设备。

请求URL

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

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

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