开放平台文档固定沙箱合同
Sandbox only

PUBLIC SANDBOX DOCUMENTATION

从合成数据开始接入

使用固定 Scope、PKCE S256 和一次性沙箱授权码验证集成。生产 OAuth、生产 Client、Secret、Token 与真实用户数据尚未开放。

查看 API 产品

HARD BOUNDARY

所有示例仅限沙箱

示例只使用 sac1.* 一次码、sbox_at1.*短期令牌和合成场景；不要把它们接入生产账号、真实权益或生产回调。

生产未开放

QUICK START

安全起步

  1. 使用攀登者通行证完成一次性开发者会话交接。
  2. 登记唯一开发者主体，创建应用草稿并配置精确 HTTPS 回调。
  3. 在应用沙箱选择固定合成场景和最小 Scope。
  4. 用 PKCE S256 完成一次授权，并在固定 UserInfo Explorer 验证结果。

OIDC-LIKE SANDBOX

仅用于模拟的授权链

控制台创建绑定应用、场景、回调、state、Scope 与 PKCE challenge 的 一次性 sac1.* 授权码。数据面只开放以下固定路由：

  • POST /sandbox/oauth2/token
  • GET /sandbox/v2/userinfo
  • POST /sandbox/oauth2/revoke

访问令牌最长 600 秒，不签发 Refresh Token；浏览器 Cookie、通行证 Token 和未来生产 Token 均不能进入沙箱数据面。

SCOPES & CLAIMS

固定 Scope 与返回字段

Scope用途合成字段
openid用途返回仅对当前沙箱应用稳定的合成 pairwise sub。合成字段sub
passport.basic用途读取合成的通行证编号、昵称和头像。合成字段pdz_no, nickname, avatar_url
passport.level.read用途读取合成等级、标签和已激活系统数。合成字段passport_level, level_label, paid_system_count
entitlements.summary.read用途读取不对应真实权益的合成权益摘要。合成字段entitlements

ERRORS

稳定错误与恢复方式

DEVELOPER_SANDBOX_INVALID_REQUEST
请求字段、格式或固定操作不符合合同。
DEVELOPER_SANDBOX_ACCESS_DENIED
当前主体或应用不能执行该沙箱操作。
DEVELOPER_SANDBOX_NOT_FOUND
资源不存在，跨主体资源也统一返回此错误。
DEVELOPER_SANDBOX_VERSION_CONFLICT
资源版本已变化，重新读取后再提交。
DEVELOPER_SANDBOX_IDEMPOTENCY_CONFLICT
同一幂等键绑定了不同正文。
DEVELOPER_SANDBOX_INVALID_GRANT
一次码、PKCE 或有效期校验失败。
DEVELOPER_SANDBOX_RATE_LIMITED
请求超出有界速率，按响应提示稍后重试。
DEVELOPER_SANDBOX_PRODUCTION_ACCESS_DISABLED
生产能力固定关闭。

网络或 5xx 导致结果不确定时，只能使用原正文和原幂等键重试；409 后重新读取资源与 ETag，不得静默覆盖。

WEBHOOK STATUS

第三方 Webhook 尚未开放

仓库已经冻结 Ed25519 签名信封、事件 ID、时间戳、正文 SHA-256、固定 DNS/TLS 投递和重试语义，但第三方端点登记与生产事件订阅尚未开放。 当前不得配置接收地址，也不能把内部事件样例当作已承诺的生产事件。

  • pdz-webhook-id
  • pdz-webhook-timestamp
  • pdz-webhook-key-id
  • pdz-webhook-body-sha256
  • pdz-webhook-signature: v1=...

TYPESCRIPT SDK

最小沙箱客户端

TypeScript SDK 只封装固定沙箱合同、严格响应解析、no-store、PKCE 与幂等恢复；仓库内参考包尚未公开发布，也不接受任意 URL、生产 Client Secret 或生产令牌。

import { PassportDeveloperClient } from "@pdz/sdk-typescript";

const client = new PassportDeveloperClient({
  apiOrigin: "https://open-api.pdz.club",
});

const products = await client.readSandboxProducts();
// 仅返回固定沙箱 Scope 和合成字段目录