本文档围绕企业微信初始化与登录相关接口展开，定义了一套基于HTTP POST协议的接口调用规范，核心服务部署于http://127.0.0.1:8083/wxwork/（单例查询接口除外），所有接口统一采用application/json请求与响应格式，以errcode=0作为操作成功的核心标识。整套接口体系以**uuid** 为实例唯一操作标识、vid为设备绑定与自动登录核心参数，实现了企业微信实例的初始化、代理管理、状态查询、登录鉴权等全流程技术操作，以下从接口协议规范、核心模块技术实现、关键参数与状态标识、核心技术规则四个维度做技术总结。
一、接口通用协议规范
- 请求层 ：所有接口均采用POST请求方法，请求体为JSON格式，要求请求头指定ContentType:application/json，确保参数解析的一致性；
- 响应层 ：响应体统一封装errcode、errmsg、data三个核心字段，errcode为数值型状态码（0表示成功，非0为异常），errmsg为状态描述文本，data为业务数据体（按需返回对象、数组或空值）；
- 地址规范 ：核心操作接口统一挂载于http://127.0.0.1:8083/wxwork/路径下，仅「根据uuid查看实例详情」接口独立部署于http://127.0.0.1:8083/wxwork/，需单独做地址适配；
- 操作粒度 ：所有实例级操作均以uuid为唯一索引，实现单实例精准操作，无参数接口（如获取运行中的实例）为全局级操作，返回全量运行态实例数据。
开发文档
功能脑图
二、核心模块技术实现
整套接口分为初始化 和登录两大核心模块，初始化是所有操作的前置技术前提，登录模块基于初始化生成的uuid实现鉴权与状态管理，模块内各接口分工明确、上下游依赖清晰。
（一）初始化模块：实例化与生命周期管理
初始化模块的核心技术目标是完成企业微信实例的创建、配置、状态查询与连接销毁，同时实现代理的动态配置与取消，为登录模块提供可用的实例载体，各接口技术要点如下：
- 实例初始化（/init） ：作为入口接口，支持设备绑定（vid）和代理预配置 两大前置能力，首次调用时vid传空，服务端自动生成新设备信息并返回uuid （实例唯一标识，生命周期内不变）；非首次调用传入16888开头的vid，可实现设备绑定与自动登录前置配置。代理配置支持proxySituation全局/非全局标识，1为全局长效代理（不可取消），0为非全局代理（可后续动态调整），代理参数（ip/port/proxyType等）支持按需传参，无代理时留空即可。
- 消息回调配置（/SetCallbackUrl） ：实现实例级消息回调的技术对接，支持HTTP 和RABBITMQ 两种回调模式，均需传入uuid指定实例。HTTP模式要求对接方搭建符合规范的POST接口，能接收uuid（实例id）、json（回调数据）、type（消息类型）三个核心参数；RABBITMQ模式需配置direct类型交换机（mqExchange）、路由键（mqRoutingKey），支持自定义额外内容（extraContent），实现消息的异步推送。
- 实例状态查询 ：提供**全局查询（/GetRunClient）和 单例查询（/GetRunClientByUuid）**两种能力，全局查询无参数，返回全量运行态实例的结构化数据，包含登录状态、设备id、用户信息、企业信息等；单例查询以uuid为入参，返回指定实例的精细化状态，核心包含loginType（实例登录状态码）、登录时间、用户与企业全量属性，为实例状态监控提供数据支撑。
- 连接管理（/CloseConnent）：实现实例连接的主动销毁，以uuid为入参，服务端接收到请求后释放该实例的相关资源，返回无数据的成功响应，适用于实例的生命周期回收。
- 代理动态配置（/setProxy） ：实现代理的后置配置与取消，以uuid为入参，支持代理参数（ip/port/proxyType等）的动态修改；技术上约定**ip=[127.0.0.1](127.0.0.1)**为代理取消标识，传入该ip时，服务端自动移除当前实例的代理配置，实现代理的灵活管控。
（二）登录模块：鉴权与状态流转
登录模块基于初始化生成的uuid实现企业微信的鉴权登录，核心实现首次手动登录 和后续自动登录两种鉴权模式，同时支持退出登录、二次验证等配套能力，实现登录状态的全生命周期流转，各接口技术要点如下：
- 登录二维码获取（/getQrCode） ：以uuid为入参，服务端生成并返回企业微信登录二维码的HTTP访问链接 和Base64位文件流两种格式，同时返回二维码有效期（Ttl=600秒）和唯一标识（Key），满足不同终端的展示需求，为扫码登录提供入口。
- 验证码验证（/CheckCode） ：作为首次登录的二次鉴权接口 ，以uuid、qrcodeKey（二维码唯一标识）、code（验证码）为必选入参，服务端验证验证码有效性后完成登录鉴权；技术上做异常拦截，若提前关闭手机验证码界面，会返回qrcode_not need verify异常码，需对接方做异常处理。
- 自动登录（/automaticLogin） ：实现基于设备绑定的免密登录，以uuid为入参，技术前提为初始化接口传入已绑定的vid，服务端通过vid匹配设备与账号的绑定关系，完成自动鉴权；若初始化未传vid，接口会执行失败，是实现后续免登的核心接口。
- 退出登录（/LoginOut）：以uuid为入参，服务端销毁当前实例的登录态，返回包含业务子状态的结构化数据（code/errMsg等），实现登录状态的主动注销，退出后需重新执行登录流程。
- 二次验证二维码获取（/SecondaryValidation）：为企业微信二次验证场景提供技术支撑，以uuid为入参，返回格式与登录二维码一致（HTTP链接/Ttl/Key），有效期600秒，实现二次验证的扫码入口。
三、关键参数与状态标识定义
整套接口体系定义了多个核心参数和状态标识，是接口调用与状态解析的技术基础，所有参数与标识均做了明确的类型和业务含义约定，避免解析歧义，核心定义如下：
（一）核心全局参数
|----------------|--------|-------------|------------------------------------|
| 参数名 | 类型 | 业务含义 | 使用规则 |
| uuid | String | 企业微信实例唯一标识 | 由/init接口生成，所有实例级操作的必选入参，生命周期内不变 |
| vid | Long | 设备绑定与自动登录标识 | 16888开头的账号id，首次/init传空，登录后传入实现设备绑定 |
| proxySituation | Int | 代理全局/非全局标识 | 0=非全局代理（可取消），1=全局代理（长效不可取消），无代理默认0 |
（二）核心状态标识
|-----------|--------|------------|-------------|---------------------------------------------|
| 标识名 | 类型 | 取值 | 业务含义 | 使用场景 |
| is_login | String | true/false | 实例初始化后的登录状态 | /init接口响应体，标识初始登录态 |
| loginType | Int | 0/1/2 | 实例精细化登录状态 | /GetRunClientByUuid接口，0=未初始化，1=初始化未登录，2=已登录 |
| errcode | Int | 0/非0 | 接口全局执行状态 | 所有接口响应体，0=成功，非0=异常 |
四、核心技术规则与约束
为保证接口调用的稳定性和数据一致性，整套接口体系制定了严格的技术规则与业务约束，对接方需严格遵循，否则会导致接口执行失败或状态异常，核心规则如下：
- 前置执行规则：初始化接口（/init）是所有接口的前置操作，未执行初始化生成uuid的情况下，调用其他实例级接口均会失败；
- uuid使用规则：uuid为实例生命周期唯一标识，一个uuid对应一个企业微信实例，所有实例级操作必须传入正确的uuid，否则会出现操作对象错误；
- 自动登录约束 ：自动登录接口（/automaticLogin）仅在初始化时传入已绑定的vid时生效，未传vid或vid无效时，接口执行失败，需重新走手动登录流程；
- 代理管控规则：全局代理（proxySituation=1）为长效配置，服务端不提供取消接口；非全局代理（proxySituation=0）可通过/setProxy接口将ip设为[127.0.0.1](127.0.0.1)实现取消，设置代理时未传proxySituation，服务端默认按全局代理处理；
- 验证码操作规则 ：首次登录的验证码验证接口（/CheckCode）需在手机验证码界面未关闭的情况下调用，提前关闭会触发qrcode_not need verify异常，需重新获取二维码并打开验证码界面；
- 二维码有效期规则：登录二维码和二次验证二维码的有效期均为600秒，超时后二维码失效，需重新调用接口获取新的二维码。
五、技术体系核心价值
这套企业微信初始化与登录接口体系，通过标准化的HTTP接口协议 、唯一的实例标识机制 、灵活的代理配置能力 、分阶段的登录鉴权模式，实现了企业微信实例的自动化、精细化管理，核心技术价值体现在三方面：
- 解耦性：将实例初始化、配置、登录、状态查询拆分为独立接口，实现各功能模块的解耦，便于对接方按需调用和功能扩展；
- 灵活性：支持代理的预配置和动态调整、两种消息回调模式、首次手动登录与后续自动登录的切换，适配不同的业务场景和技术架构；
- 可监控性：提供全局和单例的实例状态查询接口，返回精细化的实例属性和状态标识，为对接方的实例监控、问题排查提供数据支撑。
接口体系为企业微信的程序化操作提供了完整的技术入口，所有接口的参数、响应、规则均做了标准化定义，降低了对接的技术成本，同时通过严格的状态约束和参数校验，保证了接口调用的稳定性和可靠性。