Intégrer des frais personnalisés au calcul de la taxe

Ajouter des frais taxables supplémentaires aux produits vendus.

Il peut être nécessaire d’ajouter des frais supplémentaires aux produits lors du calcul de la taxe et de calculer la taxe pour ces frais.

Ajouter des frais personnalisés

Le module Stripe Tax crée des requêtes au moment de la création de la commande, de la facture et de la note de crédit et les envoie à l’API de calcul de Stripe Tax. Le module parcourt les postes du devis, de la facture ou de la note de crédit pour ajouter les détails des postes ou de la commande entière à la demande de calcul.

Si vous ajoutez des frais personnalisés qui nécessitent un calcul de taxe, vous devez fournir les détails au module Stripe Tax afin que la demande de calcul de taxe puisse l’ajouter.

Dans cette intégration, le développeur des frais personnalisés fournit la valeur totale des frais personnalisés par l’intermédiaire d’un observateur, et elle est ajoutée à la requête API pour le calcul de la taxe et envoyée à Stripe pour être calculée.

Fonctionnement du module Stripe Tax

Le module Stripe Tax ajoute les frais supplémentaires en fonction du niveau auquel les frais sont appliqués :

Au niveau des postes (la taxe est appliquée à chaque poste du devis, de la facture et de la note de crédit)

Au niveau du devis, de la commande, de la facture ou de la note de crédit (la taxe est fixée pour l’ensemble du panier et au-delà)

Le développeur tiers doit envoyer les trois informations suivantes :

Le montant total des frais personnalisés (si une taxe personnalisée de 3 s’applique au poste et que la quantité pour le poste est de 2, la valeur envoyée est de 6)
La classe de taxe pour les frais personnalisés
Le code pour les frais personnalisés

Ces trois éléments seront transmis dans un tableau ayant la structure suivante :

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

Vous devez envoyer cette structure de tableau en fonction de l’action effectuée (calcul du devis, création de la facture ou création de la note de crédit) et du niveau auquel les frais personnalisés s’appliquent (niveau du poste, du devis, de la facture ou de la note de crédit).

L’observateur envoie ces informations au module fiscal et fournit un objet auquel les informations sont ajoutées. L’observateur doit écouter l’un des six événements suivants, en fonction de l’étape du processus de commande et du niveau auquel les frais personnalisés doivent être appliqués :

stripe_tax_additional_fee_item s’applique aux postes d’une commande
stripe_tax_additional_fee_quote s’applique au devis
stripe_tax_additional_fee_invoice_item s’applique aux postes de la facture

stripe_tax_additional_fee_invoice s’applique à l’ensemble de la facture
stripe_tax_additional_fee_creditmemo_item s’applique aux postes de la note de crédit
stripe_tax_additional_fee_creditmemo s’applique à l’ensemble de la note de crédit

Chaque événement contient un objet de données Magento appelé additional_fees_container dans lequel vous pouvez ajouter les détails de ce qui doit être calculé par le module Stripe Tax. Pour ajouter les détails du calcul de la taxe, appelez la méthode ->addAdditionalFee() avec le tableau des détails comme paramètre :

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

Dans les cas où ces frais supplémentaires peuvent être ajoutés à un poste parent ou enfant (par exemple, un produit dynamique groupé), nous envoyons des événements à la fois pour le produit groupé et pour les produits qu’il contient.

Lorsque vous utilisez des produits groupés ou d’autres types de produits pour lesquels vous pouvez préciser séparément la quantité du produit principal et du sous-produit, envoyez le montant des frais supplémentaires et tenez compte de la quantité des postes parent et enfant. Quantité des postes parent et enfant.

Une fois que Stripe a calculé la taxe pour les factures, vous recevez un tableau de la taxe et de la taxe de base. Vous pouvez utiliser ces informations pour définir des champs personnalisés dans la base de données si vous en avez besoin. Le tableau contient le code de la taxe comme clé et les valeurs calculées qui sont définies pour ce code. Vous pouvez y accéder en appelant la méthode getAdditionalFeesTax() dans le poste ou sur la facture.

Exemple d’application de la taxe sur le poste au niveau du devis

Dans votre fichier d’événements (app/code/Vendor/YourModule/etc/events.xml), ajoutez l’événement suivant :

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

Les données fournies à l’événement en plus du additional_fees_container sont les suivantes :

item : le poste pour lequel la taxe est calculée
quote : le devis auquel le poste appartient

Dans votre fichier d’observateur (app/code/Vendor/YourModule/Observer/AddAdditionalFeeForQuoteItem.php), ajoutez le code pour créer les détails du calcul comme dans l’exemple suivant :

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

Exemple d’application de la taxe au niveau du devis

Dans votre fichier d’événements (app/code/Vendor/YourModule/etc/events.xml), ajoutez l’événement suivant :

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

Les données fournies à l’événement en plus du additional_fees_container sont les suivantes :

quote : le devis pour lequel la taxe est calculée
total : les totaux collectés jusqu’à ce point

Dans votre fichier d’observateur app/code/Vendor/YourModule/Observer/AddAdditionalFeeForQuote.php, ajoutez le code pour créer les détails du calcul comme dans l’exemple suivant :

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

Exemple d’application de la taxe sur le poste au niveau de la facture

Dans votre fichier d’événements (app/code/Vendor/YourModule/etc/events.xml), ajoutez l’événement suivant :

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

Les données fournies à l’événement en plus du additional_fees_container sont les suivantes :

item : le poste pour lequel la taxe est calculée. Vous pouvez obtenir d’autres détails tels que le poste de commande pour ce poste une seule fois dans l’observateur.

invoice : le devis auquel le poste appartient. Vous pouvez obtenir des informations telles que la commande associée au poste à partir de la facture.

Dans votre fichier d’observateur app/code/Vendor/YourModule/Observer/AddAdditionalFeeForInvoiceItem.php, ajoutez le code pour créer les détails du calcul, comme dans l’exemple suivant :

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

Exemple d’application de la taxe au niveau de la facture

Dans votre fichier d’événements (app/code/Vendor/YourModule/etc/events.xml), ajoutez l’événement suivant :

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

Les données fournies à l’événement, en dehors du additional_fees_container sont les suivantes :

invoice : la facture sur laquelle les frais personnalisés sont appliqués
order : la commande à laquelle la facture est associée

Dans votre fichier d’observateur app/code/Vendor/YourModule/Observer/AddAdditionalFeeForInvoice.php, ajoutez le code pour créer les détails du calcul. Voici un exemple :

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

Modifications des notes de crédit

Lors de la création de notes de crédit, la structure du tableau qui doit être renvoyée au module Stripe Tax change. Le champ tax_class_id est supprimé du tableau et vous obtenez un nouveau champ appelé amount_tax, qui doit contenir le montant de la taxe que vous souhaitez rembourser pour les frais personnalisés.

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

Remarque

Le composant code du tableau des informations doit être le même composant code que celui fourni à l’étape de la facture. Cela permet à Stripe de savoir de quel composant soustraire les montants remboursés.

amounts from.

Exemple d’application de la taxe sur le poste au niveau de la note de crédit

Dans votre fichier d’événements (app/code/Vendor/YourModule/etc/events.xml), ajoutez l’événement suivant :

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

Les données fournies à l’événement en plus du additional_fees_container sont les suivantes :

item : le poste pour lequel la taxe est calculée. Vous pouvez obtenir d’autres détails tels que le poste de commande pour ce poste une seule fois dans l’observateur.
creditmemo : le devis auquel le poste appartient

invoice : le devis auquel le poste appartient
order : le devis auquel le poste appartient

Dans votre fichier d’observateur (app/code/Vendor/YourModule/Observer/AddAdditionalFeeForCreditmemoItem.php), ajoutez le code pour créer les détails du calcul comme dans l’exemple suivant :

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

Exemple d’application de la taxe au niveau de la note de crédit

Dans votre fichier d’événements (app/code/Vendor/YourModule/etc/events.xml), ajoutez l’événement suivant :

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

Les données fournies à l’événement en plus du additional_fees_container sont les suivantes :

creditmemo : le devis auquel le poste appartient
invoice : le devis auquel le poste appartient
order : le devis auquel le poste appartient

Dans votre fichier d’observateur (app/code/Vendor/YourModule/Observer/AddAdditionalFeeForCreditmemo.php), ajoutez le code pour créer les détails du calcul comme dans l’exemple suivant :

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