# 税務上の住所を特定

税を計算する前に、住所の精度を検証します。

Stripe Tax は顧客の住所に基づいて税率を計算しますが、一部の住所には正確な税率を判断するのに十分な詳細情報が含まれていません。たとえば、アメリカの郵便番号は複数の税管轄区域にまたがることがあるため、Stripe Tax はその住所の正確な税率を計算するのではなく、概算の税率を返す場合があります。

税計算で使用する前に、Address Resolution API を使用して、特定の住所に対する税率を Stripe Tax がどの程度正確に判定できるかを確認できます。API は次の情報を返します。

- Stripe Tax が住所の税率を決定できる精度レベル
- Stripe Tax がより正確な税率を判定できるように、収集または更新する必要がある住所フィールド

  Address Resolution API はプライベートプレビュー段階です。ウェイトリストに追加するには、メールアドレスを入力してください。対象となるかどうかを確認し、オンボーディング手順をご案内するため、追ってご連絡します。すでに Stripe アカウントをお持ちの場合は、登録前にログインしてください。  

## はじめる前に

[Stripe Tax を設定](https://docs.stripe.com/tax/set-up.md)すれば、税の設定を行えます。

## 住所を特定

### リクエスト

`POST /v2/tax/address_resolution`

```json
{
  "address": {
    "country": "US",
    "state": "CA",
    "city": "South San Francisco",
    "postal_code": "94080",
    "line1": "354 Oyster Point Blvd"
  }
}
```

### レスポンス

```json
{
  "object": "v2.tax.address_resolution",
  "livemode": false,
  "precision": "address",
  "precision_details": {
    "issues": []
  },
  "address": {
    "country": "US",
    "state": "CA",
    "city": "South San Francisco",
    "postal_code": "94080",
    "line1": "354 Oyster Point Blvd"
  }
}
```

## 精度レベルを理解する

`precision` フィールドは、指定した住所に対する税を計算する際に、Stripe Tax が税率をどの詳細レベルで判定できるかを示します。精度レベルは、詳細度が高い順に次のとおりです。

| 精度            | 説明                                                  |
| ------------- | --------------------------------------------------- |
| `address`     | 特定の住所に対する税率を判定できます。最も詳細度が高いレベルであり、米国でのみ利用できます。      |
| `street`      | 番地レベルで税率を判定できます。住所によっては、これが最も詳細度の高いレベルになります。        |
| `postal_code` | 郵便番号エリアに対する税率を判定できます。通常、米国ではこのレベルの税率は概算になります。       |
| `city`        | 市区町村レベルのエリアに対する税率を判定できます。                           |
| `state`       | 州または行政区画の税率を判定できます。カナダやインドなどの国では、これが利用可能な最も詳細な区分です。 |
| `国`           | 国の税率を判定できます。北米以外のほとんどの国では、全国一律の税率が適用されます。           |
| `none`        | 住所には、税率を判定するのに十分な情報が含まれていません。                       |

`精度`が`なし`でない場合は、税の計算に住所を使用できます。ただし、詳細レベルが低い場合 (精度が低い場合)、その場所により正確な税率が存在すると、おおよその税率になる可能性があります。

### 精度と税の正確性の関係

重要な指標は、`精度`と `precision_details.issues` の組み合わせです。

- **空の `issues` 配列**: Stripe Tax は、この住所に対して可能な限り最も正確な税率を判定します。より正確な税率を得るために、顧客から追加で収集できる情報はありません。たとえば、`street` 精度で issues がないアメリカの住所は、その通りのすべての住所で税率が同じであることを意味します。
- **空でない `issues` 配列**: この場所には、より正確な税率が存在する可能性がありますが、入力した住所にはそれを判定するのに十分な詳細がありません。精度を向上させるには、`issues` に一覧表示されているフィールドを収集または更新してください。

### 国別の最高精度

税率の判定に使用できる詳細情報の数は、国によって異なります。住所がその国での最適な精度に達すると、`issues` 配列は空になります。

| 国       | 最適な精度     | 必須フィールド                                                                            |
| ------- | --------- | ---------------------------------------------------------------------------------- |
| アメリカ合衆国 | `address` | `country`、`state`、`city`、`postal_code`、`line1`                                     |
| カナダ     | `state`   | `country`、および `state` または `postal_code`                                            |
| インド     | `state`   | `country`、および `state` または `postal_code`                                            |
| スペイン    | `state`   | `country`、`state` または `postal_code` (カナリア諸島とセウタでは、スペインのその他の地域では、`country`の精度で十分です) |
| その他の国   | `国`       | `国`                                                                                |

## issues に基づいて不足しているフィールドを収集する

より正確な税率が存在していても、住所にそれを判定するのに十分な詳細がない場合、`precision_details.issues` 配列は、顧客から収集する必要があるフィールドを示します。各 issue には次の情報が含まれます。

- `field`: 収集または更新する住所フィールド (`line1`、`city`、`postal_code`、`state`、または `country`)。
- `code`: issue の種類。現在、値は `required_for_improved_precision` のみで、このフィールドを指定すると Stripe Tax がより正確な税率を判定できる可能性があることを示します。

たとえば、郵便番号のみを含むアメリカの住所を解決すると、`postal_code` の精度と、不足しているフィールドに関する issue が返されます。

```json
// Request
{"address": {"country": "US", "postal_code": "94080"}}
```

```json
// Response
{
  "precision": "postal_code",
  "precision_details": {
    "issues": [
      {"field": "city", "code": "required_for_improved_precision"},
      {"field": "line1", "code": "required_for_improved_precision"}
    ]
  },
  "address": {
    "country": "US",
    "postal_code": "94080"
  }
}
```

`precision_details.issues` が空の場合、その住所からは Stripe Tax がその場所に対して判定できる最も正確な税率が得られます。顧客から追加情報を収集する必要はありません。

## 導入で住所を検証

導入で住所解決を使用する一般的なフローは次のとおりです。

1. 顧客から住所を収集します。
1. 住所解決 API を呼び出して精度を確認します。
1. `precision_details.issues` に項目が含まれている場合は、一覧にあるフィールドを入力または更新するよう顧客に求めます。これは、顧客が住所の詳細をさらに提供すれば、より正確な税率を利用できることを意味します。
1. `precision_details.issues` が空の場合、その住所では可能な限り正確な税率が得られます。

### 顧客作成前の検証

まず住所を解決します。`precision` が `none` の場合、その住所は税計算に使用できません。`precision_details.issues` が空の場合、税率は可能な限り正確であり、顧客を作成できます。

```json
// Request
POST /v2/tax/address_resolution

{
  "address": {
    "country": "US",
    "state": "CA",
    "city": "South San Francisco",
    "postal_code": "94080",
    "line1": "354 Oyster Point Blvd"
  }
}
```

```json
// Response — precision_details.issues is empty, so the tax rate is as accurate as possible
{
  "precision": "address",
  "precision_details": {
    "issues": []
  },
  "address": {
    "country": "US",
    "state": "CA",
    "city": "South San Francisco",
    "postal_code": "94080",
    "line1": "354 Oyster Point Blvd"
  }
}
```

レスポンスに問題が含まれている場合は、顧客を作成する前に、不足しているフィールドを入力するよう顧客に求めます。

```json
// Response — issues present, a more precise tax rate is available
{
  "precision": "postal_code",
  "precision_details": {
    "issues": [
      {"field": "city", "code": "required_for_improved_precision"},
      {"field": "line1", "code": "required_for_improved_precision"}
    ]
  },
  "address": {
    "country": "US",
    "postal_code": "94080"
  }
}
```

### 加盟店の発送元住所の検証

[税設定](https://docs.stripe.com/tax/settings-api.md)を構成する前に、自社の発送元住所を検証できます。

```json
// Request
POST /v2/tax/address_resolution

{
  "address": {
    "country": "US",
    "state": "FL",
    "city": "Fort Lauderdale",
    "postal_code": "33301",
    "line1": "433 NE 8th Ave"
  }
}
```

```json
// Response — no issues, safe to use as your origin address
{
  "precision": "address",
  "precision_details": {
    "issues": []
  },
  "address": {
    "country": "US",
    "state": "FL",
    "city": "Fort Lauderdale",
    "postal_code": "33301",
    "line1": "433 NE 8th Ave"
  }
}
```

## 国別の例

### アメリカ合衆国

米国の住所では、利用可能な最も高い精度は `address` です。米国の税率は番地レベルまで異なる場合があるため、すべてのフィールドを指定すると最も正確な税率になります。

住所が一部しかない場合は、issues を伴う低い精度が返され、より正確な税率が存在する可能性があることを示します。

```json
// Request
{"address": {"country": "US", "state": "FL", "postal_code": "32789"}}
```

```json
// Response
{
  "precision": "postal_code",
  "precision_details": {
    "issues": [
      {"field": "city", "code": "required_for_improved_precision"},
      {"field": "line1", "code": "required_for_improved_precision"}
    ]
  },
}
```

米国の住所で州のみが指定され、郵便番号がない場合は、米国の住所に必要な最小フィールドを満たしていないため、精度として `none` が返されます。

```json
// Request
{"address": {"country": "US", "state": "FL"}}
```

```json
// Response
{
  "precision": "none",
  "precision_details": {
    "issues": [
      {"field": "city", "code": "required_for_improved_precision"},
      {"field": "postal_code", "code": "required_for_improved_precision"},
      {"field": "line1", "code": "required_for_improved_precision"}
    ]
  }
}
```

### カナダ

Stripe はカナダの住所の税率を州レベルで決定します。利用可能な最も高い精度は `state` です。州または郵便番号を指定すると、税率は可能な限り正確になるため、`issues` 配列は空になります。

```json
// Request
{"address": {"country": "CA", "postal_code": "T2P 2P2"}}
```

```json
// Response
{
  "precision": "state",
  "precision_details": {
    "issues": []
  },
}
```

国のみを指定すると、問題ありの `country` 精度が返されます。カナダでは州ごとに税率が異なるため、正しい州税率を判断できるよう、`issues` 配列は州または郵便番号を収集するよう示します。

```json
// Request
{"address": {"country": "CA"}}
```

```json
// Response
{
  "precision": "country",
  "precision_details": {
    "issues": [
      {"field": "state", "code": "required_for_improved_precision"},
      {"field": "postal_code", "code": "required_for_improved_precision"}
    ]
  },
}
```

### スペイン

スペインには、スペイン本土とは異なる税率が適用される自治地域 (カナリア諸島とセウタ) があります。住所がこれらの地域のいずれかに該当する場合、精度は `state` となり、`issues` 配列は空になります。つまり、税率は可能な限り正確です。

```json
// Request
{"address": {"country": "ES", "postal_code": "38003"}}
```

```json
// Response
{
  "precision": "state",
  "precision_details": {
    "issues": []
  },
}
```

住所が既知の州 (マラガなど) を含む地域に該当する場合、精度は `country` で、`issues` 配列は空です。つまり、国の税率が適用され、住所の詳細を追加しても異なる税率にはなりません。

```json
// Request
{"address": {"country": "ES", "state": "MA"}}
```

```json
// Response
{
  "precision": "country",
  "precision_details": {
    "issues": []
  },
}
```

国のみを指定する場合、`issues` 配列は `state` または `postal_code` を収集するよう示します。これは、詳細情報がないと、顧客が税率の異なる自治地域にいるかどうかを API が判断できないためです。

```json
// Request
{"address": {"country": "ES"}}
```

```json
// Response
{
  "precision": "country",
  "precision_details": {
    "issues": [
      {"field": "state", "code": "required_for_improved_precision"},
      {"field": "postal_code", "code": "required_for_improved_precision"}
    ]
  },
}
```

州を指定せずに郵便番号を指定すると、`issues` 配列では常に `state` フィールドを収集するよう示されます。これは、API が郵便番号が自治地域に対応しているかどうかを検証できないためです。

```json
// Request
{"address": {"country": "ES", "postal_code": "29001"}}
```

```json
// Response
{
  "precision": "country",
  "precision_details": {
    "issues": [
      {"field": "state", "code": "required_for_improved_precision"}
    ]
  },
}
```

### その他の国

ほとんどの国では、国全体に単一の税率が適用されます。こうした国では、国コードのみを指定すると最も正確な税率が得られます。`issues` 配列が空であれば、これ以上正確な税率を判断する必要がないことを示します。

```json
// Request
{"address": {"country": "DE", "postal_code": "12345"}}
```

```json
// Response
{
  "precision": "country",
  "precision_details": {
    "issues": []
  },
}
```

## 制限事項

- **`line2` はサポートされていません**: Stripe Tax エンジンは税率の判定に `line2` を使用しないため、API では受け付けられません。
- **精度の保証は Stripe Tax エンジンにのみ適用されます**: サードパーティの税計算エンジンを使用する場合、この API の精度レベルで同じ結果が保証されるわけではありません。
- **1 日あたりのレート制限が適用されます。** API には、本番環境とテスト環境の両方で 1 日あたりの使用制限があります。使用制限に達した場合は、[Stripe support](https://support.stripe.com/) にお問い合わせください。

## 次のステップ

- [顧客の住所を収集](https://docs.stripe.com/tax/customer-locations.md)すれば、Stripe Tax が計算で住所を使用する方法を確認できます。
- [Tax API を使用して税を計算](https://docs.stripe.com/tax/custom.md)すれば、検証済みの住所を税計算に使用できます。