设备/角色封禁管理 API 接口文档

概述

设备/角色封禁功能允许合作伙伴通过 API 管理其设备和角色的封禁状态。被封禁的设备或角色在调用 init_npc 时将被拒绝连接。

Base URL: https://hippo.adventists.cn

路由前缀: /api

数据格式: JSON

编码: UTF-8

鉴权方式

所有管理接口通过 HTTP Header 鉴权：

Header	类型	必填	说明
`api_key`	string	是	32 位 API 密钥
`org_id`	string	是	6 位组织 ID

鉴权失败时返回 401：

{
    "message": "Invalid API KEY or ORG ID"
}

接口一览

方法	路径	说明
POST	`/api/device/block`	封禁设备/角色
POST	`/api/device/unblock`	解封设备/角色
GET	`/api/device/blocklist`	查询封禁列表
GET	`/api/device/block/check`	查询单个封禁状态

封禁设备/角色

添加一条封禁记录。被封禁的设备或角色在 init_npc 时会被拒绝。

POST /api/device/block

请求体

{
    "type": "device",
    "identifier": "ABC123",
    "reason": "违规使用"
}

参数	类型	必填	说明
type	string	是	`"device"` 或 `"npc"`
identifier	string	是	设备 ID 或角色 ID（npcid）
reason	string	否	封禁原因

当 type 为 "npc" 时，identifier 必须属于当前组织（即 identifier 前 6 位与 org_id 一致），否则返回 403。

成功响应（200）

{
    "ok": true,
    "block_key": "device:ABC123"
}

错误响应

400 - 参数错误

{
    "ok": false,
    "error": "Missing required field: type"
}

403 - 无权限

{
    "ok": false,
    "error": "Cannot block NPC belonging to another org"
}

cURL 示例

解封设备/角色

移除一条封禁记录。只能解封本组织创建的封禁记录。

POST /api/device/unblock

请求体

{
    "type": "device",
    "identifier": "ABC123"
}

参数	类型	必填	说明
type	string	是	`"device"` 或 `"npc"`
identifier	string	是	设备 ID 或角色 ID

成功响应（200）

{
    "ok": true
}

错误响应

404 - 记录不存在

{
    "ok": false,
    "error": "Block record not found"
}

403 - 无权限

{
    "ok": false,
    "error": "Cannot unblock record owned by another org"
}

cURL 示例

查询封禁列表

查询当前组织的所有封禁记录，支持按类型过滤。

GET /api/device/blocklist

查询参数

参数	类型	必填	说明
type	string	否	按类型过滤：`"device"` 或 `"npc"`，不传则返回全部

成功响应（200）

{
    "ok": true,
    "items": [
        {
            "block_key": "device:ABC123",
            "type": "device",
            "identifier": "ABC123",
            "created_at": "2026-04-10T15:30:00Z",
            "created_by": "WOQSOC",
            "reason": "违规使用"
        },
        {
            "block_key": "npc:WOQSOC7a8b9c1d2e3f4a5b6c7d8e9f0a1b2c3d",
            "type": "npc",
            "identifier": "WOQSOC7a8b9c1d2e3f4a5b6c7d8e9f0a1b2c3d",
            "created_at": "2026-04-10T16:00:00Z",
            "created_by": "WOQSOC",
            "reason": "角色停用"
        }
    ]
}

cURL 示例

查询单个封禁状态

查询指定设备或角色是否被封禁。

GET /api/device/block/check

查询参数

参数	类型	必填	说明
type	string	是	`"device"` 或 `"npc"`
identifier	string	是	设备 ID 或角色 ID

已封禁响应（200）

{
    "ok": true,
    "blocked": true,
    "detail": {
        "reason": "违规使用",
        "created_at": "2026-04-10T15:30:00Z",
        "created_by": "WOQSOC"
    }
}

未封禁响应（200）

{
    "ok": true,
    "blocked": false
}

cURL 示例

init_npc 行为变更

init_npc 接口新增可选参数 device_id，并在初始化前进行封禁检查。

新增请求参数

参数	类型	必填	说明
npcid	string	是	角色 ID
lang	string	否	语言设置
device_id	string	否	设备 ID（新增，不传时跳过设备维度的封禁检查）

封禁检查顺序

若传入 device_id，检查该设备是否被封禁

检查 npcid 是否被封禁

两项均通过后执行原有初始化逻辑

封禁响应

当设备或角色被封禁时，init_npc 返回（HTTP 200）：

{
    "status": "blocked",
    "reason": "设备已被封禁"
}

TCP 侧通过 status 字段值为 "blocked" 判断连接被拒绝。

正常初始化的响应格式不变：

{
    "message": "NPC xxx initialized successfully",
    "status": "success",
    "code": 200
}

错误码汇总

HTTP 状态码	说明
200	请求成功
400	参数错误（缺少 type 或 identifier，type 值无效）
401	api_key 或 org_id 无效
403	无权限（尝试操作其他组织的 NPC）
404	未找到（unblock 时封禁记录不存在）
500	服务端错误

概述#

鉴权方式#

接口一览#

封禁设备/角色#

请求体#

成功响应（200）#

错误响应#

cURL 示例#

解封设备/角色#

请求体#

成功响应（200）#

错误响应#

cURL 示例#

查询封禁列表#

查询参数#

成功响应（200）#

cURL 示例#

查询单个封禁状态#

查询参数#

已封禁响应（200）#

未封禁响应（200）#

cURL 示例#

init_npc 行为变更#

新增请求参数#

封禁检查顺序#

封禁响应#

错误码汇总#

概述

鉴权方式

接口一览

封禁设备/角色

请求体

成功响应（200）

错误响应

cURL 示例

解封设备/角色

请求体

成功响应（200）

错误响应

cURL 示例

查询封禁列表

查询参数

成功响应（200）

cURL 示例

查询单个封禁状态

查询参数

已封禁响应（200）

未封禁响应（200）

cURL 示例

init_npc 行为变更

新增请求参数

封禁检查顺序

封禁响应

错误码汇总