No translation yet

开放平台

开放平台

这是一套面向外部开发者的系统文档。这里的内容重点回答三类问题：

  • 我应该先从哪里开始接入
  • 我应该如何配置应用、密钥、签名与回调
  • 当联调失败时，我应该去哪里排查

如果你要查某个具体接口的请求与响应字段，请优先打开 https://role2.api.role2.com/document/open 或 https://role2.api.role2.com/openapi?view=open。如果你要理解接入流程、调用顺序、常见问题和调试路径，请从本目录继续阅读。

No translation yet

概览

适用对象

本目录面向开放平台的外部接入方开发者，默认你需要完成服务端到服务端的应用接入、签名调用、Webhook 接收和升级维护。

文档地图

  • API 参考页：https://role2.api.role2.com/document/open
  • 过滤后的开放平台 OpenAPI：https://role2.api.role2.com/openapi?view=open
  • 动作目录：https://role2.api.role2.com/openapi/catalog
  • 迁移索引：https://role2.api.role2.com/openapi/migrations
  • OAuth 浏览器入口：https://role2.api.role2.com/oauth/authorize
  • 仓库示例：example/open/

建议阅读顺序

  1. 先看“快速开始”，用 https://role2.api.role2.com/api/1/sandbox/open__fixture_ensure 拿到一组可立即联调的 sandbox 凭证
  2. 再看“签名与鉴权”，确保本地能稳定算出与服务端一致的 canonical signature
  3. 然后用“接口查阅与调试”里的 TS 类型、Postman、HTTPie 示例缩短联调路径
  4. 若你的应用需要用户授权，再继续阅读 OAuth 相关入口，例如 https://role2.api.role2.com/oauth/authorize
  5. 最后在“Webhook”和“版本与迁移”里补齐回调消费与升级维护能力
No translation yet

快速开始

最短跑通路径

  1. 启动本地服务
  2. 打开 https://role2.api.role2.com/document/open，确认你看到的是开放平台 API 参考页
  3. 调用 POST https://role2.api.role2.com/api/1/sandbox/open__fixture_ensure 获取 sandbox owner、open app 和 secure open key
  4. 使用返回的 app_id 与 app_secret，对 POST https://role2.api.role2.com/api/1/account_session/session__read 发起第一条签名请求
  5. 如果签名不一致，使用 POST https://role2.api.role2.com/api/1/sandbox/signature__playground 对比服务端计算结果

推荐示例

  • 总入口说明：example/open/readme.md
  • TypeScript quickstart：example/open/ts-client/readme.md
  • TypeScript sample：example/open/ts-client/index.ts
  • HTTPie / curl：example/open/httpie/readme.md
  • Postman collection：example/open/postman/readme.md

为什么第一条请求推荐 account_session/session__read

这个动作能一次性验证 open app、open key、scope allowlist、secure key 验签和 canonical request 拼装是否都正常，是最适合作为首次接入健康检查的路径。

No translation yet

应用与密钥

应用与密钥的关系

  • open app 表示接入方应用本身
  • open key 表示该应用可用于签名调用的凭证
  • scope 表示该凭证被允许访问的开放动作集合

常用控制面动作

  • POST https://role2.api.role2.com/api/1/open_app/current_pick
  • POST https://role2.api.role2.com/api/1/open_app/current_update
  • POST https://role2.api.role2.com/api/1/open_key/regular_read
  • POST https://role2.api.role2.com/api/1/open_key/regular_create
  • POST https://role2.api.role2.com/api/1/open_key/regular_update
  • POST https://role2.api.role2.com/api/1/open_key/regular_rotate
  • POST https://role2.api.role2.com/api/1/open_key/regular_revoke

OAuth 相关入口

  • GET https://role2.api.role2.com/oauth/authorize
  • POST https://role2.api.role2.com/oauth/authorize
  • POST https://role2.api.role2.com/oauth/token
  • POST https://role2.api.role2.com/oauth/revoke
  • POST https://role2.api.role2.com/oauth/introspect

适用场景

  • 授权码 + PKCE：面向需要用户同意的第三方应用
  • client_credentials：面向服务端到服务端的受信调用

管理建议

  • 使用 sandbox 环境先跑通最小 scope
  • 为不同集成场景拆分不同 key，避免把所有权限放进一个凭证
  • Reveal-once secret 返回后立即保存，后续不要假设还能从读接口再次取回明文
  • 轮换 key 时优先走并行切换窗口，确认新 key 稳定后再撤销旧 key
No translation yet

签名与鉴权

必需请求头

对要求 secure key 验签的开放动作，请至少准备：

  • app_id
  • timestamp
  • nonce
  • signature

canonical request

签名不是简单的 body 签名，而是对 method、path、query、body hash 等 canonical pieces 进行规范化后统一计算。对象字段顺序、空 body 的处理方式、query 排序方式，都可能导致签名不一致。

调试工具

在非生产环境，优先使用：

  • POST https://role2.api.role2.com/api/1/sandbox/signature__playground

它会返回 method、path、query、body hash、canonical request 与最终 signature，适合用来比对你本地 SDK 或脚本的中间结果。

常见失败原因

  • timestamp 与服务器时间偏差过大
  • nonce 被重复使用
  • body 规范化方式与服务端不一致
  • 使用了错误的 app_secret
  • 调用动作需要 canonical signature，但本地只做了简化签名
No translation yet

接口查阅与调试

什么时候看哪里

  • 想看字段、schema、返回值：打开 https://role2.api.role2.com/document/open
  • 想导出 machine-readable 契约：打开 https://role2.api.role2.com/openapi?view=open
  • 想确认动作名、scope、auth-source：打开 https://role2.api.role2.com/openapi/catalog
  • 想看升级与替代关系：打开 https://role2.api.role2.com/openapi/migrations

推荐工具链

  • TypeScript 类型导出：npm run openapi:open:ts
  • Postman collection 导出：npm run openapi:open:postman
  • TS quickstart：example/open/ts-client/index.ts
  • HTTPie / curl quickstart：example/open/httpie/readme.md

canonical action 与官方快捷名

  • 成员股列表读取的 canonical action 是 POST https://role2.api.role2.com/api/1/share_team/read_by_symbol
  • 官方快捷名 alias 是 symbol_read__share_team
  • alias 与 canonical action 的入参、返回与权限语义保持一致，适合作为 SDK / Request Method 生成层的稳定映射键

调试建议

先用 https://role2.api.role2.com/document/open 确认字段，再用 TS 类型导出锁定结构，最后用 Postman 或 HTTPie 做最小复现。不要一开始就把签名、Webhook、业务逻辑同时绑在一起排查。

No translation yet

Webhook

Webhook 做什么

Webhook 用来把平台侧事件异步推送给接入方。你需要同时完成两件事：

  • 能正确接收 HTTP 回调
  • 能按开放平台的 canonical 规则验证回调签名

现成示例

  • receiver 示例入口：example/open/webhook-receiver/index.ts
  • 使用说明：example/open/webhook-receiver/readme.md

事件目录与联调

  • 事件目录可通过 POST https://role2.api.role2.com/api/1/open_event/list 查看
  • 非生产环境可通过 POST https://role2.api.role2.com/api/1/open_event/emit 为当前 app 触发模拟事件
  • 通过 POST https://role2.api.role2.com/api/1/open_webhook/regular_upsert 为当前 app 配置 webhook listener
  • 通过 POST https://role2.api.role2.com/api/1/open_webhook/delivery_read 查看最近 delivery 状态与失败原因
  • 通过 POST https://role2.api.role2.com/api/1/open_webhook/delivery_replay 对修复后的 failed delivery 做重放
  • 需要先完成 open webhook 的监听配置，再结合 sandbox 与 delivery replay 测试完整消费链路

建议排查顺序

  1. 先确认 receiver 端口、路径与公网或联调地址正确
  2. 再确认 timestamp、nonce、signature 是否被完整保留到验签逻辑
  3. 再读取 failed delivery 的 headers、payload 与错误原因
  4. 修复后通过 replay 重新消费
  5. 最后再看业务 payload 的字段处理
No translation yet

版本与迁移

迁移入口

  • 迁移索引：https://role2.api.role2.com/openapi/migrations
  • 动作目录：https://role2.api.role2.com/openapi/catalog

升级建议

  1. 每次升级前查看 https://role2.api.role2.com/openapi/migrations
  2. 观察是否出现 deprecation / sunset / replacement 信息
  3. 重新导出 npm run openapi:open:ts 与 npm run openapi:open:postman
  4. 调整调用方对错误码、scope 与回调行为的处理
No translation yet

常见问题

常见问题

签名总是不通过怎么办

先不要猜。用 https://role2.api.role2.com/api/1/sandbox/signature__playground 对照 method、query、body hash 与最终 signature，逐项比对差异。

为什么文档写的是 https://role2.api.role2.com/api/1/*，不是内部 https://role2.api.role2.com/call/*

因为外部接入方应该只依赖开放平台 facade，不应该绑定内部控制面路由。

为什么我已经有 key 还会被拒绝

先检查 key 是否已撤销、scope 是否覆盖当前动作、open app 是否处于正确环境，再检查你是否真的在用这把 key 对应的 app_secret。

我应该看 wiki 还是 https://role2.api.role2.com/document/open

想理解接入路径、控制面、排错顺序，请看 wiki。想确认某个接口的 schema、字段和返回值，请看 https://role2.api.role2.com/document/open。

为什么升级后还要重新导出类型与 Postman

因为 https://role2.api.role2.com/openapi?view=open 与 https://role2.api.role2.com/openapi/migrations 反映的是最新公开契约，旧导出可能缺少新字段、弃用提示或替代动作。

Webhook 验签失败但 API 调用正常

这通常说明出问题的是回调侧的 canonical request 还原，而不是 open key 本身。优先检查回调服务是否保留了原始 path、query、headers 和 body。