实例与代理

本文说的实例（一个实例对应一个登录的企微账号，appid 即实例 ID），在其他页面也叫「登录设备」。appid 形如 we_xxxxxxxxxxxxxxx，操作已有实例的业务接口都在 body 里带它；首次获取二维码时不传，由系统创建实例。appid 与 uin、roomId 等其他标识的区别见核心标识。

生命周期

拿到 appid 后存进数据库；丢失时可在企业微信控制台的实例页查到。

getQr（首次不带 appid，自动创建实例）
   │
checkQr 轮询 → status 2 在线
   │
   ├─ 返回 -11001 断线     → login/reconnect
   ├─ 返回 -11002 别处登录 → 置为离线，由用户决定是否重新扫码
   ├─ 返回 -2007 已下线    → 带原 appid 重新 getQr 扫码
   └─ 主动退出             → login/logout

阶段	接口	说明
创建并取码	获取二维码	只有第一次不带 `appid`，系统自动创建实例；之后每次取码都必须带原 `appid`。实例在线时不要再取码
登录	检测二维码 → 提交验证码	需账号持有人本人扫码
确认身份	获取个人信息	取当前账号 `uin`；在其他设备登录后被挤下线、重新扫码时，用它确认登录的还是同一个账号
恢复	断线重连	收到 `-11001` 时调用
退出	退出登录	高风险，解除登录

一个企微账号只用一个 appid

只有第一次取码不传 appid；之后每次取码都必须带上原来的 appid。一个企微账号只对应一个 appid：不要给同一个账号换 appid，也不要把账号登到别的 appid 上，乱换或绑错有封号风险。

登录必须由账号持有人本人完成

Eyun 不代持、不代扫、不托管账号。

掉线检测与恢复

业务接口失败时，顶层 code=-1，下表的企微错误码从 message 的 | 前读取；instance.offline 回调则读取请求体中的 code。两者不要混用，详见错误码。

信号	从哪来	怎么处理
返回 `-11001`	任意业务接口	调断线重连
返回 `-11002`	任意业务接口	置为离线，提示「已在其他设备登录」，由用户决定是否带原 `appid` 重新获取二维码扫码
返回 `-2007`	任意业务接口	带原 `appid` 重新获取二维码，由账号持有人扫码
收到 `instance.offline`	回调推送	记录 `code` 与 `message`，按连接事件码表处理；只有 `-11001` 自动重连
定时探测	定时调用只读接口获取个人信息	返回上述码时按对应行处理

只有 -11001 可以自动重连

-11002 不要自动重连，否则会和另一台设备互相顶号、反复掉线。应置为离线，提示「已在其他设备登录」，由用户决定是否重新登录。

-11001 和 -11002 都会推送 instance.offline；仍需保留定期业务探测。
断线重连返回 code=0 只代表已经开始恢复；是否真的在线，要看之后的业务调用有没有再报 -11002 / -2007。
重连失败先确认代理（用 Aid 时确认 Aid 是否在运行），间隔几十秒以上再试；连续失败就带原 appid 重新取码扫码。

代理三选一

登录链路的出口地区必须与账号持有人手机企微常用登录的省份一致，这就是取码时必须指定代理的原因。三选一：

参数	取值	说明
`region`	`"1"` 到 `"31"`	省份编号，由系统映射到该省出口，编号见下表
`socks5`	代理地址	你自己的 socks5 代理，出口须在同一省份
`aid`	6 位数字	Aid 本地代理编号，把你的电脑、手机或服务器作为出口，见下节

代理地区必须与手机企微登录省份一致

严禁异省：异省会登录失败或很快掉线，有封号风险。

只在获取二维码传。登录成功后代理缓存在实例上，checkQr、submitQrCode、reconnect 自动沿用。
其余业务接口的 body 里如果带了 region、socks5、aid，会被网关剥离，不会生效。
已有 appid 且三者都不传：沿用上次的代理。新建实例三者都不传：报 proxy_required。

省份编号对照（region）

编号	省份	编号	省份
1	北京	17	海南
2	天津	18	四川
3	上海	19	云南
4	重庆	20	陕西
5	河北	21	黑龙江
6	山西	22	辽宁
7	江苏	23	贵州
8	浙江	24	广西
9	安徽	25	宁夏
10	福建	26	青海
11	江西	27	甘肃
12	山东	28	西藏
13	河南	29	吉林
14	湖北	30	内蒙古
15	湖南	31	新疆
16	广东

Aid 本地代理

Aid 是一个小工具，运行在你的电脑、手机或服务器上，让登录链路走你所在的网络出口。适合出口要贴近门店、办公室、家宽或同城设备的场景。

运行后界面显示 6 位 Aid 编号；取码时填入 aid；登录完成前不要退出，编号只给需要用这个节点的人。

版本	适合	怎么拿到
Windows	首次测试、客服与门店电脑，不用安装	下载 Windows 64 位 Aid 工具，解压后打开
Android	出口要贴近手机网络	下载 Android AID
Linux	需要长期在线的固定出口：同城服务器、小主机、虚拟机	一键安装后在本地后台 `http://设备IP:18080` 看编号

Linux 一键安装（已是 root 时去掉 sudo）：

bash

curl -sSL https://aid.wkteam.cn/releases/linux/install.sh | sudo bash

网关错误

错误	含义	处理
`proxy_required`	新建实例没有指定代理	三选一传一个
`appid_not_bound`	`appid` 不属于当前应用	检查 App Token 与 `appid` 的归属
`capacity_exhausted`	应用的实例容量已满	联系对接人扩容
`device_create_disabled`、`not_exposed`	调用了不对外的内部接口	只用本文档列出的接口

多实例

一个 App Token 下可以挂多个实例，各自独立登录、独立掉线。建议在你自己的数据库里把 appid 和业务主体（门店、销售组、客服组）做映射。

实例与代理 ​

生命周期 ​

掉线检测与恢复 ​

代理三选一 ​

Aid 本地代理 ​

网关错误 ​

多实例 ​