# 服务端 API 调用说明

本文档主要介绍如何调用服务号的 API。

# 获取 AppID 和 AppSecret

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

操作路径为：「微信开发者平台 - 扫码登录 - 我的业务 - 服务号」，点击后即可进入到服务号的管理页面

其中开发者可在此处直接修改 AppSecret 、API IP 白名单信息、JS接口安全域名以及消息推送的配置

# AppSecret 管理

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

如长期无AppSecret的使用需求，开发者可以使用管理员账号登录公众平台，在“设置与开发-基本配置”中对AppSeceret进行冻结，提高账号的安全性。

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

开发者可以随时使用管理员账号登录公众平台，在“设置与开发-基本配置”中对AppSecret进行解冻。

如果secret被冻结了调用getAccessToken 会出现 40243 错误

「微信云托管」具有「免鉴权调用微信开放服务接口」特性的能力，免密钥，全程不暴漏任何信息，开发者无需维护access_token，那对于接口请求的合法性判定，完全由与微信同链路的微信云托管参与实施，具体可前往云托管文档。（如你使用云托管的云调用，则不需要后续生成 Access Token 过程，也无需配置 IP 白名单）

# IP 白名单

即白名单内的 IP 才可以调用获取接口调用凭据接口或获取稳定版接口调用凭据接口，否则会提示 61004 错误

# 生成 Access Token

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

获取的 Access Token 可用于服务端 API 的调用。

以下是一些注意事项：

access_token的有效期目前为2个小时，需定时刷新，重复获取将导致上次获取的access_token失效。建议服务号开发者使用中控服务器统一获取和刷新access_token，其他业务逻辑服务器所使用的access_token均来自于该中控服务器，不应该各自去刷新，否则容易造成冲突，导致access_token覆盖而影响业务；
目前access_token的有效期通过返回的expires_in来传达，目前是7200秒之内的值。中控服务器需要根据这个有效时间提前去刷新新access_token。在刷新过程中，中控服务器可对外继续输出的老access_token，此时公众平台后台会保证在5分钟内，新老access_token都可用，这保证了第三方业务的平滑过渡；
access_token的有效时间可能会在未来有调整，所以中控服务器不仅需要内部定时主动刷新，还需要提供被动刷新access_token的接口，这样便于业务服务器在API调用获知access_token已超时的情况下，可以触发access_token的刷新流程。
access_token是服务号的全局唯一接口调用凭据，服务号调用各接口时都需使用access_token。开发者需要进行妥善保存。
access_token的存储至少要保留512个字符空间。

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

中控服务器定时（建议1小时）调用微信api，刷新access_token,将新的access_token 存入存储；
其他工作服务器每次调用微信api时从mysql(或其他存储)获取access_token，并可在内存缓存一段时间（建议1分钟）；

对于可能存在风险的调用，在开发者进行获取 access_token 调用时进入风险调用确认流程，需要用户管理员确认后才可以成功获取。具体流程为：

开发者通过某IP发起调用->平台返回错误码[89503]并同时下发模板消息给服务号管理员->服务号管理员确认该IP可以调用->开发者使用该IP再次发起调用->调用成功。
如服务号管理员第一次拒绝该IP调用，用户在1个小时内将无法使用该IP再次发起调用，如服务号管理员多次拒绝该IP调用，该IP将可能长期无法发起调用。平台建议开发者在发起调用前主动与管理员沟通确认调用需求，或请求管理员开启IP白名单功能并将该IP加入IP白名单列表。

服务号调用各接口时，一般会获得正确的结果，具体结果可见对应接口的说明；返回错误时，可根据返回码来查询错误原因，返回码解释一般在各个接口的文档中有描述，如无特意描述，可直接参考全局返回码

# 接口域名

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

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

通用域名(api.weixin.qq.com)，使用该域名将访问官方指定就近的接入点；
通用异地容灾域名(api2.weixin.qq.com)，当上述域名不可访问时可改访问此域名；
上海域名(sh.api.weixin.qq.com)，使用该域名将访问上海的接入点；
深圳域名(sz.api.weixin.qq.com)，使用该域名将访问深圳的接入点；
香港域名(hk.api.weixin.qq.com)，使用该域名将访问香港的接入点。

# 接口限频

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

# 问题排查

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

你也可以在微信开放社区发帖提问