# 税金の計算にカスタムの手数料を導入する

販売商品に追加の課税対象手数料を追加します。

税金を計算する際に商品に手数料を追加し、それらの手数料の税金を計算する必要がある場合があります。

## カスタム手数料を追加

Stripe Tax モジュールは、注文、請求書、クレジットメモを作成した時点でリクエストを作成し、それを [Stripe Tax calculation API](https://docs.stripe.com/api/tax/calculations.md) に送信します。モジュールは、見積もり、インボイス、クレジットメモのアイテムを処理して、アイテムの詳細または注文全体を計算リクエストに追加します。

税金の計算が必要なカスタム手数料を追加する場合は、税金計算リクエストが追加できるように、Stripe Tax モジュールに詳細を指定する必要があります。

この実装では、カスタム手数料を実装する開発者がオブザーバーを介してカスタム手数料の合計額を提供します。カスタム手数料は Tax Calculation API リクエストに追加され、計算のために Stripe に送信されます。

## Stripe Tax モジュールの仕組み

Stripe Tax モジュールは、手数料が発生する場所に基づいて手数料を追加します。

- 項目レベルでは、見積もり、請求書、クレジットメモの各項目に税金が適用されます。
- 見積もり、注文、請求書、クレジットメモのレベルでは、カート全体に税金が適用されます。

サードパーティー開発者は、次の詳細を送信する必要があります。

- カスタム手数料の合計価格 (項目にカスタム税が 3 で、項目の数量が 2 の場合、送信される値は 6)
- カスタム手数料の税種別
- カスタム手数料のコード

これら 3 つのコンポーネントは、次の構造の配列で転送されます。

```php
$details = [
    'amount' => $amountValue, // generic value—provide your own when developing
    'tax_class_id' => $classId, // generic value—provide your own when developing
    'code' => 'custom_fee' // generic value—provide your own when developing
];
```

実行するアクション (見積もりの計算、インボイスの作成、クレジットメモの作成) およびカスタム手数料の適用場所 (アイテム、見積もり、インボイス、クレジットメモのレベル) に基づいて、この配列構造を送信する必要があります。

オブジェクトは、この情報を Tax モジュールに送信し、その情報の追加先のオブジェクトを指定します。オブザーバーは、注文プロセスの段階とカスタム手数料を適用すべき場所に応じて、以下の 6 つのイベントのいずれかをリッスンする必要があります。

- `stripe_tax_additional_fee_item` は注文の項目に適用されます。
- `stripe_tax_additional_fee_quote` は見積もりに適用されます。
- `stripe_tax_additional_fee_invoice_item` は請求書項目に適用されます。
- `stripe_tax_additional_fee_invoice` は請求書全体に適用されます。
- `stripe_tax_additional_fee_creditmemo_item` はクレジットメモ項目に適用されます。
- `stripe_tax_additional_fee_creditmemo` はクレジットメモ全体に適用されます。

各イベントには、`additional_fees_container` という Magento データオブジェクトが含まれ、Stripe Tax モジュールによる計算が必要な内容の詳細を追加できます。税金計算の詳細を追加するには、詳細配列をパラメーターとして指定し、`->addAdditionalFee()` メソッドを呼び出します。

```php
$additionalFees = $observer->getAdditionalFeesContainer();

// other operations to get the values to send forward

$details = [
    'amount' => $amountValue, // generic value—provide your own when developing
    'tax_class_id' => $classId, // generic value—provide your own when developing
    'code' => 'custom_fee' // generic value—provide your own when developing
];

$additionalFees->addAdditionalFee($details);
}
```

これらの追加手数料が親または子アイテム (バンドルにする動的な商品など) に追加される可能性がある場合、バンドルにする商品とその中の商品の両方のイベントを送信します。

バンドル商品や、最上位の商品とサブ商品の数量を個別に指定できるその他の商品を使用する場合は、追加手数料の金額を送信し、親項目と子項目の両方の数量を考慮します。

Stripe が請求書の税金を計算した後、税金と基準税額の配列を受け取ります。必要に応じて、この情報を使用してデータベースにカスタムフィールドを設定できます。この配列には、キーとしての手数料コードと、それに設定された計算値が格納されます。配列には、項目または請求書で `getAdditionalFeesTax()` メソッドを呼び出してアクセスできます。

### 見積もりレベルでアイテムに税を適用する例

イベントファイル (`app/code/Vendor/YourModule/etc/events.xml`) 内に、以下のイベントを追加します。

```xml
<event name="stripe_tax_additional_fee_item">
    <observer name="your_custom_observer_name" instance="Vendor\YourModule\Observer\AddAdditionalFeeForQuoteItem" />
</event>
```

`additional_fees_container` 以外で、イベントに指定されるデータは以下のとおりです。

- `item`: 税金の計算対象となる項目。
- `quote`: 項目が属する見積もり。

オブザーバーファイル (`app/code/Vendor/YourModule/Observer/AddAdditionalFeeForQuoteItem.php`) 内に、計算の詳細を作成するためのコードを追加します。以下に例を示します。

```php
<?php

namespace Vendor\YourModule\Observer;

use \Magento\Framework\Event\ObserverInterface;
use \Magento\Framework\Event\Observer;

class AddAdditionalFeeForQuoteItem implements ObserverInterface
{

    public function execute(Observer $observer)
    {
        $additionalFees = $observer->getAdditionalFeesContainer();
        $item = $observer->getItem();
        $quote = $observer->getQuote();

        // Calculations where you determine that the item has an additional tax and the tax needs to be calculated
        // After the calculations are complete and you have the values, add them to the details array and send the array forward

        $itemDetails = [
                'amount' => $amount, // generic value determined from previous calculations—provide your own when developing
                'tax_class_id' => $taxClassId, // generic value determined from previous calculations—provide your own when developing
                'code' => 'custom_fee' // generic value—provide your own when developing
            ];

        $additionalFees->addAdditionalFee($itemDetails);
    }
}
```

### 見積もりレベルで税を適用する例

イベントファイル (`app/code/Vendor/YourModule/etc/events.xml`) 内に、以下のイベントを追加します。

```xml
<event name="stripe_tax_additional_fee_quote">
    <observer name="stripe_tax_additional_fee_quote" instance="Vendor\YourModule\Observer\AddAdditionalFeeForQuote" />
</event>
```

`additional_fees_container` 以外で、イベントに指定されるデータは以下のとおりです。

1. `quote`: 税金の計算に使用される見積もり
1. `total`: この時点までで収集された合計額

オブザーバーファイル (`app/code/Vendor/YourModule/Observer/AddAdditionalFeeForQuote.php`) 内に、計算の詳細を作成するためのコードを追加します。以下に例を示します。

```php
<?php

namespace Vendor\YourModule\Observer;

use \Magento\Framework\Event\ObserverInterface;
use \Magento\Framework\Event\Observer;

class AddAdditionalFeeForQuote implements ObserverInterface
{

    public function execute(Observer $observer)
    {
        $additionalFees = $observer->getAdditionalFeesContainer();
        $quote = $observer->getQuote();
        $total = $observer->getTotal();

        // Calculations where you determine that the quote has an additional tax and the tax needs to be calculated
        // After the calculations are done and you have the values, add them to the details array and send the array forward

        $details = [
                'amount' => $amount, // generic value determined from previous calculations—provide your own when developing
                'tax_class_id' => $taxClassId, // generic value determined from previous calculations—provide your own when developing
                'code' => 'custom_fee' // generic value—provide your own when developing
            ];

        $additionalFees->addAdditionalFee($details);
    }
}
```

### インボイスレベルでアイテムに税金を適用する場合の例

イベントファイル (`app/code/Vendor/YourModule/etc/events.xml`) 内に、以下のイベントを追加します。

```xml
<event name="stripe_tax_additional_fee_invoice_item">
    <observer name="your_custom_observer_name" instance="Vendor\YourModule\Observer\AddAdditionalFeeForInvoiceItem" />
</event>
```

`additional_fees_container` 以外で、イベントに指定されるデータは以下のとおりです。

- `item`: 税金が計算される項目。オブザーバーは注文項目などのその他の詳細を提供します。
- `invoice`: 項目が属する請求書。請求書から項目の順序などの情報を取得できます。

オブザーバーファイル (`app/code/Vendor/YourModule/Observer/AddAdditionalFeeForInvoiceItem.php`) 内に、計算の詳細を作成するためのコードを追加します。以下に例を示します。

```php
<?php

namespace Vendor\YourModule\Observer;

use \Magento\Framework\Event\ObserverInterface;
use \Magento\Framework\Event\Observer;

class AddAdditionalFeeForInvoiceItem implements ObserverInterface
{

    public function execute(Observer $observer)
    {
        $additionalFees = $observer->getAdditionalFeesContainer();
        $item = $observer->getItem();
        $invoice = $observer->getInvoice();

        // Calculations where you determine that the item has an additional tax and the tax needs to be calculated
        // After the calculations are complete and you have the values, add them to the details array and send the array forward

        $itemDetails = [
                'amount' => $amount, // generic value determined from previous calculations, provide your own when developing
                'tax_class_id' => $taxClassId, // generic value determined from previous calculations, provide your own when developing
                'code' => 'custom_fee' // generic value, provide your own when developing
            ];

        $additionalFees->addAdditionalFee($itemDetails);
    }
}
```

### インボイスレベルで税を適用する場合の例

イベントファイル (`app/code/Vendor/YourModule/etc/events.xml`) 内に、以下のイベントを追加します。

```xml
<event name="stripe_tax_additional_fee_invoice">
    <observer name="stripe_tax_additional_fee_quote" instance="Vendor\YourModule\Observer\AddAdditionalFeeForInvoice" />
</event>
```

`additional_fees_container` 以外で、イベントに指定されるデータは以下のとおりです。

1. `invoice`: カスタム手数料が適用されるインボイス
1. `order`: インボイスが属する注文

オブザーバーファイル (`app/code/Vendor/YourModule/Observer/AddAdditionalFeeForInvoice.php`) 内に、計算の詳細を作成するためのコードを追加します。以下に例を示します。

```php
<?php

namespace Vendor\YourModule\Observer;

use \Magento\Framework\Event\ObserverInterface;
use \Magento\Framework\Event\Observer;

class AddAdditionalFeeForInvoice implements ObserverInterface
{

    public function execute(Observer $observer)
    {
        $additionalFees = $observer->getAdditionalFeesContainer();
        $invoice = $observer->getInvoice();
        $order = $observer->getOrder();

        // Calculations where you determine that the invoice has an additional tax and the tax needs to be calculated
        // After the calculations are complete and you have the values, add them to the details array and send the array forward

        $details = [
                'amount' => $amount, // generic value determined from previous calculations, please provide your own when developing
                'tax_class_id' => $taxClassId, // generic value determined from previous calculations—provide your own when developing
                'code' => 'custom_fee' // generic value—provide your own when developing
            ];

        $additionalFees->addAdditionalFee($details);
    }
}
```

### クレジットメモへの変更

クレジットメモを作成すると、Stripe Tax モジュールに渡す必要がある配列の構造が変わります。`tax_class_id` は配列から削除され、`amount_tax` フィールドには、カスタム手数料に対して返金する税額を含める必要があります。

```php
$details = [
    'amount' => $amount,
    'amount_tax' => $taxAmount,
    'code' => 'custom_fee'
];
```

> 詳細配列の `code` コンポーネントは、請求書ステップで指定されたコードコンポーネントと同じである必要があります。これにより、Stripe は返金額を差し引く対象のコンポーネントを認識できます。

### クレジットメモレベルでアイテムに税金を適用する場合の例

イベントファイル (`app/code/Vendor/YourModule/etc/events.xml`) 内に、以下のイベントを追加します。

```xml
<event name="stripe_tax_additional_fee_creditmemo_item">
    <observer name="your_custom_observer_name" instance="Vendor\YourModule\Observer\AddAdditionalFeeForCreditmemoItem" />
</event>
```

`additional_fees_container` 以外で、イベントに指定されるデータは以下のとおりです。

- `item`: 税金が計算される項目。オブザーバーは注文項目など、その他の詳細も提供します。
- `creditmemo`: 項目が属するクレジットメモ。
- `invoice`: 項目が属する請求書。
- `order`: 項目が属する注文。

オブザーバーファイル (`app/code/Vendor/YourModule/Observer/AddAdditionalFeeForCreditmemoItem.php`) 内に、計算の詳細を作成するためのコードを追加します。以下に例を挙げます。

```php
<?php

namespace Vendor\YourModule\Observer;

use \Magento\Framework\Event\ObserverInterface;
use \Magento\Framework\Event\Observer;

class AddAdditionalFeeForCreditmemoItem implements ObserverInterface
{

    public function execute(Observer $observer)
    {
        $additionalFees = $observer->getAdditionalFeesContainer();
        $item = $observer->getItem();
        $creditmemo = $observer->getCreditmemo();
        $invoice = $observer->getInvoice();
        $order = $observer->getOrder();

        // Calculations where you determine that the item has an additional tax and the tax needs to be refunded
        // After the calculations are complete and you have the values, add them to the details array and send the array forward

        $itemDetails = [
                'amount' => $amount, // generic value determined from previous calculations, please provide your own when developing
                'tax_amount' => $taxAmount, // generic value determined from previous calculations, please provide your own when developing
                'code' => 'custom_fee' // generic value, please provide your own when developing
            ];

        $additionalFees->addAdditionalFee($itemDetails);
    }
}
```

### クレジットメモレベルで税金を適用する例

イベントファイル (`app/code/Vendor/YourModule/etc/events.xml`) 内に、以下のイベントを追加します。

```xml
<event name="stripe_tax_additional_fee_creditmemo">
    <observer name="stripe_tax_additional_fee_quote" instance="Vendor\YourModule\Observer\AddAdditionalFeeForCreditmemo" />
</event>
```

`additional_fees_container` 以外で、イベントに指定されるデータは以下のとおりです。

- `creditmemo`: 項目が属するクレジットメモ。
- `invoice`: 項目が属する請求書。
- `order`: 項目が属する注文。

オブザーバーファイル (`app/code/Vendor/YourModule/Observer/AddAdditionalFeeForCreditmemo.php`) 内に、計算の詳細を作成するためのコードを追加します。以下に例を示します。

```php
<?php

namespace Vendor\YourModule\Observer;

use \Magento\Framework\Event\ObserverInterface;
use \Magento\Framework\Event\Observer;

class AddAdditionalFeeForInvoice implements ObserverInterface
{

    public function execute(Observer $observer)
    {
        $additionalFees = $observer->getAdditionalFeesContainer();
        $creditmemo = $observer->getCreditmemo();
        $invoice = $observer->getInvoice();
        $order = $observer->getOrder();

        // Calculations where you determine that the invoice has an additional tax and the tax needs to be refunded
        // After the calculations are complete and you have the values, add them to the details array and sent the array forward

        $details = [
                'amount' => $amount, // generic value determined from previous calculations, please provide your own when developing
                'tax_amount' => $taxClassId, // generic value determined from previous calculations, please provide your own when developing
                'code' => 'custom_fee' // generic value, please provide your own when developing
            ];

        $additionalFees->addAdditionalFee($details);
    }
}
```