Développeur

Cette page s'adresse aux développeurs qui souhaitent étendre le module ou l'intégrer à leurs propres processus. Namespace du module : Geissweb\Euvat.

Événements

Le module fournit son propre hook d'événement et prend en charge en parallèle la gestion de quelques événements standard de Magento.

Événement propre : vat_validation_after

Déclenché après chaque validation de numéro de TVA dans Geissweb\Euvat\Validator\BaseValidator – que le numéro soit valide, invalide ou que la validation ait techniquement échoué. Utilisez-le pour réagir aux résultats de validation (par ex. journalisation personnalisée, synchronisation ERP, notifications).

Payload :

Clé	Type
validation_result	Geissweb\Euvat\Api\Data\ValidationResultInterface

Enregistrer votre propre observateur (etc/events.xml) :

<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:framework:Event/etc/events.xsd">
    <event name="vat_validation_after">
        <observer name="mycompany_vat_validation_after"
                  instance="MyCompany\Module\Observer\VatValidationAfter"/>
    </event>
</config>

declare(strict_types=1);

namespace MyCompany\Module\Observer;

use Geissweb\Euvat\Api\Data\ValidationResultInterface;
use Magento\Framework\Event\Observer;
use Magento\Framework\Event\ObserverInterface;

class VatValidationAfter implements ObserverInterface
{
    public function execute(Observer $observer): void
    {
        /** @var ValidationResultInterface $result */
        $result = $observer->getEvent()->getData('validation_result');

        if ($result->getVatIsValid()) {
            // z. B. registrierten Firmennamen weiterverarbeiten
            $name = $result->getVatTraderName();
        }
    }
}

Événements standard de Magento observés

Event	Observer	Objectif
customer_login	Observer\CustomerLogin	Revalidation lors de la connexion.
sales_quote_address_save_before	Observer\QuoteAddressSaveBefore	Écriture des données de validation dans l'adresse de la quote.
estimate_tax_based_on_country	Observer\AfterEstimateTaxBasedOnCountry	Pseudo-registry pour le pays de taxation.
customer_address_save_before	Observer\BeforeAddressSaveObserver	Remplace l'observateur VIV du cœur.
customer_address_save_after	Observer\AfterAddressSaveObserver	Remplace l'observateur VIV du cœur.
admin_system_config_changed_section_euvat	Observer\Adminhtml\ConfigObserver	Réaction aux modifications de configuration.

Service Contracts (API)

Les interfaces publiques se trouvent sous Geissweb\Euvat\Api. Préférez-les aux classes de modèle concrètes.

ValidationRepositoryInterface

Accès au cache de validation (vat_validation).

namespace Geissweb\Euvat\Api;

interface ValidationRepositoryInterface
{
    public function save(Data\ValidationInterface $validation): Data\ValidationInterface;
    public function get(int $validationId): Data\ValidationInterface;
    public function getList(SearchCriteriaInterface $searchCriteria): SearchResults;
    public function delete(Data\ValidationInterface $validation): bool;
    public function deleteById(int $validationId): bool;
    /** @return Data\ValidationInterface|AbstractModel  (false, wenn nicht vorhanden) */
    public function getByVatId(string $vatId);
}

Exemple – lire le résultat mis en cache pour un numéro :

public function __construct(
    private readonly \Geissweb\Euvat\Api\ValidationRepositoryInterface $validationRepository
) {
}

public function isCachedValid(string $vatId): bool
{
    $entry = $this->validationRepository->getByVatId($vatId);

    return $entry !== false
        && $entry->getVatIsValid()
        && $entry->getVatRequestSuccess();
}

Autres interfaces

Interface	Objectif
Api\Data\ValidationInterface	Enregistrement de cache persisté (getter/setter, constantes de champ).
Api\Data\ValidationResultInterface	Résultat d'une validation individuelle (incl. warning, error, retry_available, données de l'opérateur).
Api\Data\ValidationSearchResultsInterface	Conteneur de résultats de recherche pour getList().
Api\CaseIdentifierInterface	Détermine, à partir de l'adresse de facturation/livraison, la classe de taxe client (identifyCustomerTaxClass()) et la destination de taxation (identifyTaxDestination()).

Préférences DI (etc/di.xml) : ValidationRepositoryInterface → Model\ValidationRepository, Data\ValidationInterface → Model\Validation.

Commandes de console

geissweb:clean:vatnumbers

Nettoie les numéros de TVA existants dans les adresses des clients (supprime les espaces/caractères spéciaux et les préfixes pays en double) et supprime les numéros syntaxiquement invalides. Nettoie en outre les enregistrements de la table vat_validation.

# Probelauf (Dry-Run) – zeigt nur an, ändert nichts
bin/magento geissweb:clean:vatnumbers

# Änderungen tatsächlich anwenden
bin/magento geissweb:clean:vatnumbers execute

geissweb:selftest:vatcalc

Autotest : calcule la taxe pour les scénarios pris en charge et affiche les résultats sous forme de tableau. Utile pour vérifier, après la configuration, si les règles et classes de taxe s'appliquent comme prévu.

bin/magento geissweb:selftest:vatcalc