微信第三方平台五级凭据链排障:先看 ticket 落库时间,再查签名
第三方平台(服务商)的代调用报错,绝大多数不是加解密或签名问题,而是链条上某一级凭据过期、丢失或传错。这条链上的六个凭据由五次换取动作连接起来,任何一级断开,最终都会变成 40001 invalid credential 这类含糊的报错。下面按从源头到末端、再从时间戳到签名的顺序梳理。
官方文档:
五级链与各自的有效期
| 凭据 | 有效期 | 换取方式 |
|---|---|---|
component_verify_ticket | 12 小时 | 微信每 10 分钟 POST 推送 |
component_access_token | 2 小时 | ticket + 平台 appid/secret |
pre_auth_code | 1800 秒 | component_access_token |
authorization_code | 600 秒(回调 expires_in=600) | 商家扫码授权后回调返回 |
authorizer_refresh_token | 长期,商家不解除授权就一直有效 | authorization_code 换取 |
authorizer_access_token | 7200 秒 | authorizer_refresh_token 换取 |
排障时只需先问一句:出问题的是哪一级,它现在几点入库的。
component_verify_ticket:收下来就直接落库
第三方平台创建审核通过后,微信服务器会每 10 分钟向「授权事件接收 URL」POST 一次 ticket。推送参数里 InfoType 固定为 component_verify_ticket,CreateTime 是秒级时间戳,ComponentVerifyTicket 解密后是 XML。接收端处理完直接返回字符串 success,不要包 JSON、不要加额外字段,返回体不对会被当成接收失败。
ticket 的有效期是 12 小时,比 component_access_token 的 2 小时长。这个差异是兜底设计的依据:保存最近一次可用的 ticket,在 component_access_token 过期前都可以拿它去更新,避免因为某一轮推送接收失败就彻底无法换取 token。
因此不要用「新值覆盖旧值」的逻辑,而应保留最近可用的那条并记录接收时间。
第一现场:拉不到 component_access_token
遇到 api_component_token 失败,先查 ticket 的落库时间,不要先去翻签名代码。
多实例部署时,如果 ticket 只保存在进程内存,重启一次就全丢;新实例没收到推送前又拿不到 token,整个平台的代调用会集体报 40001。这类故障的特征是:所有商家同时失败,重启后一段时间自行恢复,随后又复发。
curl -s -X POST "https://api.weixin.qq.com/cgi-bin/component/api_component_token" \
-H "Content-Type: application/json" \
-d '{"component_appid":"wxCOMPONENT_APPID","component_appsecret":"SECRET","component_verify_ticket":"TICKET"}'
拿库里的 receive_time 和当前时间比对,超过 12 小时基本可以确定是推送没收到或没落库,再去查回调 URL 是否可达、返回体是否合规。
pre_auth_code 与授权链接参数
pre_auth_code 有效期 1800 秒,用于生成扫码授权二维码或链接,属于一次性凭据,不要缓存起来复用给多个商家。
自建授权链接的必填参数是 component_appid、pre_auth_code、redirect_uri、auth_type,可选 biz_appid、category_id_list。auth_type 取值:
- 1 仅公众号
- 2 仅小程序
- 3 公众号和小程序都展示
- 4 小程序推客
- 5 视频号
- 6 全部
- 8 带货助手
biz_appid 用于指定唯一授权账号,指定后只有该 appid 的管理员能完成授权。它和 auth_type 冲突时 biz_appid 优先级更高:例如传了 auth_type=1 但 biz_appid 是小程序,会按 auth_type=2 处理。这类「参数写了但没生效」的问题,基本都是这里。
H5 链接形态:
https://open.weixin.qq.com/wxaopen/safe/bindcomponent?action=bindcomponent&no_scan=1&component_appid=xxxx&pre_auth_code=xxxxx&redirect_uri=xxxx&auth_type=xxx&biz_appid=xxxx#wechat_redirect
平台未全网发布时,还要先把测试公众号或小程序加入「授权测试公众号/小程序列表」,否则扫码端直接拒绝。
authorization_code 换 refresh_token
商家授权后回跳 redirect_url?auth_code=xxx&expires_in=600,这个 code 只有 600 秒。要在窗口内用 component_access_token 调 api_query_auth 换取 authorizer_refresh_token 和授权信息。
返回的 func_info 是商家实际勾选的权限集 id 列表。公众号和小程序可以只授权部分权限,所以权限判断要以接口返回为准,不能按自己页面声明的权限集算。否则会出现「接口报无权限但用户说授权了」的拉扯。
refresh_token is invalid 的两个成因
报这个错时按顺序排查,不要一开始就怀疑商家解绑。
第一,检查请求参数里的 authorizer_refresh_token 是不是 null。少数开发者在调 api_authorizer_token 时字段名写错或取值漏了,微信侧收到空值,返回的却是「token 无效」。用开放平台 API 调试工具看微信侧实际收到的请求参数,一分钟就能排除。
第二,确认传了值仍然报错,说明 token 真的失效了。此时调 getAuthorizerList 拉回所有已授权账号的 refresh_token。如果列表里某个账号的 refresh_token 返回空,说明它授权过但当时没及时换 token(比如回调处理超时、服务重启丢了上下文),需要补调 getAuthorizerRefreshToken 换取。如果授权码本身已经过期,就只能触发更新授权,让商家重新扫码,没有服务端补救途径。
另外,authorizer_refresh_token 长期有效的前提是商家不解除授权;一旦解绑后重新授权,refresh_token 会变,旧值直接失效,落库时整行覆盖。
IP 白名单:token 都对还报错,先看出口 IP
所有第三方平台 API 调用都校验调用者 IP,只有在第三方平台白名单 IP 列表内的 IP 才能合法调用,其余一律拒绝。
这一条在服务迁移时最容易踩:服务从自建机房搬到云上,出站走 NAT 网关的弹性 IP,白名单还停留在老地址,于是 token 全部正常、权限集也正常,但每个接口都失败。排查时先核对当前机器的公网出口 IP(curl ifconfig.me 之类),再去开放平台后台比对白名单,别在代码里找。
错误码只认文档写法
40001:invalid credential,access_token is invalid or not latest40013:invalid appid89000:account has bound open(开放平台账号已绑定)89001:not same contractor(主体不同)
注意后两个属于开放平台账号绑定接口(/cgi-bin/open/create、/bind、/unbind、/get),不在 ticket-token 这条链上。看到 89000/89001 却去翻刷新令牌的代码,方向就错了。
落库与缓存
ticket 和 refresh_token 都必须持久化,且多实例共享。最小表结构:
CREATE TABLE wx_component_ticket (
app_id VARCHAR(64) NOT NULL COMMENT '第三方平台 appid',
ticket VARCHAR(512) NOT NULL,
create_time INT NOT NULL COMMENT '微信推送的 CreateTime(秒)',
receive_time INT NOT NULL COMMENT '本地落库时间(秒)',
PRIMARY KEY (app_id),
KEY idx_receive (receive_time)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
CREATE TABLE wx_authorizer_token (
authorizer_appid VARCHAR(64) NOT NULL,
refresh_token VARCHAR(512) NOT NULL,
access_token VARCHAR(512) DEFAULT NULL,
access_expire_at INT DEFAULT NULL COMMENT '绝对过期时间(秒)',
update_time INT NOT NULL,
PRIMARY KEY (authorizer_appid)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
token 缓存建议按绝对过期时间存,刷新提前量留 5–10 分钟,不要等 expires_in 走完再换。多个实例同时发现过期会并发刷新,加个分布式锁或让单个实例负责刷新、其他实例读缓存,能避免互相把对方的 token 顶掉——access_token is not latest 这类报错往往就是这么来的。
这条链上的故障,八成出在「凭据存在哪」和「它几点入库」两个问题上,跟加解密关系不大。把 ticket 和 refresh_token 放进共享存储,把接收时间一并记下来,剩下的基本是查表。