Entwickler

Diese Seite richtet sich an Entwickler, die das Modul erweitern oder in eigene Abläufe einbinden möchten. Modul-Namespace: Geissweb\Euvat.

Events

Das Modul stellt einen eigenen Event-Hook bereit und übernimmt zugleich die Steuerung einiger Magento-Standard-Events.

Eigener Event: vat_validation_after

Wird nach jeder USt-IdNr.-Prüfung in Geissweb\Euvat\Validator\BaseValidator ausgelöst – unabhängig davon, ob die Nummer gültig, ungültig oder technisch fehlgeschlagen ist. Nutzen Sie ihn, um auf Prüfergebnisse zu reagieren (z. B. eigenes Logging, ERP-Sync, Benachrichtigungen).

Payload:

Schlüssel	Typ
validation_result	Geissweb\Euvat\Api\Data\ValidationResultInterface

Eigenen Observer registrieren (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();
        }
    }
}

Beobachtete Magento-Standard-Events

Event	Observer	Zweck
customer_login	Observer\CustomerLogin	Revalidierung beim Login.
sales_quote_address_save_before	Observer\QuoteAddressSaveBefore	Validierungsdaten an die Quote-Adresse schreiben.
estimate_tax_based_on_country	Observer\AfterEstimateTaxBasedOnCountry	Pseudo-Registry für das Steuerland.
customer_address_save_before	Observer\BeforeAddressSaveObserver	Ersetzt den Core-VIV-Observer.
customer_address_save_after	Observer\AfterAddressSaveObserver	Ersetzt den Core-VIV-Observer.
admin_system_config_changed_section_euvat	Observer\Adminhtml\ConfigObserver	Reaktion auf Konfigurationsänderungen.

Service Contracts (API)

Die öffentlichen Schnittstellen liegen unter Geissweb\Euvat\Api. Bevorzugen Sie diese gegenüber konkreten Modellklassen.

ValidationRepositoryInterface

Zugriff auf den Validierungs-Cache (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);
}

Beispiel – gecachtes Ergebnis zu einer Nummer lesen:

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

Weitere Interfaces

Interface	Zweck
Api\Data\ValidationInterface	Persistierter Cache-Datensatz (Getter/Setter, Feldkonstanten).
Api\Data\ValidationResultInterface	Ergebnis einer einzelnen Prüfung (inkl. warning, error, retry_available, Trader-Daten).
Api\Data\ValidationSearchResultsInterface	Suchergebnis-Container für getList().
Api\CaseIdentifierInterface	Ermittelt aus Rechnungs-/Versandadresse die Kundensteuerklasse (identifyCustomerTaxClass()) und das Steuerziel (identifyTaxDestination()).

DI-Präferenzen (etc/di.xml): ValidationRepositoryInterface → Model\ValidationRepository, Data\ValidationInterface → Model\Validation.

Console-Commands

geissweb:clean:vatnumbers

Bereinigt bestehende USt-IdNrn. in Kundenadressen (entfernt Leerzeichen/Sonderzeichen und doppelte Länderpräfixe) und entfernt syntaktisch ungültige Nummern. Säubert zusätzlich Datensätze in der vat_validation-Tabelle.

# 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

Selbsttest: berechnet die Steuer für die unterstützten Szenarien und zeigt die Ergebnisse als Tabelle. Nützlich, um nach der Konfiguration zu prüfen, ob die Steuerregeln und -klassen wie erwartet greifen.

bin/magento geissweb:selftest:vatcalc