操作标签

新增或删除标签 / 标签组。

POST/qingluan/api/label/operate

接口说明

新增或删除标签 / 标签组。

operItems 的元素形如 {op, label:{...}}，不是 {labelName}。 op：1 新增 · 2 删除 · 3 表示既有条目（同步接口返回的都是 3）。 labelType：1 企业标签 · 2 个人标签。dataType：2 标签组（labelGroupId 传 0）· 1 组下的标签（labelGroupId 传父组 ID）。

⚠️ 删除是软删：条目仍会出现在同步结果里，只是 bDeleted 变成 1。 ⚠️ 操作企业标签需要企业侧的标签管理权限，否则返回 -1000888；个人标签不受此限。

请求参数

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

Content-Type：application/json

appidstring必填

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

字段示例："we_xxxxxxxxxxxxxxx"

opSceneinteger可选

字段示例：2

labelTypeinteger可选

字段示例：1

operItemsobject[]可选

数组元素 · object

opinteger可选

字段示例：2

labelobject可选

idint64可选

字段示例：14073752025997020

namestring可选

字段示例："老王"

dataTypeinteger可选

字段示例：1

bDeletedinteger可选

字段示例：0

labelGroupIdint64可选

字段示例：14073751126007792

createTimeinteger可选

字段示例：1787907966

labelTypeinteger可选

字段示例：1

businessTypeinteger可选

字段示例：0

orderinteger可选

字段示例：0

serviceGroupIdinteger可选

字段示例：0

字段示例：

{"id": 14073752025997020, "name": "老王", "dataType": 1, "bDeleted": 0, "labelGroupId": 14073751126007792, "createTime": 1787907966, "labelType": 1, "businessType": 0, "order": 0, "serviceGroupId": 0}

字段示例：

[{"op": 2, "label": {"id": 14073752025997020, "name": "老王", "dataType": 1, "bDeleted": 0, "labelGroupId": 14073751126007792, "createTime": 1787907966, "labelType": 1, "businessType": 0, "order": 0, "serviceGroupId": 0}}]

响应与结果确认

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

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

响应字段与 HTTP 状态

HTTP 200

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

application/json

查看响应字段定义

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

codeinteger必填

业务状态码

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

字段示例：0

dataobject可选

业务数据

接口无固定结构化返回数据；成功时通常为空对象或省略 data。

注意：成功时恒为 null，没有任何回执内容。判断成功只能看 code；但本接口可以用回调里的 1001 载荷做二次确认。

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",
  "opScene": 2,
  "labelType": 1,
  "operItems": [
    {
      "op": 2,
      "label": {
        "id": 14073752025997020,
        "name": "老王",
        "dataType": 1,
        "bDeleted": 0,
        "labelGroupId": 14073751126007792,
        "createTime": 1787907966,
        "labelType": 1,
        "businessType": 0,
        "order": 0,
        "serviceGroupId": 0
      }
    }
  ]
}

响应示例

HTTP 200 响应示例 · JSON

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

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

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