第三方订单流程接入

本文整理第三方 App 以用户身份创建订单、发起支付、查询订单状态所需的接口。所有订单能力使用 OAuth orders:checkout scope，表示“当前授权用户自己的订单流程”，不是后台订单管理权限。

鉴权方式

第三方调用订单接口时使用 OAuth Access Token：

http

Authorization: Bearer wno-...

Token 必须包含 orders:checkout。后端会继续按业务数据做隔离：

数据类型	隔离规则
虚拟商品支付订单	使用 token 对应的 `userId`，并校验该用户属于请求的 `teamId`
订阅变更	校验该用户是团队 owner 或 admin
硬件销售订单	只允许访问 `owner_user_id` 等于当前 OAuth 用户的订单
Webhook / Admin API	不在 `orders:checkout` 范围内，不对第三方开放

获取 OAuth Token

推荐方式仍是标准 Authorization Code + PKCE：

第三方将用户跳转到 GET /oauth/authorize，请求 scope=orders:checkout。
用户在外脑授权页登录并确认授权。
第三方用授权码调用 POST /oauth/token 换取 wno- access token 与 wno-rt- refresh token。

对于被平台显式开通 direct_otp_grant capability 的 OAuth App，也可以用验证码直连 grant 获取相同格式的 OAuth token。直连方式仅适合强信任 App，未开通 capability 会返回 unauthorized_client。

bash

curl -X POST "https://block2-api.wainao.chat/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  --data-urlencode "grant_type=urn:wainao:params:oauth:grant-type:otp" \
  --data-urlencode "client_id=<client_id>" \
  --data-urlencode "otp_type=phone" \
  --data-urlencode "identifier=13800001234" \
  --data-urlencode "code=123456" \
  --data-urlencode "scope=orders:checkout"

邮箱验证码使用 otp_type=email，identifier 传邮箱地址。手机号验证码使用 otp_type=phone，identifier 传手机号。

虚拟商品与订阅订单

步骤	接口	说明
读取价格	`GET /payment/prices`	返回可购买的积分包或订阅价格
读取支付方式	`GET /payment/methods`	返回当前可用支付渠道与方式
创建订单	`POST /payment/orders`	请求体必须包含 `teamId`、`productType`、`productCode`
发起支付	`POST /payment/orders/:id/pay`	返回支付 URL、二维码或 checkout token
查询订单	`GET /payment/orders/:id`	仅可查询当前用户所属团队的订单
查询订单列表	`GET /payment/orders?teamId=...`	仅可列出当前用户所属团队订单

订阅变更接口也归入同一个订单 checkout scope：

接口	说明
`GET /billing/subscription?teamId=...`	查询当前团队订阅和余额
`POST /billing/subscription/change-plan`	变更订阅计划
`POST /billing/subscription/cancel-renewal`	取消自动续费
`POST /billing/subscription/resume-renewal`	恢复自动续费

订阅写操作需要当前 OAuth 用户是目标团队 owner 或 admin。

硬件销售订单

步骤	接口	说明
读取 SKU 配置	`GET /public/hardware-sales/skus/:sku/config`	公开接口，不需要 OAuth
创建硬件订单	`POST /public/hardware-sales/orders`	可使用 OAuth `orders:checkout`，也兼容 JWT 或 `phoneToken`
发起硬件订单支付	`POST /public/hardware-sales/orders/:orderNo/pay`	OAuth 用户必须是订单 owner
查询我的硬件订单列表	`GET /hardware-sales/orders`	仅返回当前 OAuth 用户自己的订单
查询我的硬件订单详情	`GET /hardware-sales/orders/:orderNo`	非 owner 与不存在都返回 404

硬件订单要求账号绑定已验证手机号。OAuth token 有效但账号未绑定已验证手机号时，下单会返回验证相关错误，需要用户先完成手机号绑定或使用手机号验证码登录流程。

不开放给第三方的订单接口

以下接口不属于 orders:checkout：

接口	原因
`/admin/payment/*`	后台支付管理
`/admin/hardware-sales/*`	后台硬件销售运营
`/webhook/*`	支付渠道回调
`/public/hardware-sales/orders/lookup`	手机号 + 订单号公开查单，不使用 OAuth scope

第三方订单流程接入 ​

鉴权方式 ​

获取 OAuth Token ​

虚拟商品与订阅订单 ​

硬件销售订单 ​