企业微信API开发：登录-联系人查询-消息发送完整开发流程分享

一、开发概述

        本文基于https://wechatapi.apifox.cn/企微 iPad 协议接口文档，聚焦账号登录流程、联系人查询、全类型消息发送三大核心链路，提供完整调用步骤、请求示例、参数说明、开发注意事项，适用于机器人、SCRM 系统企微消息自动化开发。

通用接口规范

{
  "data": {},
  "errcode": 0, // 0=成功，非0为错误码
  "errmsg": "ok"
}

二、账号完整登录流程

2.1 步骤总览

初始化实例 → 获取登录二维码 → 扫码 / 验证码登录 / 历史账号自动登录 → 登录状态校验

2.2 初始化企微实例（所有操作前置）

接口地址

POST /wxwork/init

参数说明

| 参数 | 类型 | 是否必传 | 说明 | |——|——|——–| | vid | string | 否 | 16888 开头账号 ID；首次登录传空，历史登录账号传 vid 实现免扫码 | | ip/port/proxyType | string | 否 | http 代理配置，无代理留空 | | userName/passward | string | 否 | 代理账号密码，无代理不传 | | proxySituation | int | 否 | 0 = 临时代理（可取消）；1 = 全局长效代理 | | deverType | string | 是 | 固定值ipad |

新账号首次登录请求示例（无代理）

{
    "vid": "",
    "ip": "",
    "port": "",
    "proxyType": "",
    "userName": "",
    "passward": "",
    "proxySituation": 0,
    "deverType": "ipad"
}

返回示例

{
    "data": {
        "uuid": "427d7ee5-3a1c-4183-a83b-532ba1e7a1e",
        "is_login": "false"
    },
    "errcode": 0,
    "errmsg": "ok"
}

2.3 获取登录二维码

接口地址

POST /wxwork/getQrCode

请求参数

{
    "uuid": "427d7ee5-3a1c-4183-a83b-532ba1e7a1e"
}

返回字段说明

• qrcode：二维码在线访问链接

• qrcode_data：二维码 base64 字符串，前端可直接渲染

• Key：验证码校验凭证

2.4 验证码提交（首次扫码需要）

扫码后手机弹出验证码弹窗时调用，未关闭验证码窗口前调用。

接口地址

POST /wxwork/CheckCode

请求示例

{

    "uuid":"cbba2997c55b8d8b036816e03c19e5a0",

    "qrcodeKey":"096F100D9D140448DF2973876F2E1D9F", //qr_codekey

    "code":"406269"//验证码

}

异常说明

返回qrcode_not need verify代表提前关闭验证码弹窗，需重新获取二维码。

2.5 历史账号自动登录

初始化时传入登录过的vid，无需扫码一键登录。

接口地址

POST /wxwork/automaticLogin

请求体

{
    "uuid": "427d7ee5-3a1c-4183-a83b-532ba1e7a1e"
}

2.6 辅助登录接口

三、联系人查询（获取接收人 userid）

发送消息前必须获取目标联系人send_userid，区分内部企业联系人、外部客户两套接口。

3.1 获取外部客户（微信好友）列表

接口地址

POST /wxwork/GetExternalContacts

请求示例

{
    "uuid": "427d7ee5-3a1c-4183-a83b-532ba1e7a1e",
    "limit": 100,
    "seq": 0
}

状态说明 status 字段

• 正常好友：非 0/2049/8

• 2049：对方删除我方

• 8：我方拉黑对方

• 0：双向删除

3.2 根据 userid 批量查询联系人详情

接口地址

POST /wxwork/GetUserInfoByVids

请求示例

{
    "uuid": "427d7ee5-3a1c-4183-a83b-532ba1e7a1e",
    "vids": [7881302555913738, 1688853790599424]
}

四、消息发送全流程

前置说明

4.1 ：发送纯文本消息

接口地址

POST /wxwork/SendTextMsg

请求示例（单聊）

{
    "uuid": "427d7ee5-3a1c-4183-a83b-532ba1e7a1e",
    "kf_id": 0,
    "send_userid": 7881302555913738,
    "isRoom": false,
    "content": "你好，这是测试消息"
}

返回核心

msg_id：消息唯一 ID，用于撤回、语音转文字。

4.2 文本 + 表情混合消息

接口地址

POST /wxwork/SendTextAndExpMsg

请求示例

{
    "uuid": "427d7ee5-3a1c-4183-a83b-532ba1e7a1e",
    "send_userid": 7881302555913738,
    "isRoom": false,
    "content": [
        {"msgtype":0,"msg":"早上好"},
        {"msgtype":3,"msg":"[微笑]"},
        {"msgtype":0,"msg":"今天开工啦"}
    ]
}

msgtype：0 = 文字，3 = 表情

4.3 CDN 图片消息（25M 内）

前置：调用 CDN 上传接口拿到 cdnkey/aeskey/md5

发送接口

POST /wxwork/SendCDNImgMsg

{
    "uuid": "427d7ee5-3a1c-4183-a83b-532ba1e7a1e",
    "send_userid": "7881302555913738",
    "kf_id": 0,
    "isRoom": false,
    "cdnkey": "xxx",
    "aeskey": "xxx",
    "md5": "xxx",
    "fileSize": 3243381,
    "width": 1279,
    "height": 1706,
    "thumb_image_height": 512,
    "thumb_image_width": 384,
    "thumb_file_size": 15195,
    "thumb_file_md5": "xxx",
    "is_hd": 1
}

4.4 群 @消息（群专属）

接口地址

POST /wxwork/SendTextAtMsg

请求示例（@指定成员）

{
    "uuid": "427d7ee5-3a1c-4183-a83b-532ba1e7a1e",
    "send_userid": 10696052955013024,
    "atids":[7881302555913738],
    "content":"通知全体成员开会",
    "isRoom":true
}

格式化 @（支持 @所有人）接口：SendTextAtMsgTwo，vid=0代表 @全体

4.5 高级消息类型简表

| 消息类型 | 接口地址 | 前置依赖 | |———|———| | CDN 文件 | SendCDNFileMsg | CDN 上传文件接口 | | CDN 语音 | SendCDNVoiceMsg | CDN 上传 silk 语音 | | 短视频 (<25M) | SendCDNVideoMsg | CDN 上传视频 | | 超大视频 / 文件 | SendCDNBigVideoMsg / SendCDNBigFileMsg | 大文件上传链路 | | 链接卡片 | SendLinkMsg | 无需上传，直接传 url、标题、封面 | | 小程序 | SendAppMsg | 小程序封面 CDN 资源 | | GIF 表情 | SendEmotionMessage | 图片 url | | 名片消息 | SendBusinessCardMsg | 目标用户 id | | 位置消息 | SendLocationMsg | 经纬度、地址 | | 视频号 / 直播 | SendVideoNumber / SendVideoNumberZhiBo | 视频号链接参数 | | 引用回复 | sendQuoteMsg | 原消息完整元数据 |

4.6 消息辅助操作接口

{
    "uuid": "xxx",
    "msgid":1063645,
    "roomid":0
}

五、完整业务执行流程（端到端链路）

• 新账号：获取二维码 → 扫码 → 提交验证码完成登录；

• 老账号：init 携带 vid，调用automaticLogin自动登录；

六、开发注意事项

1. 登录风控

• 二维码短时效，获取后立即渲染；

• 频繁切换设备、共用代理 IP 会触发二次验证；

• 登录后建议配置消息回调接口，实时接收回复消息。

2. 联系人使用

• 内外联系人接口不可混用；

• status 字段校验，过滤已拉黑 / 删除客户，避免消息发送失败。

3. 消息发送风控限制

• 单账号每秒发送不超过 2 条；

• 群发接口每人每日仅可推送 1 次，不可高频调用；

• 媒体消息必须完成上传再发送，缺少 cdnkey/aeskey 直接报错。

4. 缓存建议

Redis 缓存映射关系：账号vid -> uuid、uuid -> 登录状态、用户昵称-userid，减少重复查询接口调用。