登录

扫码登录、验证码、断线重连、退出。

本模块接口全部 POST。{BASE_URL} 是含 /wx-api 的完整 API Base；直接复制接口页的请求示例。

接口	用途	安全级别
获取二维码 /wx-api/api/login/getQr	获取登录二维码，同时返回这次二维码的 uuid，用于后续查询扫码进度。	写操作
检测二维码 /wx-api/api/login/checkQr	查询是否已扫码、是否需要验证码以及是否登录成功；登录成功时返回当前账号信息。	写操作
提交验证码 /wx-api/api/login/submitQrCode	当 checkQr 返回 status:10（企微要求二次验证）时，提交手机端显示的 6 位验证码。	写操作
断线重连 /wx-api/api/login/reconnect	收到错误码 -11001（企微连接断开）时调用，判断账号是否仍在线并尝试恢复登录。	写操作
退出登录 /wx-api/api/login/logout	主动退出该设备当前登录的企微账号。	高风险

安全级别与「实测 日期」标记的含义见API 参考的表格说明。

如何完成扫码登录

第一次使用，先按快速开始在控制台扫码即可。只有需要在自己的产品里提供扫码登录时，再接入下面的接口。已有在线实例可以直接调用业务接口，不必重新扫码。

开始前，准备好已保存的 API 凭证（App Token）和从控制台文档中心复制的完整 API Base URL，替换示例中的 <你的 App Token> 和 {BASE_URL}。API Base 保留末尾 /wx-api。

登录时选择账号常用省份的 region，例如江苏为 7；查看省份编号或使用其他代理。由账号持有人本人扫码。

第 1 步 · 获取登录二维码

首次接入，调用获取二维码，将 region 换成你的省份编号：

curl -X POST "{BASE_URL}/api/login/getQr" \
  -H "Authorization: Bearer <你的 App Token>" \
  -H "Content-Type: application/json" \
  -d '{ "region": "<你的省份编号>" }'

已有实例时，改用下方的再次取码请求，带上原 appid；实例在线时不要再取码。

响应 code=0 后，先保存 appid 和 uuid，再显示二维码：

返回值	用途
data.appid	实例 ID，后续请求一直使用这个值；接入业务后存进数据库，丢失时可到控制台实例页查找
data.uuid	本次扫码会话，重新取码后换成新值
data.imageBase64	二维码图片的 Base64 内容，按下方方法显示

怎样显示二维码？

将下面内容保存为 qr.html，把 替换为imageBase64的完整值 换成响应中的完整 data.imageBase64，用浏览器打开文件。复制时不带 JSON 两侧的引号，也不要把登录二维码上传到在线转换网站。

<!doctype html>
<meta charset="utf-8">
<title>企微登录二维码</title>
<img alt="请用手机企业微信扫码" src="data:image/jpeg;base64,替换为imageBase64的完整值">

一个企微账号只用一个 appid

只有第一次创建实例不传 appid，之后每次取码都带原 appid。不要给同一个账号换 appid，也不要把账号登到别的 appid 上，乱换或绑错有封号风险。

已有实例、二维码过期或扫码失败：带原 appid 再次取码

二维码 600 秒过期。返回 -12007，或扫码状态为 -1、3、4 时，确认仍要登录后，用原 appid 调获取二维码：

curl -X POST "{BASE_URL}/api/login/getQr" \
  -H "Authorization: Bearer <你的 App Token>" \
  -H "Content-Type: application/json" \
  -d '{
    "appid": "<原 appid>",
    "region": "<你的省份编号>"
  }'

沿用之前的代理方式；首次使用 socks5 或 aid 时，按登录账号与网络设置替换 region，只选一种。成功后保留原 appid，保存新的 data.uuid，显示新二维码，再继续第 2 步。

第 2 步 · 查询扫码进度

让账号持有人扫码并在手机上确认。将上一步保存的 appid、uuid 填入检测二维码请求：

curl -X POST "{BASE_URL}/api/login/checkQr" \
  -H "Authorization: Bearer <你的 App Token>" \
  -H "Content-Type: application/json" \
  -d '{
    "appid": "<原 appid>",
    "uuid": "<本次 uuid>",
    "pushHistory": false
  }'

每隔 2 到 3 秒查询一次，查看 data.status。首次调试可手动重复请求。

status	下一步
0	等待扫码，继续查询
1 / 6	等待手机确认，继续查询
2	登录成功，可以发送文本消息
10	按下方说明提交验证码，再继续查询
-1 / 3 / 4	登录失效、失败或取消，按再次取码重试

status 为 10：提交 6 位验证码

将账号持有人手机企微上显示的 6 位验证码填入提交验证码请求：

curl -X POST "{BASE_URL}/api/login/submitQrCode" \
  -H "Authorization: Bearer <你的 App Token>" \
  -H "Content-Type: application/json" \
  -d '{
    "appid": "<原 appid>",
    "uuid": "<本次 uuid>",
    "code": "<手机上显示的6位验证码>"
  }'

提交后继续查询扫码状态，直到 data.status=2 才算登录成功。接入自己的系统时，为账号持有人提供验证码输入框。

请求失败或账号在别处登录，怎么办？

业务失败时，顶层 code=-1，具体错误码在 message 的 | 前：

• -12007：二维码已过期，带原 appid 再次取码。
• -12006：检查是否使用了本次取码返回的最新 uuid。
• -11002：账号在别处登录，置为离线并提示，由用户决定是否重新扫码，不要自动重连。

其他错误见错误码。

登录成功后，后续业务接口使用保存的 appid。nonceKey、deviceUuid、scannerNonce 不需要业务程序保存，也不要泄露。

扫码进度怎么看

status	含义	下一步
0	未扫码	提示用户扫码，继续查询
1 / 6	已扫码，等待手机确认	提示用户在手机上确认，继续查询
10	需要验证码	提交手机上的 6 位验证码，再继续查询
2	登录成功	停止查询，可以调用业务接口
-1	登录状态失效	带原 appid 重新获取二维码
3	登录失败	带原 appid 重新获取二维码
4	用户取消登录	用户决定继续登录时，带原 appid 重新获取二维码

登录网络与掉线处理

登录网络只在获取二维码时设置：region（省份）、socks5（自定义代理）、aid（本地代理）三选一。后续查询扫码进度、提交验证码和重连都不用再填，详见登录账号与网络设置。

掉线后先看错误码：只有 -11001 可以自动调用断线重连。-11002 表示已在其他设备登录，不要自动重连，应提示用户决定是否重新扫码。重连返回 code=0 也不等于已恢复在线，后续检查和重试方法见掉线检测与恢复。