阅读指引：本篇是《开放平台服务端 API 指南》的第 12 部分。接口基础地址、通用约定与各接口请求限制，请先阅读《服务端 API 概览》。
15. Scope 与接口映射
| Scope |
Channel |
入口 |
凭证/config |
状态 |
user:profile:read |
OpenAPI |
GET /openapi/v1/user/profile |
User access token |
可用 |
material:manage |
OpenAPI |
POST /openapi/v1/materials<br>GET /openapi/v1/materials/content |
App access token |
可用 |
contact:organization:read |
OpenAPI/Webhook |
GET/POST /openapi/v1/organization/*<br>organization.department.changed<br>organization.member.changed |
读取使用 App access token；通知使用 sign_key；两者都受发布范围约束 |
可用 |
| 无需额外 Scope |
Webhook/OpenAPI |
接收 message.created<br>GET /openapi/v1/messages/media/download |
Webhook 使用 sign_key；下载使用 App access token |
可用 |
chat:conversation:choose |
JSAPI |
chooseChat |
必须 config |
可用 |
chat:conversation:open |
JSAPI |
openChat |
必须 config |
可用 |
group:app |
OpenAPI/Webhook |
GET /openapi/v1/groups/changes<br>GET /openapi/v1/groups/info<br>GET /openapi/v1/groups/members<br>POST /openapi/v1/messages/send（recipient.type=group）<br>四种 group.* Webhook |
读取和发送使用 App access token；通知使用 sign_key；要求当前 Scope；目标操作要求有效群关系，移除通知描述已失效关系 |
可用 |
message:send:user |
OpenAPI |
POST /openapi/v1/messages/send |
App access token；按 recipient.type 选择 Scope |
可用 |
message:send:org_node |
OpenAPI |
POST /openapi/v1/messages/send |
App access token；按 recipient.type 选择 Scope |
可用 |
message:send:all |
OpenAPI |
POST /openapi/v1/messages/send |
App access token；按 recipient.type 选择 Scope |
可用 |
message:delegate:send |
OpenAPI |
POST /openapi/v1/messages/delegate_send |
User access token；必须是当前用户已授权的 Scope |
可用 |
16. 错误处理与安全清单
16.1 响应解析与时间单位
| 接口/字段 |
格式 |
处理 |
| oauth2/token 成功 |
顶层 access_token 等字段 |
无 code/data 包络；错误为 OAuth error 对象，另需处理全局限流业务包络。 |
| jssdk/ticket 成功 |
顶层 ticket、expires_in |
无 code/data 包络；失败为 code/message。 |
| 组织、群读取 |
code/message/data/request_id |
同时检查 HTTP 与 code；组织 sync-state 的 304 没有 body。 |
| 素材、消息、资料和撤销 |
按各接口 code/message/data 约定 |
200 不一定成功；错误响应可省略 data，空明细数组可能省略。 |
| 头像、素材和消息媒体下载成功 |
二进制 |
不要按 JSON 解析；错误按该接口约定处理。 |
| expires_in、refresh_expires_in、expiresIn |
秒数 |
相对有效期，以实际响应为准。 |
| profile.avatar.expires_at |
Unix 秒 |
头像链接到期时间。 |
| Webhook 媒体 expires_at、occurred_at、sent_at、updated_at、JSSDK timestamp |
Unix 毫秒 |
Webhook 签名 Header timestamp 为毫秒的十进制字符串。 |
| 组织、群、用户 ID |
十进制字符串 |
保持字符串，避免 JavaScript Number 精度丢失；其他标识、Token、游标按不透明字符串处理。 |
所有示例域名、密钥、ID、时间戳和 Token 都是示意值。签名请求必须使用实际页面 URL、当前时间和新随机数；历史示例时间戳不能直接用于在线调用。遇到限流请按对应秒/分钟窗口退避，并对可重试服务错误设置次数上限。
OAuth2 Token endpoint
| HTTP |
error |
处理 |
| 400 |
invalid_request |
检查重复凭证、缺失参数和请求格式 |
| 400 / 401 |
invalid_client |
检查 app_key/app_secret；使用 Basic 认证失败返回 401，否则返回 400；不要记录 secret |
| 400 |
invalid_grant |
code/refresh token 已失效、过期、已消费或绑定不一致 |
| 400 |
invalid_scope |
申请了未知或未授予 Scope |
Token endpoint 另有 HTTP 400 unsupported_grant_type（不支持的授权类型）、HTTP 500 server_error（认证服务异常）及 HTTP 429 temporarily_unavailable（认证服务限流）。命中全局 IP 限流时返回 HTTP 200、code=170108，使用业务包络，不是 OAuth error 对象。
常用业务码
| code |
含义 |
170104 |
应用 Token 无效或已过期 |
170105 |
Token 缺少接口所需 Scope |
170209 |
用户 Token 无效、过期、撤销或类型错误 |
170210 |
用户授权不足 |
170300～170320 |
JSSDK config 参数、签名、URL、应用、Scope、时间戳、重放、环境、手势或资源访问错误；H5 侧映射为第 11.6 节字符串错误码 |
170410、170411、170412、170417、170418、170419 |
应用消息请求、接收目标或消息存储发送错误；详见发送应用消息章节 |
170501～170509 |
应用素材请求、格式、大小、时长、查找、限流、处理或存储错误；详见应用素材章节 |
170610～170613 |
用户上行消息媒体下载参数无效、资源不存在、票据过期或跨应用访问 |
170700～170703 |
组织读取参数、资源、依赖服务或同步版本错误；详见第 13.9 节 |
170800～170803 |
群应用读取参数、群关系、同步重置或依赖服务错误；详见第 14.6 节 |
上线前安全清单
app_secret/sign_key/jsapi_ticket/access_token/refresh_token 不进入普通日志、埋点、前端持久缓存或客户端包体；authorization code 只在应用后端短期、一次性使用。- 应用后端使用 HTTPS，校验 OAuth2
state，并精确复用同一 redirect_uri。
- H5 只提交各接口已文档化的参数，不附加由平台识别的用户身份或运行环境参数。
- 头像短期 URL 不当成永久资源地址；过期后重新获取 profile。
- 应用素材只使用平台返回的
media_id，不猜测或拼接其他文件标识和地址。
- 普通文件按附件下载且可能包含不可信内容；应用后端不要自动执行、解压或以内联 HTML 方式展示。
- 权限或应用状态变化后，按 Token 无效处理并重新认证，不循环刷新旧 Token。
- 卡片消息中的跳转和封面 URL 只能由应用后端从允许名单生成，不直接接受终端用户提交的任意 URL。
- 群应用只保存和使用服务端返回的不透明 cursor；不能解析、修改、跨应用或跨群复用。群关系移除后立即停止读取和发送。