大客户端到端接入指南

这是一条上线决策路径，不是 endpoint 清单。每个阶段都明确区分 已开放、需要平台开通 与 尚未开放；只有 API 参考 中来自 public-only artifact 的操作才视为已开放。

当前权威阻塞快照

API public-only artifact 明确给出五类阻塞。它们只解释为什么能力尚未开放，不表示 endpoint 已存在：

1. 接入前检查

状态：已开放（评估指南）；需要平台开通（商业与生产资格）。

• 确认场景是匿名目录读取、API Key 服务端读取，还是尚未开放的用户授权/写入能力。
• 明确数据控制者、终端用户、店铺/资源边界、市场与数据保留要求。
• 指定技术负责人、安全联系人和应急联系人；建立凭据泄漏、限流和未知写入结果的响应流程。
• 只把 25 项已发布契约操作 纳入当前实施范围。
• 五项 hosted 操作仅视为后端 session 安全基础；官方 UI、订单最终创建、Provider 支付推进、生产配置与迁移尚未完成。

继续条件： 所需能力均有公开 Reference，或平台书面确认开通路径。否则停止集成，不从控制台流量或混合 OpenAPI 推测接口。

2. 申请应用与环境

状态：需要平台开通。

应用、环境、API Key、installation、生产资格及相关能力由 Ayalink 平台配置或审批；当前没有公开的申请/管理 endpoint。向平台提供应用名称、业务场景、所需市场、回调域名、技术与安全联系人，以及最小权限说明。秘密只通过平台批准的安全交付方式接收。

继续条件： 已获得目标环境的明确标识、允许能力、凭据交付与轮换说明。文档页面、client ID 或 CORS 成功都不代表生产资格。

3. 官方授权域与 PKCE

状态：尚未开放（OAuth endpoint）；安全模型已公开。

需要用户授权时，只能把用户送往平台开通材料确认的官方 Ayalink authorization domain，并使用 Authorization Code + PKCE S256、精确 redirect URI、逐次生成并校验的 state 与 nonce。第三方不得反代或仿冒登录页，也不得收集密码/MFA。

当前 public-only artifact 不包含 authorization、token exchange、撤销或 grant 管理 endpoint，并明确阻塞于 DPoP 与 resource/installation 绑定，因此本站不提供 URL、scope、curl 或成功响应。详见 OAuth 与账号安全边界。

停止条件： 未获得平台确认的官方域、client 配置或精确 redirect URI 时，不实现 OAuth 跳转或 token exchange。

4. Token 安全与 BFF

状态：已开放（安全架构指南）；需要平台开通（真实 grant）；尚未开放（DPoP、rotation 等未确认能力）。

浏览器不得持有 client secret，不得把 access/refresh token 放入 URL、持久化浏览器存储、日志、分析或错误报告。需要浏览器会话时使用同源 BFF：BFF 仅保存该应用自己的 grant，并向自己的前端签发 HttpOnly、Secure、适当 SameSite 的应用会话 Cookie；绝不接收或转发 Ayalink 全局 Cookie。

按平台开通材料确认 token audience、资源边界、有效期、轮换和撤销语义。未公开的 DPoP、refresh-token rotation 与 replay detection 不能当作现有能力。

5. 调用已开放 API

状态：已发布契约（20 项读取与 5 项 hosted 后端 session 基础操作）。

当前 Reference 包含 7 项匿名 catalog 读取与 4 项 API Key identity/catalog 读取。按每个 operation 页面使用真实 method、path、认证、参数与响应 schema；不要从本指南复制或猜测 Base URL，运行环境地址以平台开通材料为准。

• 浏览已开放 API 目录
• API Key 只放服务端批准的 header，禁止进入浏览器 bundle 或 URL。
• 请求只发送 Reference 声明的参数；没有 schema 的示例不自行补造。

继续条件： 目标 operation 存在于当前目录，且所需认证已开通。Installation identity/readiness 读取与五项 hosted 后端 session 操作已发布；OAuth、installation 写入、Webhook 管理、官方 hosted UI、订单最终创建和 Provider 支付推进仍不可用。

6. 分页、错误、requestId 与 429

状态：已开放（以每个 operation 的公开契约为准）。

分页参数、游标与响应结构只按对应 operation 页面声明实现；若 spec 未声明，则不能假设 page、limit、cursor 或总数。按 HTTP 状态与稳定错误码分支处理，不解析自然语言文案。保存响应中实际提供的 requestId 或关联编号，用于支持与对账；具体字段/header 未声明时以平台材料为准，不自行创造。

收到 429 时，仅当响应实际提供 Retry-After 才按其等待；否则使用有界指数退避与抖动，并限制重试预算。401、403、404、409/412、422、429 与 5xx 的恢复边界见错误、幂等与限流。

7. 幂等与未知结果

状态：已开放操作均为 GET，不需要写入幂等键；installation 写入与订单 API 尚未开放。

对 20 项读取操作可进行有界安全重试，但仍须遵守限流。Hosted session 变更只能遵循对应 operation 契约明确声明的幂等事实；spec 未声明时，超时或断连结果必须视为未知，不能盲目重放。这些 session 操作不证明 hosted UI、订单创建或支付推进已经可用。

8. Webhook 签名、重放与重试

状态：需要平台开通（订阅与 secret）；尚未开放（订阅管理 endpoint 仍缺 installation-bound credential）；验签与恢复指南已公开。

接收方必须基于原始请求体、平台声明的 timestamp 与签名材料完成 HMAC 校验，使用常量时间比较、时间窗校验和 event ID 原子去重；签名通过前不解析 JSON。轮换时只接受平台明确允许的当前/前一 key 窗口。

发送方重试次数、时间窗、header 名称和 dead-letter 行为以平台开通材料为准。本地处理应有界退避、尊重实际收到的 Retry-After、保留原 event ID，并让业务效果幂等。详见 Webhook 指南 与验签示例。

9. 测试与验收

状态：已开放（静态契约测试）；需要平台开通（真实环境联调）。

至少覆盖：成功读取、空结果、无效/撤销凭据、权限拒绝、资源不存在、校验错误、429、5xx/断连、分页边界、日志脱敏；若接入 Webhook，再覆盖错误签名、过期 timestamp、重复 event、乱序、重试和 secret 轮换。测试不得使用生产 secret 或真实个人数据。

继续条件： 合同测试使用当前 artifact，真实环境联调记录 requestId、时间、operationId 与脱敏结果；所有未知结果均能对账或安全停止。

10. 生产上线检查

状态：需要平台开通；外部 readiness 尚未获得证明。

• 平台已确认生产应用/环境、允许能力、市场和凭据状态。
• Base URL、authorization domain、redirect URI、audience、scope 与 Webhook 参数均来自平台材料，而非文档推测。
• 凭据进入 secret manager；日志、监控、告警、轮换、限流预算和应急联系人已就绪。
• 生产前重新核对当前 API Reference 的来源版本与变更说明。
• 灰度、回滚和停止条件有负责人；不得把测试环境成功当作生产批准。

11. 撤销与应急

状态：需要平台开通（撤销入口与支持）；安全响应流程已开放。

发现 token/API Key/Webhook secret 泄漏、异常调用、仿冒授权页或越权迹象时：立即停止相关流量，隔离泄漏来源，通过平台批准入口撤销或轮换受影响凭据，保留 requestId、operationId、时间窗和脱敏日志，并联系官方安全渠道。不要把 token、Cookie 或完整 payload 发进工单。

重新上线前确认旧凭据确已失效、消费者已更新、重复事件/未知写入已对账、根因已修复，并重新执行生产检查。当前未公开自助撤销 endpoint；不得猜测 URL 或把删除本地 Cookie 当作撤销 grant。

Reference 自动扩充原则

后续 API public-only artifact 到达时，importer 会校验来源 commit、hash、operationId、安全方案和内部边界，再自动生成新增双语 endpoint 页面。本指南只据真实 artifact 更新开放状态；不会等待“全量接口”，也不会手写不存在的 endpoint、scope 或响应。