检测二维码

轮询查询当前扫码会话进展（状态机核心）；登录成功时同时返回账号身份字段。

说明与注意

• 无需传代理，沿用取码时的代理；推送地址以你在回调配置里设置的为准，本接口不用传。
• status 全部取值：-1 登录状态失效，需重新扫码；0 未扫码；1 / 6 已扫码待确认；10 已扫码确认，待 6 位验证码；2 登录成功；3 登录失败；4 用户取消登录。建议每 2 到 3 秒轮询一次；提交验证码后必须再次调用本接口，status 变为 2 才算登录成功。
• nonceKey、deviceUuid、scannerNonce 是登录内部凭证，业务侧不用保存，不要外泄；登录后调用其他业务接口使用保存的 appid。

请求参数

参数	必填	类型	说明
appid	是	string	获取二维码返回的实例 appid。示例：we_xxxxxxxxxxxxxxx
uuid	是	string	getQr 返回的二维码 uuid。示例：68EF33CF8D86CBC1D9214DCA3AD6B04C
pushHistory	否	boolean	是否推送历史消息。示例：false

请求示例

HTTP

POST {BASE_URL}/wx-api/api/login/checkQr
Authorization: Bearer <你的 App Token>
Content-Type: application/json

{
  "appid": "we_xxxxxxxxxxxxxxx",
  "uuid": "68EF33CF8D86CBC1D9214DCA3AD6B04C",
  "pushHistory": false
}

curl

curl -X POST '{BASE_URL}/wx-api/api/login/checkQr' \
  -H 'Authorization: Bearer <你的 App Token>' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "appid": "we_xxxxxxxxxxxxxxx",
  "uuid": "68EF33CF8D86CBC1D9214DCA3AD6B04C",
  "pushHistory": false
}'

Python

import requests

url = "{BASE_URL}/wx-api/api/login/checkQr"
headers = {"Authorization": "Bearer <你的 App Token>", "Content-Type": "application/json"}
body = """{
  "appid": "we_xxxxxxxxxxxxxxx",
  "uuid": "68EF33CF8D86CBC1D9214DCA3AD6B04C",
  "pushHistory": false
}"""

resp = requests.post(url, headers=headers, data=body.encode("utf-8"))
print(resp.text)

Java

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;

String url = "{BASE_URL}/wx-api/api/login/checkQr";
String body = "{\n" +
    "  \"appid\": \"we_xxxxxxxxxxxxxxx\",\n" +
    "  \"uuid\": \"68EF33CF8D86CBC1D9214DCA3AD6B04C\",\n" +
    "  \"pushHistory\": false\n" +
    "}";

HttpClient client = HttpClient.newHttpClient();
HttpRequest request = HttpRequest.newBuilder(URI.create(url))
    .header("Authorization", "Bearer <你的 App Token>")
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();
HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

PHP

<?php

$url = '{BASE_URL}/wx-api/api/login/checkQr';
$body = <<<'JSON'
{
  "appid": "we_xxxxxxxxxxxxxxx",
  "uuid": "68EF33CF8D86CBC1D9214DCA3AD6B04C",
  "pushHistory": false
}
JSON;

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Authorization: Bearer <你的 App Token>',
    'Content-Type: application/json',
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

响应示例

{
  "code": 0,
  "data": {
    "uuid": "4BB5…FE7B",
    "authId": 2251801417098298,
    "corpId": 1970324965569447,
    "status": 2,
    "nickName": "哈**",
    "nonceKey": "J5L0…(脱敏)",
    "avatarUrl": "https://wework.qpic.cn/wwpic3az/373744_…/0",
    "corpUserId": 1688857562919230,
    "deviceUuid": "52be…(脱敏)",
    "corpLogoUrl": "https://wework.qpic.cn/wwpic3az/875652_…/0",
    "scannerNonce": "oT4e…(脱敏)",
    "WxUserProfile": {
      "avatarUrl": "https://thirdwx.qlogo.cn/…",
      "wechatName": "…"
    }
  },
  "detail": "",
  "message": "ok",
  "time": "2026-09-06 11:51:31"
}

响应字段

响应字段（19 项）

字段	类型	说明
code	int64	统一封套状态码：0=成功，负数=失败
data	object	业务数据
data.uuid	string	二维码会话标识（getQr 返回，checkQr 必带）
data.authId	int64	企业对本设备的授权 id
data.corpId	int64	所属企业唯一 id
data.status	int64	登录状态，取值见上方说明
data.nickName	string	昵称
data.nonceKey	string	登录随机密钥（凭证，勿外泄）
data.avatarUrl	string	头像 url
data.corpUserId	int64	用户在企业内的成员 id
data.deviceUuid	string	设备唯一标识（登录凭证）
data.corpLogoUrl	string	企业 logo url
data.scannerNonce	string	扫码方随机串（登录凭证）
data.WxUserProfile	object	扫码者的微信侧资料（头像/昵称等）
data.WxUserProfile.avatarUrl	string	头像 url
data.WxUserProfile.wechatName	string	微信昵称
detail	string	附加明细，通常为空
message	string	文案：成功为 ok；失败形如 -码|描述
time	string	服务端处理时间 YYYY-MM-DD HH:MM:SS

常见错误

下表为企微错误码。业务失败时顶层 code=-1，具体错误码在 message 的 | 前，例如 -3004|参数错误；鉴权与网关错误见错误码。

错误码	含义	怎么办
-12006	checkQr 没带 uuid	带上 getQr 返回的 uuid
-12007	二维码过期	重新 getQr

下一步

• 再调：提交验证码（status 为 10 时才需要；其余状态继续轮询本接口）
• 登录模块总览
• 错误码
• 快速开始