# Integrieren Sie eine nutzerdefinierte Gebühr in die Steuerberechnung

Fügen Sie den verkauften Produkten zusätzliche steuerpflichtige Gebühren hinzu.

Möglicherweise müssen Sie bei der Berechnung der Steuer Gebühren zu den Produkten hinzufügen und dann die Steuer für diese Gebühren berechnen.

## Nutzerdefinierte Gebühr hinzufügen

Das Stripe Tax-Modul erstellt Anfragen zum Zeitpunkt der Erstellung von Bestellungen, Rechnungen und Gutschriften und sendet sie an die [Stripe Tax Calculation API](https://docs.stripe.com/api/tax/calculations.md). Das Modul durchläuft die Positionen des Angebots, der Rechnung oder der Gutschrift, um die Details der Positionen oder der gesamten Bestellung zur Berechnungsanforderung hinzuzufügen.

Wenn Sie eine nutzerdefinierte Gebühr hinzufügen, die eine Steuerberechnung erfordert, müssen Sie die Details im Stripe Tax-Modul angeben, damit sie bei der Anfrage zur Steuerberechnung hinzugefügt werden kann.

In dieser Integration stellt die/der Entwickler/in der benutzerdefinierten Gebühr den Gesamtwert der benutzerdefinierten Gebühr über einen Observer bereit. Die benutzerdefinierte Gebühr wird der Anfrage an die Tax Calculation API hinzugefügt und zur Berechnung an Stripe gesendet.

## So funktioniert das Stripe Tax-Modul

Das Stripe Tax-Modul fügt Gebühren hinzu, je nachdem, wo diese anfallen:

- Auf Postenebene gilt die Steuer für jeden Posten des Angebots, der Rechnung und der Gutschrift.
- Auf Angebots-, Bestell-, Rechnungs- oder Gutschriftsebene gilt die Steuer für den gesamten Warenkorb.

Der Drittentwickler muss folgende Angaben übermitteln:

- Der Gesamtpreis der Zollgebühr (wenn für einen Artikel eine Zollgebühr von 3 gilt und die Artikelmenge 2 beträgt, wird der Wert 6 übermittelt)
- Die Steuerklasse für die nutzerdefinierte Gebühr
- Der Code der nutzerdefinierten Gebühr

Diese drei Komponenten werden in einem Array mit folgender Struktur weitergeleitet:

```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
];
```

Sie müssen diese Array-Struktur basierend auf der ausgeführten Aktion (Angebotsberechnung, Rechnungserstellung oder Gutschriftserstellung) und dem Ort, an dem die nutzerdefinierte Gebühr anfällt (Artikel-, Angebots-, Rechnungs- oder Gutschriftsstufe), senden.

Nach der Überprüfung werden die Informationen an das Steuermodul gesendet und ein Objekt bereitgestellt, dem die Informationen hinzugefügt werden. Bei der Überprüfung muss je nach Phase des Bestellvorgangs und dem Ort, an dem die nutzerdefinierte Gebühr erhoben werden muss, eines der folgenden sechs Ereignisse berücksichtigt werden:

- `stripe_tax_additional_fee_item` gilt für die Artikel einer Bestellung.
- `stripe_tax_additional_fee_quote` gilt für das Angebot.
- `stripe_tax_additional_fee_invoice_item` gilt für Rechnungspositionen.
- `stripe_tax_additional_fee_invoice` gilt für die gesamte Rechnung.
- `stripe_tax_additional_fee_creditmemo_item` gilt für Gutschriftsposten.
- `stripe_tax_additional_fee_creditmemo` gilt für die gesamte Gutschrift.

Jedes der Ereignisse enthält ein Magento-Datenobjekt mit dem Namen `additional_fees_container`, in dem Sie die Details dessen hinzufügen können, was vom Stripe Tax-Modul berechnet werden muss. Um die Details der Steuerberechnung hinzuzufügen, rufen Sie die Methode `->addAdditionalFee()` mit dem Details-Array als Parameter auf:

```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);
}
```

In Fällen, in denen diese zusätzlichen Gebühren entweder für einen übergeordneten oder untergeordneten Artikel (zum Beispiel ein gebündeltes dynamisches Produkt) hinzugefügt werden können, senden wir Ereignisse sowohl für das gebündelte Produkt als auch für die darin enthaltenen Produkte.

Wenn Sie gebündelte Produkte oder andere Produkte verwenden, bei denen Sie die Menge des übergeordneten Produkts und des Unterprodukts separat angeben können, senden Sie den Betrag der zusätzlichen Gebühr und berücksichtigen Sie die Menge der übergeordneten und untergeordneten Artikel.

Nachdem Stripe die Steuer für die Rechnungen berechnet hat, erhalten Sie ein Array mit der Steuer und der Basissteuer. Mit diesen Informationen können Sie bei Bedarf benutzerdefinierte Felder in der Datenbank festlegen. Das Array enthält den Gebührencode als Schlüssel und die dafür festgelegten berechneten Werte. Sie können auf das Array zugreifen, indem Sie die Methode `getAdditionalFeesTax()` im Posten oder auf der Rechnung aufrufen.

### Beispiel für die Anwendung der Steuer auf den Artikel auf Angebotsebene

Fügen Sie innerhalb Ihrer Ereignisdatei (`app/code/Vendor/YourModule/etc/events.xml`) das folgende Ereignis hinzu:

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

Die Daten, die zusätzlich zum `additional_fees_container` für das Ereignis bereitgestellt werden, sind:

- `item`: Der Artikel, für den die Steuer berechnet wird.
- `quote`: Das Angebot, zu dem der Posten gehört.

Fügen Sie in Ihrer Observer-Datei (`app/code/Vendor/YourModule/Observer/AddAdditionalFeeForQuoteItem.php`) den Code zum Erstellen der Berechnungsdetails hinzu, wie im folgenden Beispiel gezeigt:

```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);
    }
}
```

### Beispiel für die Anwendung der Steuer auf Angebotsebene

Fügen Sie innerhalb Ihrer Ereignisdatei (`app/code/Vendor/YourModule/etc/events.xml`) das folgende Ereignis hinzu:

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

Die Daten, die zusätzlich zum `additional_fees_container` für das Ereignis bereitgestellt werden, sind:

1. `quote`: Das Angebot, für das die Steuer berechnet wird
1. `total`: Die gesammelten Summen bis zu diesem Punkt

Fügen Sie in Ihrer Überwachungsdatei (`app/code/Vendor/YourModule/Observer/AddAdditionalFeeForQuote.php`) den Code zum Erstellen der Berechnungsdetails hinzu, wie im folgenden Beispiel gezeigt:

```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);
    }
}
```

### Beispiel für die Anwendung der Steuer auf den Artikel auf Rechnungsebene

Fügen Sie innerhalb Ihrer Ereignisdatei (`app/code/Vendor/YourModule/etc/events.xml`) das folgende Ereignis hinzu:

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

Die Daten, die zusätzlich zum `additional_fees_container` für das Ereignis bereitgestellt werden, sind:

- `item`: Der Posten, für den die Steuer berechnet wird. Der Observer liefert weitere Details, wie zum Beispiel den Bestellposten.
- `invoice`: Die Rechnung, zu der der Posten gehört—Sie können Informationen wie die Bestellung des Postens aus der Rechnung erhalten.

Fügen Sie in Ihrer Observer-Datei (`app/code/Vendor/YourModule/Observer/AddAdditionalFeeForInvoiceItem.php`) den Code zum Erstellen der Berechnungsdetails hinzu, wie im folgenden Beispiel gezeigt:

```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);
    }
}
```

### Beispiel für die Anwendung von Steuern auf Rechnungsebene

Fügen Sie innerhalb Ihrer Ereignisdatei (`app/code/Vendor/YourModule/etc/events.xml`) das folgende Ereignis hinzu:

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

Bei den Daten, die dem Ereignis zur Verfügung gestellt werden, handelt es sich abgesehen von `additional_fees_container` um:

1. `invoice`: Die Rechnung, auf der die nutzerdefinierte Gebühr erhoben wird
1. `order`: Der Auftrag, zu dem die Rechnung gehört

Fügen Sie in Ihrer Überwachungsdatei(`app/code/Vendor/YourModule/Observer/AddAdditionalFeeForInvoice.php`) den Code zum Erstellen der Berechnungsdetails hinzu, wie im folgenden Beispiel gezeigt:

```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);
    }
}
```

### Änderungen an Gutschriften

Beim Erstellen von Gutschriften ändert sich die Struktur des Arrays, das an das Stripe Tax-Modul zurückgegeben werden muss. Die `tax_class_id` wird aus dem Array entfernt und das Feld `amount_tax` muss den Steuerbetrag enthalten, den Sie für die benutzerdefinierte Gebühr zurückerstatten möchten.

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

> Die `code`-Komponente des Detail-Arrays muss dieselbe Codekomponente sein, die im Rechnungsschritt angegeben wurde. Dadurch wird sichergestellt, dass Stripe weiß, von welcher Komponente die erstatteten Beträge abgezogen werden sollen.

### Beispiel für die Anwendung der Steuer auf die Position auf Gutschriftebene

Fügen Sie innerhalb Ihrer Ereignisdatei (`app/code/Vendor/YourModule/etc/events.xml`) das folgende Ereignis hinzu:

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

Die Daten, die zusätzlich zum `additional_fees_container` für das Ereignis bereitgestellt werden, sind:

- `item`: Der Posten, für den die Steuer berechnet wird. Der Observer liefert auch weitere Details, wie zum Beispiel den Bestellposten.
- `creditmemo`: Die Gutschrift, zu der der Posten gehört.
- `invoice`: Die Rechnung, zu der der Posten gehört.
- `order`: Die Bestellung, zu der der Posten gehört.

Fügen Sie in Ihrer Überwachungsdatei (`app/code/Vendor/YourModule/Observer/AddAdditionalFeeForCreditmemoItem.php`) den Code zum Erstellen der Details für die Berechnung wie im folgenden Beispiel hinzu:

```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);
    }
}
```

### Beispiel für die Anwendung von Steuern auf Gutschriftebene

Fügen Sie innerhalb Ihrer Ereignisdatei (`app/code/Vendor/YourModule/etc/events.xml`) das folgende Ereignis hinzu:

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

Die Daten, die zusätzlich zum `additional_fees_container` für das Ereignis bereitgestellt werden, sind:

- `creditmemo`: Die Gutschrift, zu der der Posten gehört.
- `invoice`: Die Rechnung, zu der der Posten gehört.
- `order`: Die Bestellung, zu der der Posten gehört.

Fügen Sie in Ihrer Observer-Datei (`app/code/Vendor/YourModule/Observer/AddAdditionalFeeForCreditmemo.php`) den Code zum Erstellen der Berechnungsdetails hinzu, wie im folgenden Beispiel gezeigt:

```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);
    }
}
```