📖 API 接入与开发规范指南

开发原则：统一鉴权、复用终端、明确超时、谨慎重试、保留原始响应。先跑通最小闭环，再逐步接入复杂业务。

核心概念

名称	含义	保存建议
`wechat-token`	API 访问凭证，放在请求 Header	仅保存在服务端密钥配置中
`appId`	微信登录终端标识	与业务账号、`wxid` 建立持久化关系
`wxid`	微信账号或联系人标识	作为联系人主键之一保存
`@chatroom`	群聊 ID 的常见后缀	与群名称分开保存，避免使用群名定位
`NewMsgId`	消息唯一标识	与 `Appid` 组合用于 Webhook 去重

统一请求规范

所有接口统一使用：

推荐在服务端封装公共请求客户端，统一管理基础地址、Header、连接超时、响应日志和敏感信息脱敏，不要在每个业务模块重复拼装请求。

响应判断

不要只根据 HTTP 200 判断业务成功。建议统一执行以下判断：

HTTP 请求是否成功到达服务端；

响应是否为合法 JSON；

ret 是否表示成功；

msg 是否包含需要提示或记录的信息；

data 是否符合当前接口预期结构。

建议日志至少记录：请求路径、appId、业务耗时、HTTP 状态、ret、msg 和业务追踪 ID。Token、代理密码、完整 Base64 及敏感消息内容必须脱敏。

终端生命周期

获取二维码 → 执行登录 → 保存 appId/wxid → 检查在线 → 调用业务接口
                                      ↓ 离线
                           优先重连或复用原 appId 登录

登录成功后立即保存 appId 与 wxid 的对应关系；

同一账号再次登录时复用原 appId；

业务调用前可检查在线状态，避免对离线终端持续发送请求；

异常断线时先调用重连接口，无法恢复后再使用原 appId 重新扫码。

超时与重试

场景	处理建议
查询类接口超时	可进行有限次数重试，并使用递增等待时间
发送、创建、修改类接口超时	先查询实际结果，避免直接重试造成重复操作
返回明确业务失败	根据 `ret` 和 `msg` 处理，不要无条件重试
终端离线	停止业务重试，先恢复终端状态
Webhook 处理失败	使用队列重试，并依靠消息去重避免重复消费

任何可能产生副作用的接口都不应无限重试。建议为任务设置最大次数、总超时时间和人工介入状态。

数据与字段处理

ID、路径、Header 名称区分大小写，按照接口文档原样传递；

NewMsgId 等长整数在 JavaScript 中可能存在精度风险，建议按字符串保存或使用支持大整数的解析方式；

XML、Base64 和媒体地址应保存原始内容，需要展示时再做截断；

群名称、昵称和备注都可能变化，不要把它们当作稳定唯一标识；

Webhook 字段可能随事件类型变化，解析时允许可选字段缺失。

上线前检查

Token 只保存在服务端，日志中已脱敏；

appId 与业务账号关系已持久化；

已区分查询接口与有副作用接口的重试策略；

Webhook 已实现快速响应、去重和异步处理；

已设置超时、限流、告警和人工停止入口；

已使用测试账号完成登录、发送、接收和掉线恢复验证。

调试与常见问题

排查原则：先验证鉴权，再验证终端，随后检查业务参数和响应，最后检查 Webhook。一次只改变一个条件，便于快速确定问题位置。

标准排查路径

wechat-token → appId → 在线状态 → 请求参数 → ret/msg → 客户端结果 → Webhook

接口提示鉴权失败

请依次检查：

Header 名称是否为 wechat-token；

是否误把 appId 或其他 Token 放入 Header；

Token 前后是否包含空格或换行；

当前环境是否引用了错误的测试变量；

管理后台中的 Token 是否仍然可用。

终端显示离线

使用检查是否在线确认状态；

查看手机微信是否存在安全验证、退出或网络异常提示；

尝试调用异常断线重连；

无法恢复时，使用原 appId 重新获取二维码并完成登录；

恢复在线后，再重新执行原业务任务。

不要在终端离线时持续重试消息、好友或群操作。

接口返回成功，但客户端没有看到结果

确认 appId 对应的是预期微信账号；

确认好友使用正确 wxid，群聊使用正确的 @chatroom ID；

同时查看 HTTP 状态、ret、msg 和 data；

检查客户端是否存在缓存，可重新进入对应页面确认；

对有副作用的接口先查询实际结果，不要立即重复提交。

收不到消息回调

检查项	验证方法
地址可达	使用 Apifox 或 Postman 请求自己的回调地址
绑定关系	确认回调地址配置在当前 `wechat-token` 下
终端状态	确认产生消息的 `appId` 在线
响应时间	回调服务应在 3 秒内返回 HTTP 200
网关规则	检查防火墙、反向代理、签名校验和请求体大小限制
应用日志	记录未经修改的请求 Body 和接收时间

通过 API 主动发送的消息不会再次触发消息回调；使用手机端主动发送测试消息时会产生回调。

为什么收到重复事件？

网络重试或业务服务重复消费都可能产生重复处理。使用 Appid + Data.NewMsgId 建立唯一键，在执行业务逻辑前先完成去重。

好友、群聊或朋友圈操作受限

确认当前账号拥有所需权限，例如群公告需要群主或管理员身份；

新登录终端可能暂时受到客户端能力限制；

出现失败或安全提示后先停止任务，不要通过高频重试尝试绕过限制；

在手机端确认账号状态，必要时联系技术支持核对。

提交问题时需要什么信息？

建议一次提供以下内容：

问题发生时间；

接口路径；

脱敏后的 appId；

HTTP 状态、ret 和 msg；

脱敏后的最小请求体；

是否能够在手机端复现；

涉及 Webhook 时提供对应 TypeName 和 NewMsgId。

不要提交：完整 wechat-token、代理密码、验证码、个人隐私数据或未经脱敏的聊天内容。

核心概念#

统一请求规范#

响应判断#

终端生命周期#

超时与重试#

数据与字段处理#

推荐调试顺序#

上线前检查#

调试与常见问题#

标准排查路径#

接口提示鉴权失败#

终端显示离线#

接口返回成功，但客户端没有看到结果#

收不到消息回调#

为什么收到重复事件？#

好友、群聊或朋友圈操作受限#

提交问题时需要什么信息？#