# Stripe Billing でサポート対象外のシステムの税額を使用する

サポート対象外の外部システムで計算した税金を Stripe 請求書で使用する。

[Stripe App Marketplace](https://docs.stripe.com/tax/third-party-apps.md) でサポートされているアプリがないサードパーティーの税金エンジンを使用して税金を計算する場合は、[tax_amounts](https://docs.stripe.com/api/invoice-line-item/update.md#update_line-tax_amounts) パラメーターを使用して請求書に税額を手動で設定できます。

Stripe に税金を計算させるには、[Stripe Tax](https://docs.stripe.com/tax.md) を使用します。

## 手動で設定した税額を使用して請求書を作成する

このセクションでは、手動で設定した税額を請求書のラインアイテムに追加する方法について説明します。

### 請求書のアイテムを使用して請求書を作成する

最初のステップは、請求書を作成することです。顧客はすでに作成しているものとして説明します。まだ作成していない場合は、[顧客](https://docs.stripe.com/invoicing/customer.md)ガイドをご覧ください。

```curl
curl https://api.stripe.com/v1/invoices \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d customer="{{CUSTOMER_ID}}"
```

手動で設定した税額は、請求書のラインアイテムにのみ追加できます。そのため、請求書のアイテムを請求書に追加してください。

```curl
curl https://api.stripe.com/v1/invoiceitems \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d customer="{{CUSTOMER_ID}}" \
  -d invoice="{{INVOICE_ID}}" \
  -d amount=100 \
  -d currency=usd
```

### 請求書の項目を税額で更新する

[請求書の明細項目](https://docs.stripe.com/api/invoices/update_line.md)を更新する際に税額を直接設定するには、[tax_amounts](https://docs.stripe.com/api/invoice-line-item/update.md#update_line-tax_amounts) パラメーターを使用します。顧客に関連情報が表示されるように、`tax_amounts` とともに [tax_rate_data](https://docs.stripe.com/api/invoice-line-item/update.md#update_line-tax_amounts-tax_rate_data) を指定する必要があります。次の例は、`tax_amounts` フィールドを使用して請求書の明細項目を更新する方法を示しています。

```curl
curl https://api.stripe.com/v1/invoices/{{INVOICE_ID}}/lines/il_0O4tNe589O8KAxCGYD7OyXPP \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "tax_amounts[0][amount]"=10 \
  -d "tax_amounts[0][taxable_amount]"=100 \
  -d "tax_amounts[0][tax_rate_data][percentage]"=10 \
  -d "tax_amounts[0][tax_rate_data][inclusive]"=false \
  -d "tax_amounts[0][tax_rate_data][tax_type]"=sales_tax \
  -d "tax_amounts[0][tax_rate_data][display_name]"="Sales Tax" \
  -d "tax_amounts[0][tax_rate_data][description]"="Texas Sales Tax" \
  -d "tax_amounts[0][tax_rate_data][jurisdiction]"=Texas \
  -d "tax_amounts[0][tax_rate_data][jurisdiction_level]"=state \
  -d "tax_amounts[0][tax_rate_data][country]"=US \
  -d "tax_amounts[0][tax_rate_data][state]"=TX
```

`tax_amounts` 以下のフィールドは、`description`、`jurisdiction`、`jurisdiction_level`、`country`、`state`、`tax_type` を除きすべて必須です。[請求書の項目オブジェクト](https://docs.stripe.com/api/invoice-line-item/object.md)は `tax_amounts` フィールドを返します。

```json
{
  id: "il_0O4tNe589O8KAxCGYD7OyXPP",
  object: "line_item",
  amount: 100,
  amount_excluding_tax: 100,
  currency: "usd",
  ...
  tax_amounts: [
    {
      amount: 10,
      inclusive: false,
      tax_rate: "txr_0Ns7kW589O8KAxCGXoi7EAuS",
      taxability_reason: null,
      taxable_amount: 100
    }
  ],
  tax_rates: [],
  ...
}
```

> Stripe は `tax_rate_data` に基づいて既存の税率を自動的に作成または再利用しますが、請求書の税額の計算は、amount パラメーターのみに基づいて行います。それ以外の値 (税率など) は請求書に表示する際のレンダリングにのみ使用します。これらのフィールドと指定された税額に矛盾がないかどうかを確認するための検証は行われません。

### 請求書を確定する

税額を使用して請求書のラインアイテムがすべて更新されたら、請求書を確定する必要があります。請求書を確定した後に税額を変更することはできません。確定後に請求書を変更する必要がある場合は、[請求書の編集](https://docs.stripe.com/invoicing/invoice-edits.md)ガイドをご覧ください。

```curl
curl -X POST https://api.stripe.com/v1/invoices/{{INVOICE_ID}}/finalize \
  -u "<<YOUR_SECRET_KEY>>:"
```

## Stripe が税率を自動生成する

税額を手動設定する場合、Stripe は対応する税率の情報を要求します。この税率は顧客に情報を表示する目的でのみ使用し、計算には一切使用されません。

Stripe は、`tax_rate_data` に基づいてバックグラウンドで税率オブジェクトを自動的に作成します。同じ税率データが複数回渡された場合、Stripe は別の税率オブジェクトを作成するのではなく、既存の税率オブジェクトを参照します。税率の重複排除には、`percentage`、`inclusive`、`display_name`、`jurisdiction`、`jurisdiction_level`、`country`、`state`、`tax_type` の各フィールドが使用されます。この例では、前セクションの請求書で 2 つ目の請求書項目が同じ `tax_rate_data` で更新されたと仮定します。

```curl
curl https://api.stripe.com/v1/invoices/{{INVOICE_ID}}/lines/il_0P6nbg589O8KAxCGRWBJAdNV \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "tax_amounts[0][amount]"=50 \
  -d "tax_amounts[0][taxable_amount]"=500 \
  -d "tax_amounts[0][tax_rate_data][percentage]"=10 \
  -d "tax_amounts[0][tax_rate_data][inclusive]"=false \
  -d "tax_amounts[0][tax_rate_data][tax_type]"=sales_tax \
  -d "tax_amounts[0][tax_rate_data][display_name]"="Sales Tax" \
  -d "tax_amounts[0][tax_rate_data][description]"="Texas Sales Tax" \
  -d "tax_amounts[0][tax_rate_data][jurisdiction]"=Texas \
  -d "tax_amounts[0][tax_rate_data][jurisdiction_level]"=state \
  -d "tax_amounts[0][tax_rate_data][country]"=US \
  -d "tax_amounts[0][tax_rate_data][state]"=TX
```

```json
{
  id: "il_0P6nbg589O8KAxCGRWBJAdNV",
  object: "line_item",
  amount: 100,
  amount_excluding_tax: 100,
  currency: "usd",
  ...
  tax_amounts: [
    {
      amount: 10,
      inclusive: false,
      tax_rate: "txr_0Ny6QR589O8KAxCGo6MKGPxM",
      taxability_reason: null,
      taxable_amount: 100
    }
  ],
  tax_rates: [],
  ...
}
```

双方の請求書の項目には、`tax_amount` の下に同じ `tax_rate` ID が設定されます。事業者の負担を最小限に抑えるために、Stripe が税率の作成と重複排除の処理を行います。`tax_rate` ID は有効な税率オブジェクトにマッピングされますが、自動作成された税率にマッピングされている ID を、API の `tax_rates` フィールドに渡すことはできません。このルールの唯一の例外は、クレジットノート作成エンドポイントです。

## クレジットノートを発行する

クレジットノートを使用すると、請求書を無効にすることなく請求書を調整できます。請求書のラインアイテムを手動で設定した税額に更新するクレジットノートを発行すると、API はクレジットノートを正確に作成するために追加の情報を要求します。

### クレジットノートを作成する

クレジットノート作成エンドポイントは、`tax_amounts` パラメーターを受け付けます。対応する請求書のラインアイテムに手動で設定した税額が含まれている場合、このフィールドは必須です。そうすることで、クレジットノートの会計処理が正確に行われ、請求書との一貫性が確保されます。

```curl
curl https://api.stripe.com/v1/credit_notes \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d invoice="{{INVOICE_ID}}" \
  -d reason=duplicate \
  -d "lines[0][type]"=invoice_line_item \
  -d "lines[0][invoice_line_item]"=il_0O4tNe589O8KAxCGYD7OyXPP \
  -d "lines[0][tax_amounts][0][amount]"=10 \
  -d "lines[0][tax_amounts][0][taxable_amount]"=100 \
  -d "lines[0][tax_amounts][0][tax_rate]"=txr_0Ns7kW589O8KAxCGXoi7EAuS
```

## 制限事項

手動で設定した税額を使用する際には、次の制約があることに注意してください。

### 請求書のアイテムには税額は含まれません

手動で設定した税額は、請求書のラインアイテムにのみ追加できます。

### taxable_amount と tax_rates は検証されません

リクエストで渡された課税対象額と税率のデータはレンダリングでのみ使用されます。リクエスト内の税額と照らし合わせた検証は行われません。

### tax_amounts と tax_rates を組み合わせて使用することはできません

請求書のラインアイテムに税率もある場合は、手動設定した税額を含めることはできず、その逆に、手動設定した税額がある場合は税率を含めることはできません。また、請求書にデフォルトの税率がある場合や、請求書の他のラインアイテムに税率がある場合、ラインアイテムに手動設定した税額を含めることはできません。

### 他のフィールドを更新すると、tax_amounts は最新でなくなる可能性があります。

手動で設定された既存の税額は、直接編集しない限り請求書のラインアイテムに残るため、`amount`、`discounts`、`price` などその金額に関係するフィールドで[請求書アイテムを更新](https://docs.stripe.com/api/invoiceitems/update.md)すると、税額が最新でなくなる可能性があります。

### 自動生成された税率は直接使用できません

Stripe は手動で設定された税額に対する税率オブジェクトを自動生成します。これらの税率を請求書や決済関連のエンドポイントで直接参照することはできませんが、クレジットノートエンドポイントからは参照できます。また、これらの税率は直接更新することができず、すべての税率エンドポイントに含まれません。ただし、トークンを使用して税率取得エンドポイントを呼び出すと、税率のデータにアクセスすることは可能です。