> ## Documentation Index
> Fetch the complete documentation index at: https://docs.waffo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Customer Portal API 总览

> Customer 浏览器侧使用 session token 调用的端点

Customer Portal API 是 Waffo 的 customer 侧接口。商户后端通过 [Issue Session Token](/zh/api-reference/endpoints/auth/issue-session-token) mint 短期 session token，由 customer 浏览器（或你的产品内 UI）在 `Authorization` 头中携带调用下列端点。商户 API Key 永不离开服务端。

<Note>
  Session token 按 `buyerIdentity` + `visitingStoreId` 限制作用域，只能操作属于该 customer 在该门店内的记录。不能读取商户全量数据。
</Note>

## 每次调用必须的请求头

| 请求头             | 值                                                     |
| --------------- | ----------------------------------------------------- |
| `Authorization` | `Bearer <session-token>`（Issue Session Token 返回的 JWT） |
| `X-Environment` | `test` 或 `prod`（必须与 mint token 时的 environment 一致）     |

网关从 token 派生 customer identity 与 visiting store，无需作为独立请求头传入。

## 端点

<CardGroup cols={2}>
  <Card title="Preview Trial" icon="circle-info" href="/zh/api-reference/endpoints/orders/preview-trial">
    检查 customer 是否符合试用资格
  </Card>

  <Card title="取消一次性订单" icon="ban" href="/zh/api-reference/endpoints/orders/cancel-onetime-order">
    在支付完成前取消待处理的一次性订单
  </Card>

  <Card title="取消订阅" icon="circle-stop" href="/zh/api-reference/endpoints/subscriptions/cancel-subscription-customer">
    代 customer 取消活跃或待处理的订阅
  </Card>

  <Card title="恢复订阅" icon="rotate" href="/zh/api-reference/endpoints/subscriptions/reactivate-order">
    在 `canceling` 期间撤销待生效的取消
  </Card>

  <Card title="更换产品" icon="right-left" href="/zh/api-reference/endpoints/subscriptions/change-product">
    将活跃订阅切换到另一个产品
  </Card>

  <Card title="GraphQL" icon="diagram-project" href="/zh/api-reference/endpoints/graphql/overview">
    查询 customer 自己的订单、支付、退款
  </Card>
</CardGroup>

## Token 路径特有错误

仅在 session-token 调用路径下出现的错误：

| 状态码 | `errors[0].message`                          | 含义                                                         |
| --- | -------------------------------------------- | ---------------------------------------------------------- |
| 400 | `Missing X-Context-Buyer-Identity header`    | Token 不含 customer identity（`buyerIdentity`）claim — 重新 mint |
| 400 | `Missing X-Context-Visiting-Store-Id header` | Token 未绑定门店 — 重新 mint 时带上 `visitingStoreId`                |
| 401 | `Authentication failed`                      | Session token 过期、格式错或为其他商户签发                               |