获取二维码

为指定设备取一张登录二维码，并开启一次扫码会话（返回 uuid）。

说明与注意

• 响应里的 uuid 在检测二维码时要带上；imageBase64 是 JPEG 图片的 base64，refreshInterval 是二维码有效秒数。
• 代理三选一：region 省份编号、socks5 自定义代理、aid 本地代理编号。新建实例必须传其中一个，否则报 proxy_required；已有实例不传则沿用上次的代理，代理会缓存在实例上供后续接口使用。
• 只有第一次取码不传 appid；之后每次取码都必须带上原来的 appid。
• 一个企微账号只对应一个 appid：不要给同一个账号换 appid，也不要把账号登到别的 appid 上，乱换或绑错有封号风险。
• 实例在线时不要再取码。

请求参数

参数	必填	类型	说明
appid	首次后必填	string	第一次取码不传；之后每次取码都必须带上原来的 appid，新实例的 appid 在响应 data.appid 返回
region	三选一	string	省份编号 1-31，与手机企微常用登录省份一致，编号见实例与代理。示例：7
socks5	三选一	string	自定义 socks5 代理地址，出口须在同一省份
aid	三选一	string	Aid 本地代理的 6 位编号，见实例与代理

请求示例

HTTP

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

{
  "region": "7"
}

curl

curl -X POST '{BASE_URL}/wx-api/api/login/getQr' \
  -H 'Authorization: Bearer <你的 App Token>' \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "region": "7"
}'

Python

import requests

url = "{BASE_URL}/wx-api/api/login/getQr"
headers = {"Authorization": "Bearer <你的 App Token>", "Content-Type": "application/json"}
body = """{
  "region": "7"
}"""

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/getQr";
String body = "{\n" +
    "  \"region\": \"7\"\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/getQr';
$body = <<<'JSON'
{
  "region": "7"
}
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": {
    "imageBase64": "/9j/4AAQSkZJRgABAQEASABIAAD/2wBDABQODxIP...(JPEG base64,约 57KB)",
    "uuid": "61AC3F0E49D4A74A3CF5A3D4A53C6099",
    "refreshInterval": 600,
    "appid": "we_自动创建或复用的设备appid"
  },
  "detail": "",
  "message": "ok",
  "time": "2026-09-06 11:11:26"
}

响应字段

响应字段（9 项）

字段	类型	说明
code	int64	统一封套状态码：0=成功，负数=失败
data	object	业务数据
data.imageBase64	string	登录二维码图片的 JPEG base64（约 57KB）；前端用 data:image/jpeg;base64,<该串> 直接渲染
data.uuid	string	二维码会话标识（getQr 返回，checkQr 必带）
data.refreshInterval	int64	二维码有效期 / 刷新间隔，单位秒；600 = 10 分钟，超时需重新 getQr
data.appid	string	设备 appid（自动创建时在此返回）
detail	string	附加明细，通常为空
message	string	文案：成功为 ok；失败形如 -码|描述
time	string	服务端处理时间 YYYY-MM-DD HH:MM:SS

下一步

• 再调：检测二维码
• 登录模块总览
• 错误码
• 快速开始