# 获取稳定版AccessToken

# 接口说明

  • 可通过该接口获取视频号小店全局调用凭证access_token,同时该接口可支持设置是否为强制刷新模式;
  • 接口应在服务器端调用,详细说明参见服务端API

# 注意事项

  • 获取到的视频号小店全局后台接口调用凭据,有效期最长为7200s,开发者需要进行妥善保存;
  • 有两种调用模式:
    1. 普通模式,access_token 有效期内重复调用该接口不会更新 access_token,绝大部分场景下使用该模式;
    2. 强制刷新模式,会导致上次获取的 access_token 失效,并返回新的 access_token
  • 该接口调用频率限制为 1万次 每分钟,每天限制调用 50万 次;
  • 获取AccessToken获取的调用凭证完全隔离,互不影响。该接口仅支持 POST JSON 形式的调用;
  • 如使用云开发,可通过云调用免维护 access_token 调用;
  • 如使用云托管,也可以通过微信令牌/开放接口服务免维护 access_token 调用。

# access_token 的存储与更新

  • access_token 的存储空间至少要保留 512 个字符;
  • 建议开发者仅在access_token 泄露时使用强制刷新模式,该模式限制每天20次。考虑到数据安全,连续使用该模式时,请保证调用时间隔至少为30s,否则不会刷新;
  • 在普通模式调用下,平台会提前5分钟更新access_token,即在有效期倒计时5分钟内发起调用会获取新的access_token。在新旧access_token交接之际,平台会保证在5分钟内,新旧access_token都可用,这保证了用户业务的平滑过渡; 根据此特性可知,任意时刻发起调用获取到的 access_token 有效期至少为 5 分钟,即expires_in >= 300。

# access_token 泄露紧急处理

  • 使用强制刷新模式以间隔30s发起两次调用可将已经泄露的 access_token立即失效,同时正常的业务请求可能会返回错误码40001(access_token 过期),请妥善使用该策略。其次,需要立即排查泄露原因,加以修正,必要时可以考虑重置 appsecret

# 最佳实践

  • 在使用getAccessToken时,平台建议开发者使用中控服务来统一获取和刷新access_token。有此成熟方案的开发者依然可以复用方案并通过普通模式来调用本接口,另外请将发起接口调用的时机设置为上次获取到的access_token有效期倒计时5分钟之内即可;
  • 根据以上特性,为减少其他开发者构建中控服务的开发成本,在普通调用模式下,平台建议开发者将每次获取的access_token 在本地建立中心化存储使用,无须考虑并行调用接口时导致意外情况发生,仅须保证至少每5分钟发起一次调用并覆盖本地存储。同时,该方案也支持各业务独立部署使用,即无须中心化存储也可以保证服务正常运行。

# 接口调用请求说明

POST https://api.weixin.qq.com/cgi-bin/stable_token 

# 请求参数说明

参数 类型 是否必填 描述
grant_type string 填写 client_credential
appid string 小店唯一凭证,即 小店ID,可在「视频号小店 - 服务市场 - 经营工具 - 自研」页中获得。(需要已完成店铺开通,且账号没有异常状态)
secret string 小店唯一凭证密钥,即 小店secret,获取方式同 小店ID
force_refresh boolean 是否为强制刷新模式,默认使用false;
false:否,为普通调用模式,access_token 有效期内重复调用该接口不会更新 access_token
true:是,为强制刷新模式,会导致上次获取的 access_token 失效,并返回新的 access_token

# 请求参数示例

1、普通模式,获取当前有效调用凭证。

请求参数示例1(不传递force_refresh,默认值为false):

{
    "grant_type": "client_credential",
    "appid": "APPID",
    "secret": "APPSECRET"
}

请求参数示例2(设置force_refresh为false):

{
    "grant_type": "client_credential",
    "appid": "APPID",
    "secret": "APPSECRET",
    "force_refresh": false
} 

2、强制刷新模式,请谨慎使用,且连续使用需要至少间隔30s

请求参数示例3(设置force_refresh为true):

{
    "grant_type": "client_credential",
    "appid": "APPID",
    "secret": "APPSECRET",
    "force_refresh": true
} 

# 返回参数说明

参数 类型 描述
access_token string 获取到的凭证
expires_in number 凭证有效时间,单位:秒。目前是7200秒之内的值。

# 返回参数示例

1、普通模式

返回示例1:

{
    "access_token":"ACCESS_TOKEN",
    "expires_in":7200
}

返回示例2:

{
    "access_token":"ACCESS_TOKEN",
    "expires_in":345 
} 

2、强制刷新模式

返回示例3:

{
    "access_token":"ACCESS_TOKEN",
    "expires_in":7200
} 

# 错误码

错误码 错误码取值 错误描述
公共错误码 - -
40001 - appsecret 错误或者 appsecret 不属于这个小店,请开发者确认 appsecret 的正确性
40002 invalid grant_type 不合法的凭证类型,请开发者检查grant_type的正确性
40013 invalid appid 不合法的 AppID ,请开发者检查 AppID 的正确性,避免异常字符,注意大小写
40125 invalid appsecret 无效的appsecret,请检查appsecret的正确性
40164 invalid ip not in whitelist 将ip添加到ip白名单列表即可
41002 appid missing 缺少 appid 参数,请开发者确认是否有传递该参数
41004 appsecret missing 缺少 appsecret 参数,请开发者确认是否有传递该参数
43002 require POST method 需要 POST 请求
45009 reach max api daily quota limit 调用超过天级别频率限制。可调用clear_quota接口恢复调用额度。
45011 api minute-quota reach limit mustslower retry next minute API 调用太频繁,请稍候再试
89503 - 此次调用需要管理员确认,请耐心等候