创建设备

创建一个设备，返回的标识用于后续扫码登录。⚠️ version 是整数，传 0 即可；传版本号字符串会被拒绝。

POST/qingluan/api/device/create

在线调试鉴权与基础约定

接口说明

创建一个设备，返回的标识用于后续扫码登录。⚠️ version 是整数，传 0 即可；传版本号字符串会被拒绝。

请求参数

请求体必填。通过 QL-Key 请求头携带 APIKey。

Content-Type：application/json

请求参数。字段名区分大小写，请按文档原样传递。

appidstring必填

青鸾实例 ID，形如 we_xxxxxxxxxxxxxxx。在开发者控制台「实例与回调」扫码上号后获得。

字段示例："we_xxxxxxxxxxxxxxx"

typestring必填

类型

设备类型，例如 iPad。

注意：必填且强校验：缺失或空串直接 code=-1 / type cannot be empty。传 iPad 可用，其它取值未确认。（早期契约未把它标为必填，contract_errors.missing_required 已记录，现按实际补齐。）

字段示例："iPad"

namestring必填

名称

名称/昵称

注意：契约标 required，但完全不传也返回 code=0。至少在缺失时服务端不做校验。它究竟影响什么（设备显示名？风控画像？）未确认。

字段示例："东皇太一"

versionint64必填

版本号，整数，传 0 即可。

字段示例：0

响应与结果确认

本接口为能力层原样返回，不统一增加青鸾外层信封。code = 0 仅表示请求被接受，不保证副作用已完成。

请结合业务数据与本页说明判断实际状态，不要仅凭响应码推断操作效果。

响应字段与 HTTP 状态

HTTP 200

能力层原样返回；code = 0 仅表示请求已受理，业务结果须按接口说明确认。

application/json

查看响应字段定义

接口原样返回平台的业务响应。HTTP 状态码与业务状态码需分别判断：HTTP 200 只表示请求已送达，成功以 code = 0 为准。

codeinteger必填

业务状态码

业务状态码：0 表示成功，-1 表示失败；失败原因见 message。

字段示例：0

dataobject可选

业务数据

业务返回数据；字段结构见下方定义。

appidstring可选

设备实例 ID

设备实例 ID。由 /api/device/create 返回；登录后保持不变，可长期复用。

注意：契约写「登录后保持不变，可长期复用」，容易被误读成「重复调用返回同一个」。不是：即使请求体里带了一个已有 appid，返回的仍是一个全新值。「保持不变」指的是同一个实例在其生命周期内不变，不是这个接口幂等。格式 we_ + 15 位大小写字母数字（总长 18）。

最短长度：1 字段示例："{{appid}}"

detailstring可选

错误详情

错误详情；无补充信息时通常为空字符串。

messagestring必填

响应消息

业务结果消息。成功通常为 ok；企微错误通常为 错误码|错误信息。

字段示例："ok"

timestring必填

服务端时间

服务端时间，格式为 YYYY-MM-DD HH:mm:ss。

字段示例："2026-07-21 07:33:17"

HTTP 403

受控接口，需通过控制台配置

HTTP 404

appid 不存在或无权访问

请求示例

请求示例 · JSON

{
  "appid": "we_xxxxxxxxxxxxxxx",
  "type": "iPad",
  "name": "示例名称",
  "version": 0
}

响应示例

HTTP 200 响应示例 · JSON

{
  "code": 0,
  "data": {
    "appid": "{{appid}}"
  },
  "detail": "",
  "message": "ok",
  "time": "2026-07-21 07:33:17"
}

本接口为能力层原样返回，不统一增加青鸾外层信封。code = 0 仅表示请求被接受，不保证副作用已完成。

请结合业务数据与本页说明判断实际状态，不要仅凭响应码推断操作效果。