> ## 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.

# 税金プレビュー

> チェックアウトセッションの税ルールを照会し、段階的に税額を計算する

チェックアウトセッションに適用される税ルールを照会し、請求情報が十分に揃った時点で計算済みの税額を取得します。

このエンドポイントは**段階的な収集**を前提に設計されています：必須なのは `billingDetail.country` のみです。その国で追加的に必要となるフィールドは `rules.requiredFields` でレスポンスが示すため、チェックアウトフォームは最初から全てを要求せず、一つずつ順に尋ねられます。

```
POST /v1/actions/checkout/preview-tax
```

**認証：** Store Slug（`visitor` ロール）

<Note>
  このエンドポイントは、customer が請求情報を入力していく過程でホスティングされたチェックアウトページから呼び出されます。独自のチェックアウト UI を構築する場合は、customer の国または法人ステータスが変わるたびに呼び出してください。
</Note>

## リクエストボディ

| フィールド               | 型      | 必須  | 説明                                                                                        |
| ------------------- | ------ | --- | ----------------------------------------------------------------------------------------- |
| `checkoutSessionId` | string | Yes | [チェックアウトセッションの作成](/ja/api-reference/endpoints/orders/create-checkout-session) が返すセッション ID |
| `billingDetail`     | object | Yes | これまでに収集した請求情報（以下参照）                                                                       |

### billingDetail

| フィールド          | 型       | 必須  | 説明                                        |
| -------------- | ------- | --- | ----------------------------------------- |
| `country`      | string  | Yes | ISO 3166-1 alpha-2 国コード（例：`US`、`DE`、`JP`） |
| `isBusiness`   | boolean | No  | 法人購入かどうか                                  |
| `state`        | string  | No  | 州・県コード                                    |
| `postcode`     | string  | No  | 郵便番号                                      |
| `businessName` | string  | No  | 法人の正式名称                                   |
| `taxId`        | string  | No  | 法人の税務登録番号（EU の VAT 番号など）                  |

必須なのは `country` のみです。**残りのどのフィールドを収集する必要があるかはレスポンスが決定します** —— 国ごとの固定ルールではありません。`rules.requiredFields` を参照してください。

## レスポンス

| フィールド         | 型              | 説明                             |
| ------------- | -------------- | ------------------------------ |
| `currency`    | string         | チェックアウトセッションの通貨                |
| `rules`       | object         | 指定された国の税ルール                    |
| `calculation` | object \| null | 計算済みの金額。フィールドがまだ足りない場合は `null` |

### rules

| フィールド                       | 型       | 説明                        |
| --------------------------- | ------- | ------------------------- |
| `country`                   | string  | ルールが適用される国コード             |
| `taxName`                   | string  | 税の名称（例：`JCT`、`VAT`）       |
| `standardRate`              | number  | 標準税率（小数表記、`0.1` = 10%）    |
| `isTaxFree`                 | boolean | この国が非課税かどうか               |
| `isEuReverseChargeEligible` | boolean | EU のリバースチャージが適用できるかどうか    |
| `hasReducedRates`           | boolean | 一部の商品カテゴリに軽減税率が存在するかどうか   |
| `requiredFields`            | array   | 税額を計算する前にまだ必要なフィールド（以下参照） |

### requiredFields

各エントリは、チェックアウトフォームが次に収集すべきフィールドを 1 つ表します。

| フィールド       | 型      | 説明                                                           |
| ----------- | ------ | ------------------------------------------------------------ |
| `field`     | string | `isBusiness`、`state`、`postcode`、`businessName`、`taxId` のいずれか |
| `label`     | string | 入力欄に使用する可読ラベル                                                |
| `reason`    | string | その国でこれが必要な理由 —— customer に表示して問題ありません                        |
| `inputType` | string | 推奨される入力コントロール                                                |

`requiredFields` が空の場合、`calculation` に値が入ります。

### calculation

| フィールド       | 型      | 説明                         |
| ----------- | ------ | -------------------------- |
| `subtotal`  | string | 税抜き金額（表示フォーマット、例：`"8.39"`） |
| `taxAmount` | string | 税額（表示フォーマット）               |
| `total`     | string | customer に実際に請求される金額       |
| `taxRate`   | number | この注文に適用される税率               |

<Note>
  金額は API の他の部分と同様に表示フォーマットの文字列です。`taxRate` は小数（`0.19` = 19%）です。
</Note>

## 例

<CodeGroup>
  ```bash 情報が不足している場合 theme={"system"}
  curl -X POST https://api.waffo.ai/v1/actions/checkout/preview-tax \
    -H "X-Store-Slug: my-store-abc123" \
    -H "X-Environment: prod" \
    -H "Content-Type: application/json" \
    -d '{
      "checkoutSessionId": "cs_xxx",
      "billingDetail": { "country": "US" }
    }'
  ```

  ```bash 計算できる場合 theme={"system"}
  curl -X POST https://api.waffo.ai/v1/actions/checkout/preview-tax \
    -H "X-Store-Slug: my-store-abc123" \
    -H "X-Environment: prod" \
    -H "Content-Type: application/json" \
    -d '{
      "checkoutSessionId": "cs_xxx",
      "billingDetail": { "country": "DE", "isBusiness": false }
    }'
  ```
</CodeGroup>

情報が不足している場合 —— フォームは次に `state` を尋ねる必要があります。

```json theme={"system"}
{
  "data": {
    "currency": "USD",
    "rules": {
      "country": "US",
      "taxName": "Sales Tax",
      "standardRate": 0,
      "isTaxFree": false,
      "isEuReverseChargeEligible": false,
      "hasReducedRates": false,
      "requiredFields": [
        {
          "field": "state",
          "label": "State",
          "reason": "Sales tax in the United States is determined at state level",
          "inputType": "select"
        }
      ]
    },
    "calculation": null
  }
}
```

計算できる場合：

```json theme={"system"}
{
  "data": {
    "currency": "EUR",
    "rules": {
      "country": "DE",
      "taxName": "VAT",
      "standardRate": 0.19,
      "isTaxFree": false,
      "isEuReverseChargeEligible": true,
      "hasReducedRates": true,
      "requiredFields": []
    },
    "calculation": {
      "subtotal": "8.39",
      "taxAmount": "1.60",
      "total": "9.99",
      "taxRate": 0.19
    }
  }
}
```

## エラー

| ステータス | メッセージ                                              | 原因                                                  |
| ----- | -------------------------------------------------- | --------------------------------------------------- |
| 400   | `Missing required field: checkoutSessionId`        | `checkoutSessionId` が指定されていない                       |
| 400   | `Missing required field: billingDetail.country`    | `billingDetail` が欠落、または `country` を含まない             |
| 400   | `Missing or invalid header: x-context-environment` | `X-Environment` ヘッダーが欠落、または `test` / `prod` 以外      |
| 404   | `Checkout session not found or expired`            | セッションが存在しない、期限切れ、別のストアに属する、または別の environment で作成された |
| 500   | `Internal server error`                            | サーバ側の予期しない障害                                        |

## 現在の税務カバレッジ

税の判定は customer の請求地に基づき、Waffo Pancake が記録商（Merchant of Record）として納税義務を負います。現在設定されているカバレッジでは、**すべての国で `taxAmount` と `taxRate` は `0` が返ります** —— このエンドポイントは、ある注文に実際に請求される金額の正式な情報源です。税率を仮定せず `calculation.total` を読み取ってください。

`rules.requiredFields` も同様に稼働中の設定によって決まります。「米国とカナダは state が必要」「EU の法人は税番号が必要」といった内容をチェックアウト UI にハードコードせず、レスポンスが要求する項目をそのままレンダリングしてください。