开放平台
取消
开发者平台
中文
EN
取消
  • 平台指南

    • # 服务端 API 调用说明

    本文档主要介绍如何调用微信开发生态服务端的 API，包括获取 AppID 和 AppSecret、生成 access_token、接口域名选择以及调用额度等。

    # 1、获取 AppID 和 AppSecret

    微信开发者平台已支持管理大部分业务的基本信息、开发信息以及绑定关系和授权关系。

    操作路径

    进入管理页面后，开发者可在此处直接修改 AppSecret、API IP 白名单信息、JS 接口安全域名以及消息推送的配置（不同业务的设置信息会有不同）。

    # 2、AppSecret 管理

    支持启用、重置、冻结以及解冻的操作，其中冻结与解冻的操作需 10 分钟后方可生效。

    如长期无 AppSecret 的使用需求，开发者可对 AppSecret 进行冻结，提高账号的安全性。

    AppSecret 冻结后，开发者无法使用 AppSecret 获取 access_token（接口返回错误码 40243），不影响账号基本功能的正常使用，不影响通过第三方授权调用后台接口，不影响云开发调用后台接口。

    业务名称 AppSecret 管理功能 操作路径
    小程序 启用、重置、冻结、解冻 微信公众平台 - 微信扫码并选择小程序登录 - 管理 - 开发管理 - 开发设置
    小游戏 启用、重置、冻结、解冻 微信公众平台 - 微信扫码选择小游戏登录 - 管理 - 开发管理 - 开发设置
    公众号 启用、重置、冻结、解冻 微信开发者平台 - 微信扫码登录 - 我的业务 - 公众号 - 基础信息 - 开发密钥
    服务号 启用、重置、冻结、解冻 微信开发者平台 - 微信扫码登录 - 我的业务 - 服务号 - 基础信息 - 开发密钥
    移动应用 启用、重置 微信开放平台 - 邮箱账号密码登录 - 管理中心 - 移动应用 - 详情
    网站应用 启用、重置 微信开放平台 - 邮箱账号密码登录 - 管理中心 - 网站应用 - 详情
    第三方平台 启用、重置 微信开放平台 - 邮箱账号密码登录 - 管理中心 - 第三方平台 - 详情
    多端应用 启用、重置 微信开发者平台 - 微信扫码登录 - 我的业务 - 多端应用 - 应用概览
    微信小店 启用、重置 微信小店平台 - 微信扫码选择小店账号登录 - 服务市场 - 经营工具 - 我的服务 - 自研
    小店带货助手 启用、重置 微信开发者平台 - 微信扫码登录 - 我的业务 - 带货助手 - 基础信息 - 开发密钥
    联盟带货机构 启用、重置 联盟带货机构管理平台 - 微信扫码选择联盟带货机构账号登录 - 设置 - 开放信息
    视频号助手 启用、重置 视频号助手 - 微信扫码登录 - 直播 - 直播管理 - 开放能力

    # 3、API IP 白名单

    业务名称 API IP 白名单功能描述 操作路径
    小程序 开启后只有白名单内的 IP 可以调用参数为 AppSecret 的接口 微信公众平台 - 微信扫码并选择小程序登录 - 管理 - 开发管理 - 开发设置
    小游戏 开启后只有白名单内的 IP 可以调用参数为 AppSecret 的接口 微信公众平台 - 微信扫码选择小游戏登录 - 管理 - 开发管理 - 开发设置
    公众号 只有白名单内的 IP 可以调用服务端 API（不局限于参数为 AppSecret 的接口） 微信开发者平台 - 微信扫码登录 - 我的业务 - 公众号 - 基础信息 - 开发密钥
    服务号 只有白名单内的 IP 可以调用服务端 API（不局限于参数为 AppSecret 的接口） 微信开发者平台 - 微信扫码登录 - 我的业务 - 服务号 - 基础信息 - 开发密钥
    移动应用 暂未支持配置 API IP 白名单 /
    网站应用 暂未支持配置 API IP 白名单 /
    第三方平台 只有白名单内的 IP 可以调用服务端 API（不局限于参数为 AppSecret 的接口） 微信开放平台 - 邮箱账号密码登录 - 管理中心 - 第三方平台 - 详情
    多端应用 暂未支持配置 API IP 白名单 /
    微信小店 开启后只有白名单内的 IP 可以调用参数为 AppSecret 的接口 微信小店平台 - 微信扫码选择小店账号登录 - 服务市场 - 经营工具 - 我的服务 - 自研
    小店带货助手 开启后只有白名单内的 IP 可以调用参数为 AppSecret 的接口 微信开发者平台 - 微信扫码登录 - 我的业务 - 带货助手 - 基础信息 - 开发密钥
    联盟带货机构 开启后只有白名单内的 IP 可以调用参数为 AppSecret 的接口 联盟带货机构管理平台 - 微信扫码选择联盟带货机构账号登录 - 设置 - 开放信息
    视频号助手 开启后只有白名单内的 IP 可以调用参数为 AppSecret 的接口 视频号助手 - 微信扫码登录 - 直播 - 直播管理 - 开放能力

    说明

    • 第三方平台账号：如果启用了 API IP 白名单，未在白名单内调用接口，返回的错误码是 61004
    • 其他账号，则返回的是 40164 错误码

    # 4、生成 access_token

    参考获取接口调用凭据接口或获取稳定版接口调用凭据，传入上一步获取的 AppID 和 AppSecret 获取 access_token，两者都可以正常获取，推荐使用稳定版接口。

    获取的 access_token 可用于业务「服务端 API」的调用。

    以下是一些注意事项：

    1）access_token 的有效期目前为 2 个小时，需定时刷新，重复获取将导致上次获取的 access_token 失效。建议开发者使用中控服务器统一获取和刷新 access_token，其他业务逻辑服务器所使用的 access_token 均来自于该中控服务器，不应该各自去刷新，否则容易造成冲突，导致 access_token 覆盖而影响业务。

    2）目前 access_token 的有效期通过返回的 expires_in 来传达，目前是 7200 秒之内的值。中控服务器需要根据这个有效时间提前去刷新新 access_token。在刷新过程中，中控服务器可对外继续输出的老 access_token，此时公众平台后台会保证在 5 分钟内，新老 access_token 都可用，这保证了第三方业务的平滑过渡。

    3）access_token 的有效时间可能会在未来有调整，所以中控服务器不仅需要内部定时主动刷新，还需要提供被动刷新 access_token 的接口，这样便于业务服务器在 API 调用获知 access_token 已超时的情况下，可以触发 access_token 的刷新流程。

    4）access_token 是全局唯一接口调用凭据，调用各接口时都需使用 access_token。开发者需要进行妥善保存。

    5）access_token 的存储至少要保留 512 个字符空间。

    这里提供一个较为简单的 access_token 存储和使用方案：

    1）中控服务器定时（建议 1 小时）调用微信 API，刷新 access_token，将新的 access_token 存入存储。

    2）其他工作服务器每次调用微信 API 时从 MySQL（或其他存储）获取 access_token，并可在内存缓存一段时间（建议 1 分钟）。

    # 5、接口域名

    开发者可以根据自己的服务器部署情况，选择最佳的接入域名（延时更低，稳定性更高）。

    除此之外，可以将其他接入域名用作容灾用途，当网络链路发生故障时，可以考虑选择备用域名来接入。请开发者使用域名进行 API 接口请求，不要使用 IP 作为访问。若有需要开通网络策略，开发者可以从获取微信服务器IP地址接口定期获取最新的 IP 信息。

    1）通用域名（api.weixin.qq.com），使用该域名将访问官方指定就近的接入点。

    2）通用异地容灾域名（api2.weixin.qq.com），当上述域名不可访问时可改访问此域名。

    3）上海域名（sh.api.weixin.qq.com），使用该域名将访问上海的接入点。

    4）深圳域名（sz.api.weixin.qq.com），使用该域名将访问深圳的接入点。

    5）香港域名（hk.api.weixin.qq.com），使用该域名将访问香港的接入点。

    # 6、接口调用额度

    微信开发生态服务端的 API 并不是无限制的。为了防止程序错误而引发微信服务器负载异常，默认情况下，每个接口都不能超过一定限制，具体可参考各个业务的接口限频说明。

    如果出现了调用次数超过当日的可调用额度，则会出现 45009 的报错。遇到该问题时，开发者可通过以下接口重置接口调用次数，接口调用说明可查看接口文档：

    # 7、问题排查

    如果你在调用接口时遇到问题，可参考接口报警和排查指引。

    此外，调用接口遇到报错可前往微信开发者平台使用API 报错诊断工具，一键精准定位和解决问题。