开发前必读

阅读指引：本篇汇总开发前必须理解的核心概念与约束：部署形态、凭据体系、权限模型、标识与时间约定、限流与安全红线。理解本文后再进入具体接口文档，可避免绝大多数联调问题。

部署与接入形态

莲信以私有化部署为主，HTTP 接口须使用平台交付的服务地址，JSAPI 须运行在平台提供的兼容客户端与 SDK 中。文档中的 {OPENAPI_BASE_URL} 均为占位符，实际基础地址为 {OPENAPI_BASE_URL}/openapi/v1（例如 https://openapi.example.com/openapi/v1），以管理员交付的接入信息为准。

应用取得凭据及 Scope 后，还须满足各接口的授权、发布范围、群绑定或客户端条件。

凭据体系

重置 app_secret：每 7 天最多一次，会撤销该应用全部应用 Token 和用户 Token。轮换时应先暂停应用后端的换 Token 和刷新请求，配置新密钥后再恢复，并丢弃所有使用旧密钥发起的请求结果。

重置 sign_key：每 10 分钟最多一次，不撤销 OAuth2 Token。切换后须使用新密钥处理 Webhook 并重新验证回调；原群同步游标失效，需重新全量同步群与成员。

三类访问凭证

三者有效期均以响应 expires_in 为准并须缓存复用；jsapi_ticket 与 access_token 只能保存在应用后端。

权限模型

应用能否做一件事，由三层相互独立的配置共同决定，不能互相替代：

常用 Scope 一览（完整表见《用户授权 OAuth2》）：

权限变更后既有 access token 和 refresh token 被撤销，应用必须重新认证。应用不能根据 Scope 名称猜测接口，以文档公开入口和应用实际获授能力为准。

标识与时间约定

• 组织、群、用户 ID 在 JSON 中一律是十进制字符串。不要转换成 JavaScript Number，避免精度丢失；Token、游标、media_id、会话 ID 等按不透明字符串保存和使用，不要解析、修改或自行拼装。
• expires_in、refresh_expires_in 等相对有效期单位为秒；profile.avatar.expires_at 为 Unix 秒；Webhook 事件时间与 JSSDK config 的 timestamp 为 Unix 毫秒。
• OAuth2 Token 成功响应是顶层字段（无 code/data 包络），错误为 OAuth error 对象；其余多数接口成功响应为 code/message/data/request_id，业务判断以 code 为准，HTTP 200 不一定代表成功。

限流

• 所有 /openapi/v1/* 请求共享来源 IP 每分钟 300 次的全局固定窗口限制；命中时返回 HTTP 200、业务码 170108。
• 发送类接口另有每应用 + 来源 IP 每分钟 60 次的专用限额，同样返回 170108；素材上传的专用限流返回 HTTP 429、170507。
• 遇到限流按对应窗口退避重试，不要紧密循环重试，也不要通过切换连接或地址规避限制。

安全红线

• app_secret、sign_key、jsapi_ticket、access_token、refresh_token 不进入普通日志、埋点、前端持久缓存或客户端包体；authorization code 只在应用后端短期、一次性使用。
• 应用后端使用 HTTPS；OAuth2 流程必须校验 state，并精确复用登记的 redirect_uri。
• JSSDK 签名只能在应用后端计算，签名用的页面 URL 与调用 config 的页面 URL 必须完全一致（去掉 # 及其后部分）。
• 头像等短期 URL 不要当成永久资源地址，过期后重新获取。
• 卡片消息中的跳转与封面 URL 只能由应用后端从允许名单生成，不直接接受终端用户提交的任意 URL。
• 收到 Webhook 后先验签、按 event_id 幂等，再执行业务；普通文件附件可能包含不可信内容，不要自动执行、解压或以内联 HTML 展示。

完整安全清单见《Scope 映射与错误处理》。