登录账号与网络设置

第一次使用，按快速开始在控制台扫码登录。需要选择登录网络、查找账号的 appid 或处理掉线时，再看本页对应说明。

一个实例对应一个登录的企微账号，appid 就是这个实例的 ID，形如 we_xxxxxxxxxxxxxxx。调用接口时，在请求体中填写 appid，指定要操作哪个账号；首次获取二维码时不传，由系统创建实例。appid 与联系人、群 ID 的区别见常用 ID 说明。

登录网络怎么选

登录时，需要选择通过哪个地区的网络连接企微，接口里称为「代理」。选择与手机企微常用登录地相同的省份，从下面三种方式中选一种即可。

你想怎么连接	填哪个参数	填什么
按省份使用系统提供的网络	region	省份编号 "1" 到 "31"，编号见下方对照表
使用自己已有的代理	socks5	你的 socks5 代理地址，出口须在同一省份
使用自己的电脑、手机或服务器所在网络	aid	Aid 工具显示的 6 位编号，见下方使用方法

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

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

• 这三个参数只在获取二维码时选择一个填写。后续查询扫码进度、提交验证码和断线重连会沿用，不用重复填写。
• 其他业务接口不用填写 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。登录完成前保持工具运行，编号只提供给需要使用这台设备网络的人。

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

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

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

保存账号 ID

appid 用来指定你登录的企微账号。第一次取码时，保存返回的 data.appid；以后发消息、查资料或重新登录，都用这个值。找不到时，可以在企业微信控制台的实例页查看。

你要做什么	调哪个接口	注意什么
第一次扫码	获取二维码	不传 appid，保存返回的 data.appid；之后取码必须带原值。账号在线时不要再取码
确认是否登录成功	检测二维码	由账号持有人本人扫码，查到 data.status=2 才算成功；只有返回 10 时，才需提交验证码后继续查询
确认登录的是谁	获取个人信息	返回当前账号的 uin。在其他设备登录后被挤下线、重新扫码时，用它核对还是原账号
退出账号	退出登录	会解除登录，只在确定要退出时调用

同一个企微账号一直用原来的 appid

不要给同一个账号更换 appid，也不要把另一个账号登录到这个 appid 上，乱换或绑错有封号风险。扫码必须由账号持有人本人完成；Eyun 不代持、不代扫、不托管账号。

掉线检测与恢复

先看你是在哪里发现掉线的：

• 调用接口时报错：响应 code=-1，具体错误码在 message 的竖线前，例如 -11002|你已在其他设备上登录。
• 收到掉线通知：事件名为 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 重新取码扫码。

登录失败时先查什么

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

登录多个账号

一个应用可以登录多个企微账号，使用同一个 App Token、不同的 appid。每个账号的登录和掉线状态互不影响。在自己的数据库里，记录每个 appid 对应哪个门店、销售组或客服组，调用时选择对应账号。