接入概览
三狗云通过 OAuth 2.0 提供用户身份授权和店铺 OpenAPI。第三方应用使用审核通过的客户端获取 Access Token，再在批准的权限和资源范围内调用接口。
服务地址
服务地址由平台按客户端分配。应用审核通过后，在 开发者中心 → 应用接入配置 → 服务地址 获取当前客户端的配置。示例使用以下占位符，请替换为应用接入配置中的地址：
| 配置项 | 文档占位符 | 用途 |
|---|---|---|
| API Base URL | {API_BASE_URL} | 业务接口根地址，保留平台分配的完整路径前缀 |
| 用户授权地址 | {AUTHORIZATION_ENDPOINT} | 浏览器跳转的完整授权页面地址 |
| 令牌端点 | {TOKEN_ENDPOINT} | 换取或刷新令牌的完整地址 |
| 用户信息端点 | {USERINFO_ENDPOINT} | 获取授权用户身份的完整地址 |
业务接口使用 API Base URL 拼接文档路径，例如 {API_BASE_URL}/openapi/v1/products。OAuth 端点使用分配的完整地址，不要根据 API 域名推导或自行增删 /api 等路径前缀。
这些地址可能随客户端接入安排不同，应保存为应用配置，不硬编码到业务逻辑中。平台调整地址时需按通知更新配置；文档地址和客户端回调地址不作为服务地址使用。{CLIENT_ID}、{ACCESS_TOKEN} 等表示需替换为当前请求实际值的参数。
接入条件
- 开发者资格：开发者入口采用邀请和审核机制，每个账号最多拥有一个客户端。
- 应用配置：需登记客户端类型、回调地址和申请权限。审核通过后，在开发者中心获取
client_id；机密客户端还需生成client_secret。 - 用户身份授权：无需商户身份；通常申请
openid profile；需要邮箱时另行申请email。 - 店铺与交易能力：申请人必须拥有已启用商户，客户端固定绑定该商户。不能指定其他商户编号访问其他店铺。
申请字段、类型选择和配置变更限制见 应用申请与配置。
授权方式与能力范围
| 业务能力 | 授权方式 | 客户端要求 |
|---|---|---|
| 用户登录、读取用户身份 | authorization_code + PKCE | 公共或机密客户端 |
| 用户下单、查询订单、发起支付、查询支付状态 | authorization_code + PKCE | 公共或机密客户端，已绑定商户 |
| 外部业务订单按金额收款与对账 | client_credentials | 机密客户端，已绑定商户；merchant_payments.create、merchant_payments.read |
| 服务端读取店铺与商品 | client_credentials | 机密客户端，已绑定商户 |
| 延续用户授权 | refresh_token | 使用同一客户端取得的 Refresh Token |
client_credentials 支持已批准的商户资料、商品/库存维护和 merchant_payments.* 通用收款能力，但不能替代 orders.*、payments.* 的用户授权。通用收款的建单、幂等键和 return_url 见 通用商户收款。权限名称、可用主体和商户绑定规则见 权限范围。
鉴权约定
用户授权：应用生成 PKCE、state 和按需提供的 nonce → 浏览器跳转授权页 → 平台将授权结果返回已登记的 redirect_uri → 应用验证回调并向令牌端点换码。
所有用户授权客户端均要求 PKCE，算法固定为 S256。授权码有效期 5 分钟，只能使用一次；机密客户端换码、刷新时还必须在请求体中提交 client_secret。参数、响应和刷新契约见 OAuth 授权。
业务请求：用户信息与 OpenAPI 请求使用下列请求头：
Authorization: Bearer {ACCESS_TOKEN}Access Token 的实际权限以令牌响应 scope 为准，不能超出客户端批准范围。订单及支付还会校验授权用户和绑定商户的资源归属。平台账户登录令牌、Refresh Token 和 ID Token 均不能替代 OAuth Access Token。
请求与响应约定
| 项目 | 契约 |
|---|---|
| 令牌请求 | POST {TOKEN_ENDPOINT}，支持表单编码与 JSON；文档统一使用 application/x-www-form-urlencoded |
| 业务写请求 | Content-Type: application/json |
| 成功响应 | 直接返回 JSON 资源或列表，没有统一的 data 外层 |
| 业务编号 | 字符串，保留原值 |
| 金额 | 商品订单采用八位定点；通用收款的 amount_minor 按币种精度；详见 数据格式 |
| 有效期 | expires_in 为持续秒数，支付 expire_time 为 Unix 秒时间戳 |
| 错误处理 | 先检查 HTTP 状态，再解析错误字段；详见 错误与排查 |
业务接口的方法、权限、参数和返回字段见 API 参考。交易状态、副作用与重试边界见 交易接入约定。
当前能力边界
- 未提供标准 OIDC Discovery / JWKS 端点。通用 OIDC SDK 不能仅配置 issuer 后自动完成接入；用户身份可通过 Access Token 调用
userinfo获取。不能直接信任仅解码、未验签的 ID Token。 - 已签发客户端暂不提供类型、回调地址或权限的自助修改入口；需调整时联系平台处理。
- 通用收款提供本商户渠道目录和按引用/单号过滤的收款列表。商品订单仍无独立渠道发现、结算报价和通用订单列表；未提供公开取消、退款或提现接口。
- 商品订单创建未提供通用幂等键契约；通用收款按商户和
idempotency_key去重。支付请求可能实际扣款。超时后需先确认业务结果，不能直接重放写请求。