> ## 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](/ja/api-reference/endpoints/auth/issue-session-token) で短期 session token を mint し、customer のブラウザ（または製品内 UI）がその token を `Authorization` ヘッダに入れて下記エンドポイントを呼び出します。マーチャント API Key はサーバから外に出ません。

<Note>
  Session トークンは `buyerIdentity` + `visitingStoreId` でスコープされ、その customer がその店舗内で保持するレコードに対する操作のみ認可されます。マーチャント全体の状態は読み取れません。
</Note>

## 各呼び出しで必須のヘッダ

| ヘッダ             | 値                                                     |
| --------------- | ----------------------------------------------------- |
| `Authorization` | `Bearer <session-token>`（Issue Session Token が返す JWT） |
| `X-Environment` | `test` または `prod`（トークン mint 時の environment と一致）       |

ゲートウェイがトークンから customer identity と visiting store を導出するため、別ヘッダで渡す必要はありません。

## エンドポイント

<CardGroup cols={2}>
  <Card title="Preview Trial" icon="circle-info" href="/ja/api-reference/endpoints/orders/preview-trial">
    Customer がトライアルの対象か確認
  </Card>

  <Card title="ワンタイム注文のキャンセル" icon="ban" href="/ja/api-reference/endpoints/orders/cancel-onetime-order">
    決済完了前に pending のワンタイム注文をキャンセル
  </Card>

  <Card title="サブスクリプションのキャンセル" icon="circle-stop" href="/ja/api-reference/endpoints/subscriptions/cancel-subscription-customer">
    customer を代表して active または pending のサブスクリプションをキャンセル
  </Card>

  <Card title="サブスクリプションの再有効化" icon="rotate" href="/ja/api-reference/endpoints/subscriptions/reactivate-order">
    `canceling` 中に予定済みキャンセルを取り消す
  </Card>

  <Card title="プラン変更" icon="right-left" href="/ja/api-reference/endpoints/subscriptions/change-product">
    active なサブスクリプションを別の商品へ切替
  </Card>

  <Card title="GraphQL" icon="diagram-project" href="/ja/api-reference/endpoints/graphql/overview">
    Customer 自身の注文、支払い、返金を照会
  </Card>
</CardGroup>

## トークン経路固有のエラー

Session-token 呼び出し経路でのみ発生するエラー：

| ステータス | `errors[0].message`                          | 意味                                                            |
| ----- | -------------------------------------------- | ------------------------------------------------------------- |
| 400   | `Missing X-Context-Buyer-Identity header`    | トークンに customer identity（`buyerIdentity`）claim が含まれない — 再 mint |
| 400   | `Missing X-Context-Visiting-Store-Id header` | トークンが店舗にスコープされていない — `visitingStoreId` 付きで再 mint              |
| 401   | `Authentication failed`                      | Session token の期限切れ、形式不正、または別マーチャント向けに署名されている                 |