服务端 API 概览

阅读指引：本篇是《开放平台服务端 API 指南》的总览。本套文档共 12 篇（本篇为总览），本篇说明平台可用能力与各接口请求限制总表。

文档目录

编号说明：各篇标题编号沿用原《开放平台应用开发者指南》章节编号（如「9.3 文本消息」），正文中「N.N 节」「第 N 章」均指原指南对应位置，跨篇引用时对照上表即可。

文档版本

第三方接入正式稿 · 2026-09-13。面向服务号应用后端与 H5 开发者，完整说明应用凭据、OAuth2、OpenAPI、发布范围、组织与群应用可靠同步、素材、消息、Webhook 与 JSSDK。接口字段、调用流程与错误处理以本文为准；客户端 SDK 安装包及适配版本由平台接入方交付。

按任务查找

首次接入：创建应用 → 确认权限 → 获取应用 Token / 用户授权 → 选择业务接口 → 上线前检查（错误处理与安全清单）。Token 类型取决于目标接口。

• 接入准备：可用能力（本篇）、创建应用与获取凭据
• 认证与授权：权限与 Scope、应用 Token、H5 用户授权、JSSDK 用户授权、发布范围
• 用户与组织：当前授权用户信息与头像、组织目录同步、群应用与群成员同步
• 消息与素材：发送应用消息、模板卡片、代发消息、消息去重重试、素材上传下载
• 事件与回调：Webhook 验签、用户消息、卡片操作、组织与群变化、媒体下载、重试幂等
• 客户端 JSSDK：config 初始化与签名、closeWindow、openChat、JSSDK 错误码
• 接口参考：请求限制总表（本篇）、Scope 与接口映射、错误处理与安全清单

1. 可用能力

本文说明第三方服务号应用的公开接入契约。HTTP 接口须使用平台交付的服务地址；JSAPI 须运行在平台提供的兼容客户端与 SDK 中。应用取得凭据及 Scope 后，还须满足各接口的授权、发布范围、群绑定或客户端条件。

OAuth2应用 Token、用户授权 code、用户 Token、刷新和撤销。

用户资料读取当前授权用户资料，以及下载短期头像资源。

应用素材上传文件、语音、视频和图片，下载当前应用原始素材。

消息发送应用自身向用户、组织节点、全员或单个已绑定群发送消息，支持文本、素材、普通卡片和可回传菜单点击的模板卡片；也可在用户授权后向用户或群代发。

组织目录读取授权组织、成员与人员详情，并通过同步 Token 判断是否需要全量同步。

群应用群主或管理员添加应用后，应用可以同步该群及成员，并以应用身份向该群发送消息。

Webhook 事件URL 验证、用户消息、模板卡片菜单操作、组织目录与群应用变化通知、请求签名和短期媒体下载。

JSSDKready、error、getAuthCode、config、closeWindow、chooseChat 和 openChat。

重置 app_secret 时的操作要求重置会撤销该应用已经签发的应用 Token 和用户 Token。为避免仍在执行的旧凭据请求返回不可继续使用的 Token，轮换时应先暂停应用后端的换 Token 和刷新请求，完成重置及新密钥配置后再恢复，并丢弃所有使用旧 app_secret 发起的请求结果。

基础地址{OPENAPI_BASE_URL}/openapi/v1，例如 https://openapi.example.com/openapi/v1。

3.1 每个 HTTP 接口的请求限制

两类限制必须同时满足请求速率限制控制调用频率；请求规则限制 Token 类型、Scope、目标语义、参数、大小和资源边界。通过其中一类检查不代表请求一定合法。

所有 /openapi/v1/* 请求首先共享来源 IP 每分钟 300 次的全局固定窗口限制。下表“专用请求速率”在全局限制之外叠加；“无”仅表示没有额外接口级额度。同一出口 IP 的多个应用共享全局额度；不要通过切换连接或访问地址规避限制。各专用接口分别计数，同一发送接口的四种目标共享发送额度。命中全局限流时返回 HTTP 200、业务码 170108；消息、JSSDK 等专用限流同样返回 HTTP 200、170108；只有素材接口自身的专用限流返回 HTTP 429、170507。