13 KiB
13 KiB
企微 API 能力目录
文档状态：当前企微 API 调研与本项目使用事实源。
分类：集成事实源 / API 能力目录。
适用时间：WAPI 之后。
关联 Issue：WAPI。
最近核对：2026-05-18。
不得误读：本文只记录本项目会用到的企业微信官方 API 摘要、链接和项目决策，不复制官方文档全文，不保存 Secret、access token、完整 userid、手机号、邮箱或企微原始 payload。官方文档和企业微信后台权限配置始终是最终依据。
1. 固定规则
- 任何企微能力不清楚时，先查企业微信官方开发者文档，再进入 Issue CSV；不得在运行时代码里靠轮询多个 Secret 试错。
- 每个企微 Issue 必须明确接口路径、请求方法、Secret 来源、应用可见范围、可信 IP、回调/模板要求、读写边界、脱敏输出和
SKIP/BLOCKED_BY_EXTERNAL_CONFIG语义。 - 产品 UI 支持不等于开放 API 支持。入职、转正、离职、工资条确认、考勤确认等人事助手产品能力，只有在官方 API 明确支持并通过 POC 后才能进入自动化实现。
- 生产写接口、真实员工批量同步、企微规则写入、应急模式开启和恢复回写都必须另建合同并获得明确批准。
2. Secret 矩阵
| Secret | 当前标准用途 | 禁止或限制 |
|---|---|---|
WECOM_CONTACT_SECRET |
通讯录专用：成员 ID 清单、成员详情、部门、创建/更新/禁用成员。 | 不用于工作台消息、人事助手、打卡或审批；运行时代码不得 fallback 到 WECOM_AGENT_SECRET。 |
WECOM_AGENT_SECRET |
工作台自建应用和多数开放 API：OAuth/免登、应用消息、人事助手/花名册、打卡、审批读取。 | 不作为通讯录读取的默认 fallback；缺权限时记录阻断，不换 Secret 试错。 |
WECOM_CHECKIN_SECRET |
仅作为专用打卡应用的显式 override；为空时使用 WECOM_AGENT_SECRET。 |
不要求为了打卡重复维护 Secret；只有后台单独建打卡应用时才配置。 |
WECOM_HR_ASSISTANT_SECRET |
当前不作为标准配置，历史兼容项。 | 默认不参与人事助手读取；后续若确需启用，必须先更新本文和 Issue CSV。 |
3. 能力目录
| 能力 | 官方文档 | 关键接口 | 方法 | Secret | 当前项目状态 | 本项目使用决策 |
|---|---|---|---|---|---|---|
| 基础 token | 获取 access_token | /cgi-bin/gettoken |
GET |
按能力域选择对应 Secret | CAN_REUSE_NOW |
所有服务端 API 的前置；日志只记录 token source，不输出 token。 |
| 回调配置 | 回调配置 | 企业微信后台配置 URL、Token、EncodingAESKey | GET/POST 验证事件 |
按回调所属应用 | NEEDS_CONFIG |
考勤/审批镜像前必须先证明真实回调可达、可验签、可解密、可幂等入库。 |
| 企业微信接口 IP | 获取企业微信接口 IP 段 | /cgi-bin/get_api_domain_ip |
GET |
WECOM_AGENT_SECRET |
CAN_REUSE_NOW |
只作为运维排障和防火墙/可信 IP 核对参考。 |
| 企业微信回调 IP | 获取企业微信回调 IP 段 | /cgi-bin/getcallbackip |
GET |
WECOM_AGENT_SECRET |
CAN_REUSE_NOW |
用于回调入口放行和安全审计，不进入业务数据。 |
| 网页授权链接 | 构造网页授权链接 | connect/oauth2/authorize |
浏览器跳转 | WECOM_AGENT_SECRET 所属应用 |
CAN_REUSE_NOW |
企业微信工作台入口和 deeplink 回 OA 使用；只改变登录体验，不改变 OA 权限。 |
| 访问用户身份 | 获取访问用户身份 | /cgi-bin/auth/getuserinfo |
GET |
WECOM_AGENT_SECRET |
CAN_REUSE_NOW |
获取当前企业微信 userid 后匹配 OA 绑定；不能仅靠手机号/邮箱授权登录。 |
| 应用消息 | 发送应用消息 | /cgi-bin/message/send |
POST |
WECOM_AGENT_SECRET |
CAN_REUSE_NOW |
OA 主办审批只发脱敏标题、类型、编号、状态和 OA deeplink；不发送高敏附件。 |
| 通讯录概述 | 通讯录管理 | 通讯录成员、部门、回调和导入导出 | 混合 | WECOM_CONTACT_SECRET |
CAN_REUSE_NOW_PARTIAL |
通讯录是单独 Secret 域，和工作台应用 Secret 分开管理。 |
| 成员 ID 清单 | 获取成员 ID 列表 | /cgi-bin/user/list_id |
POST |
WECOM_CONTACT_SECRET |
CAN_REUSE_NOW |
WOUA/WHMS 全量候选必须走该接口，请求体只使用 cursor/limit，返回用户-部门关系后本地按 userid 去重；不再用旧 /cgi-bin/user/list 做全量读取。 |
| 读取成员 | 读取成员 | /cgi-bin/user/get |
GET |
WECOM_CONTACT_SECRET |
OPTIONAL_ENRICHMENT |
用于补齐 userid 对应的通讯录详情；若 list_id 与人事助手花名册可读，详情权限不足不阻断 WOUA，只降低可富化字段完整度。 |
| 获取部门成员 | 获取部门成员 | /cgi-bin/user/simplelist |
GET |
WECOM_CONTACT_SECRET |
LEGACY_NOT_DEFAULT |
仅作历史参考，当前全量读取不依赖它。 |
| 获取部门成员详情 | 获取部门成员详情 | /cgi-bin/user/list |
GET |
WECOM_CONTACT_SECRET |
LEGACY_NOT_DEFAULT |
当前部署曾返回权限错误，不再作为 WOUA/WHMS 全量入口。 |
| 获取部门列表 | 获取部门列表 | /cgi-bin/department/list |
GET |
WECOM_CONTACT_SECRET |
OPTIONAL_ENRICHMENT |
只用于部门名富化；失败不得阻断 userid 清单读取和只读对账。 |
| 创建成员 | 创建成员 | /cgi-bin/user/create |
POST |
WECOM_CONTACT_SECRET |
DONE_LIVE_VERIFIED |
已由 HRWD/HCLT 验证公网 create；仅作为管理员修复/迁移能力，不作为默认入职主流程。 |
| 更新成员 | 更新成员 | /cgi-bin/user/update |
POST |
WECOM_CONTACT_SECRET |
DONE_LIVE_VERIFIED |
仅在明确合同下做受控更新；不得静默覆盖企微资料。 |
| 删除/禁用成员 | 删除成员 | /cgi-bin/user/delete 或更新启用状态 |
GET/POST |
WECOM_CONTACT_SECRET |
DONE_LIVE_VERIFIED_FOR_DISABLE |
本项目离职默认禁用成员，不删除成员；历史业务和绑定审计保留。 |
| 人事助手概述 | 人事助手 | 字段配置、花名册读取、花名册更新 | 混合 | WECOM_AGENT_SECRET |
CAN_REUSE_NOW_FOR_READ |
人事助手产品 UI 功能很多，但当前 API 只按官方开放接口使用。 |
| 员工字段配置 | 获取员工字段配置 | /cgi-bin/hr/get_fields |
GET |
WECOM_AGENT_SECRET |
CAN_REUSE_NOW |
作为花名册字段解释和后续字段映射依据。 |
| 花名册读取 | 获取员工花名册信息 | /cgi-bin/hr/get_staff_info |
POST |
WECOM_AGENT_SECRET |
CAN_REUSE_NOW |
WHMS/WOUA 读取员工在职资料；不使用 WECOM_HR_ASSISTANT_SECRET。 |
| 花名册更新 | 更新员工花名册信息 | /cgi-bin/hr/update_staff_info |
POST |
WECOM_AGENT_SECRET |
NEEDS_API_POC_WRITE |
写接口，后续需单独低风险 POC 和人工批准；本轮不调用。 |
| 打卡概述 | 打卡 | 记录、规则、日报、月报、排班 | 混合 | WECOM_AGENT_SECRET 或显式 WECOM_CHECKIN_SECRET |
CAN_REUSE_NOW_FOR_READ_PARTIAL |
企业微信继续做原始采集和风控，OA 只读同步摘要和解释。 |
| 打卡记录 | 获取打卡记录数据 | /cgi-bin/checkin/getcheckindata |
POST |
WECOM_AGENT_SECRET 或显式 WECOM_CHECKIN_SECRET |
CAN_REUSE_NOW_FOR_READ |
已用于考勤同步 V1；不保存完整位置、人脸、设备明文或原始 payload。 |
| 员工打卡规则 | 获取员工打卡规则 | /cgi-bin/checkin/getcheckinoption |
POST |
WECOM_AGENT_SECRET 或显式 WECOM_CHECKIN_SECRET |
CAN_REUSE_NOW_FOR_READ |
可作为后续考勤解释和规则快照依据。 |
| 打卡日报/月报/排班 | 日报、月报、排班 | 官方打卡扩展接口 | POST 为主 |
WECOM_AGENT_SECRET 或显式 WECOM_CHECKIN_SECRET |
NEEDS_API_POC |
不进入当前运行优先主线；后续考勤镜像合同时再做只读 POC。 |
| 审批概述 | 审批 | 模板、实例、回调、假期 | 混合 | WECOM_AGENT_SECRET |
PARTIAL_NEEDS_CONFIG |
HR/考勤员工日常审批可优先在企微处理，但 OA 镜像尚未实现。 |
| 审批模板详情 | 获取审批模板详情 | /cgi-bin/oa/gettemplatedetail |
POST |
WECOM_AGENT_SECRET |
NEEDS_CONFIG |
需要审批模板 ID；缺模板不得进入镜像实现。 |
| 审批申请详情 | 获取审批申请详情 | /cgi-bin/oa/getapprovaldetail |
POST |
WECOM_AGENT_SECRET |
NEEDS_CONFIG |
需要测试审批单号 sp_no；不上传采购、合同、报销、发票或银行回单做测试附件。 |
| 审批状态回调 | 审批申请状态变化回调通知 | 事件回调 | POST 事件 |
WECOM_AGENT_SECRET 所属应用 |
NEEDS_CONFIG |
需要真实回调 URL、Token、EncodingAESKey、验签、解密、幂等和重试设计。 |
| 批量获取审批单号 | 批量获取审批单号 | 官方审批单查询接口 | POST |
WECOM_AGENT_SECRET |
NEEDS_API_POC |
可作为补偿拉取入口，后续镜像合同中评估。 |
| 提交审批申请 | 提交审批申请 | 官方提交审批接口 | POST |
WECOM_AGENT_SECRET |
NOT_IN_CURRENT_SCOPE_WRITE |
本项目当前不把 OA 主办报销、采购、合同、项目迁到企微原生审批。 |
| 假期余额 | 获取成员假期余额 | /cgi-bin/oa/vacation/getuservacationquota |
POST |
WECOM_AGENT_SECRET |
CAN_REUSE_NOW_OR_NEEDS_PERMISSION |
WCPC 已证明可读但历史有权限错误；后续作为考勤镜像的只读项。 |
| 审批模板创建/更新 | 创建审批模板、更新审批模板 | 官方模板写接口 | POST |
WECOM_AGENT_SECRET |
RULEOPS_LATER_WRITE |
只允许 RuleOps 后期在人工确认、前后快照和回滚建议齐全时写入。 |
4. 运行优先结论
- 近期优先利用：企业微信工作台入口、OAuth/免登、绑定、个人应用消息、OA deeplink、通讯录 userid 清单、可选成员详情、人事助手花名册读取、打卡记录和打卡规则读取。
- 暂缓深度镜像：
wecom_attendance_approval_mirror_v1、oa_hr_emergency_mode_v1、wecom_recovery_writeback_v1、wecom_ruleops_v1均等 WOUA 差异收口或 WHMS 同步窗口决策、审批模板 ID、测试sp_no和真实回调配置明确后再拆。 - OA 主办边界不变：报销、采购、费用、合同、项目、付款批次、AP、代账交接、审计和高敏附件继续在 OA 内完成，只向企业微信发送脱敏提醒和 OA 链接。
5. 后续使用要求
- 新增企微能力前，先在本文补一行能力记录，再写 Issue CSV。
- POC 输出统一使用
CAN_REUSE_NOW、NEEDS_CONFIG、NEEDS_API_POC、KEEP_OA_PRIMARY、NOT_SUPPORTED_BY_API、SKIP/BLOCKED_BY_EXTERNAL_CONFIG。 - 公网验证报告只允许输出脱敏 userid 前缀、计数、错误码、token source 和结论，不得输出 Secret、token、完整 userid、手机号、邮箱或原始 payload。