Installation für Agenturen

Diese Anleitung richtet sich ausschließlich an Agenturen und technische Shop-Administratoren mit Datei-, Composer-, Konsolen- und Datenbankzugriff. Einstellungen und tägliche Prüfabläufe für Shop-Betreiber sind unter Bedienung für Shop-Betreiber beschrieben.

Paket passend zur OXID-Hauptversion wählen

Verwenden Sie ausschließlich das zur Shop-Hauptversion gehörende Paket:

Paketauswahl

Shop

Ausgabe

Ziel

OXID eShop 7 ab 7.1

Twig

vendor/ecs/ustidchk

OXID eShop 6 ab 6.1

Smarty

source/modules/ecs/UStIDOnline

Warnung

Die OXID-6- und OXID-7-Pakete sind nicht austauschbar. Sichern Sie vor Installation und Update mindestens die Projekt-composer.json, die Shopdatenbank, die OXID-Konfiguration und den vorhandenen Modulordner. Prüfzeitpunkte und API-Antworten liegen in der Shopdatenbank und müssen in deren Sicherungs- und Datenschutzkonzept einbezogen werden.

Voraussetzungen

Prüfen Sie vor der Installation:

  • Im aktiven Subshop ist unter den Stammdaten eine gültige deutsche Shop-USt-IdNr. eingetragen. Sie wird als anfragende USt-IdNr. verwendet.

  • Die PHP-Erweiterungen cURL und SimpleXML sind im Webserver beziehungsweise in PHP-FPM verfügbar. Das OXID-7-Paket verlangt zusätzlich PHP ab Version 8.0; maßgeblich bleiben die höheren Anforderungen der eingesetzten OXID-Version.

  • Der Shopserver erreicht https://api.evatr.vies.bzst.de/app/v1/abfrage per HTTPS; Firewall, DNS, Proxy und CA-Zertifikate dürfen die Verbindung nicht verhindern.

  • Der Prüfdienst darf maximal 30 Sekunden Antwortzeit beanspruchen. PHP- und Webserver-Zeitlimits müssen den Checkout trotzdem kontrolliert behandeln.

  • Die Rechnungsadressfelder Firma, Ort, PLZ, Straße, Hausnummer, Land und USt-IdNr. stehen im verwendeten Theme und Checkout zur Verfügung.

  • Ein vollständiges Datenbankbackup und ein Wiederherstellungsweg wurden geprüft.

Achtung

Bei jeder Anfrage werden Shop- und Kunden-USt-IdNr. sowie Firma, Ort, PLZ und Straße an den externen Prüfdienst übertragen. Klären Sie vor dem Live-Betrieb Datenschutzhinweise, Auftragsabläufe, Zugriffsrechte und Aufbewahrung. Das Modul selbst trifft keine rechtliche Bewertung.

OXID 7 installieren

1. Moduldateien kopieren

Kopieren Sie das vollständige Twig-Paket nach:

vendor/ecs/ustidchk

Prüfen Sie danach insbesondere metadata.php, composer.json, services.yaml, assets, src, translations und views des ausgelieferten OXID-7-Pakets.

2. Namespace in der Projekt-composer.json registrieren

Ergänzen Sie in der composer.json des Shop-Hauptverzeichnisses unter autoload / psr-4:

"Ecs\\UStIDOnline\\": "vendor/ecs/ustidchk/src/"

Vollständiges Beispiel mit einem vorhandenen Namespace:

{
    "autoload": {
        "psr-4": {
            "Vorhandener\\Namespace\\": "vendor/vorhandener/anbieter/modul/src/",
            "Ecs\\UStIDOnline\\": "vendor/ecs/ustidchk/src/"
        }
    }
}

Der Eintrag gehört in die Projekt-composer.json, nicht in die Datei des Moduls. Vorhandene Namespaces bleiben erhalten. Ein zusätzlicher Eintrag unter require ist bei dieser manuellen Installation nicht notwendig.

3. Autoloader und Modul installieren

Führen Sie im Shop-Hauptverzeichnis aus:

composer dump-autoload
vendor/bin/oe-console oe:module:install vendor/ecs/ustidchk
vendor/bin/oe-console oe:module:activate ecs_ustidchk
vendor/bin/oe-console oe:cache:clear

Alternativ kann die Aktivierung nach oe:module:install im Admin unter Erweiterungen ‣ Module erfolgen.

4. OXID-7-Installation kontrollieren

Prüfen Sie mindestens:

  • Das Modul ist im Admin sichtbar und aktiv; alle drei Einstellungen sind vorhanden.

  • Das Feld ECSUSTIDCHECK ist in oxorder vorhanden und die OXID-Views wurden aktualisiert.

  • Kundenkonto, Checkout, Kundenverwaltung und Bestellübersicht öffnen ohne Twig-, Block- oder Controllerfehler.

  • Ein kontrollierter EU-Testkunde erhält ein verständliches Prüfergebnis.

  • Eine erfolgreiche Testbestellung erhält einen Prüfzeitpunkt und eine Kundenbemerkung mit der API-Antwort.

  • Der Shopcache wurde geleert.

OXID 6 installieren

1. Moduldateien kopieren

Kopieren Sie das vollständige Smarty-Paket nach:

source/modules/ecs/UStIDOnline

Beachten Sie die Groß- und Kleinschreibung von UStIDOnline. Prüfen Sie mindestens metadata.php, composer.json, Core, Model, translations und views.

2. Namespace in der Projekt-composer.json registrieren

Ergänzen Sie in der composer.json des Shop-Hauptverzeichnisses unter autoload / psr-4:

"Ecs\\UStIDOnline\\": "./source/modules/ecs/UStIDOnline/"

Vollständiges Beispiel:

{
    "autoload": {
        "psr-4": {
            "Vorhandener\\Namespace\\": "./source/modules/vorhandenes/modul/",
            "Ecs\\UStIDOnline\\": "./source/modules/ecs/UStIDOnline/"
        }
    }
}

Alle vorhandenen Namespaces bleiben erhalten. Ein zusätzlicher Eintrag unter require ist für die manuelle Installation nicht notwendig.

3. Autoloader und Modulkonfiguration installieren

Führen Sie im Shop-Hauptverzeichnis aus:

composer dump-autoload
vendor/bin/oe-console oe:module:install-configuration source/modules/ecs/UStIDOnline
vendor/bin/oe-console oe:module:activate ecs_ustidchk

Leeren Sie anschließend die temporären Shopdateien beziehungsweise den OXID-Cache mit dem in der jeweiligen OXID-6-Umgebung vorgesehenen Verfahren.

4. OXID-6-Installation kontrollieren

Prüfen Sie mindestens:

  • Modul und alle drei Einstellungen sind im Admin sichtbar.

  • ECSUSTIDCHECK ist in oxorder und den relevanten OXID-Views vorhanden.

  • Kundenkonto, Smarty-Checkout, Kundenverwaltung und Bestellübersicht öffnen ohne Templatefehler.

  • Onlineprüfung, Steuerberechnung, Prüfzeitpunkt und Kundenbemerkung wurden mit einem kontrollierten EU-Testkunden abgenommen.

  • Die temporären Shopdateien wurden geleert.

Datenbankänderung und Aktivierungsereignisse

Bei der Aktivierung versucht das Modul, folgendes Feld anzulegen:

ALTER TABLE oxorder
  ADD ECSUSTIDCHECK DATETIME NOT NULL
  DEFAULT '0000-00-00 00:00:00'
  AFTER OXISNETTOMODE;

Danach leert es das konfigurierte OXID-Compile-Verzeichnis und regeneriert die Datenbank-Views. Ein bereits vorhandenes Feld bleibt erhalten; ein Fehler des ALTER TABLE-Befehls wird vom Modul nicht im Admin ausgegeben. Kontrollieren Sie die Struktur deshalb ausdrücklich:

SHOW COLUMNS FROM oxorder LIKE 'ECSUSTIDCHECK';

Bei der Deaktivierung entfernt das Modul seine Einträge aus oxtplblocks, leert erneut das Compile-Verzeichnis und regeneriert die Views. Das Feld ECSUSTIDCHECK, vorhandene Zeitstempel und Kundenbemerkungen werden bewusst nicht gelöscht.

Welche Prüfdaten werden gespeichert?

Nur nach einer vom Modul akzeptierten Prüfung werden dauerhaft gespeichert:

  • der Prüfzeitpunkt in oxorder.ECSUSTIDCHECK und

  • die vollständige JSON-Antwort des Prüfdienstes als OXID-Bemerkung oxremark mit Typ r beim Bestellkunden.

Die Bemerkung kann unter anderem Status, Ergebniskennzeichen und vom Dienst gelieferte Prüfinformationen enthalten. Das Modul speichert in der Bemerkung keine eigene Modul-ID und keine Bestell-ID. Bei Gastbestellungen versucht es, die Bemerkung ebenfalls dem von OXID für die Bestellung verwendeten Kundenobjekt zuzuordnen. Kann OXID dieses Kundenobjekt nicht laden, wird im OXID-7-Paket keine Bemerkung angelegt; der erfolgreiche Prüfzeitpunkt wird trotzdem an der Bestellung gespeichert.

Im laufenden Storefront-Prozess wird die API-Antwort zusätzlich in der OXID-Sitzung unter ustidcheck wiederverwendet. Ändert der Kunde seine relevanten Benutzerdaten, entfernt das Modul diesen Sitzungswert und prüft erneut. Mit dem Ende beziehungsweise der Bereinigung der Sitzung verschwindet dieser temporäre Wert.

Modul aktualisieren

OXID 7 aktualisieren

Deaktivieren Sie das Modul für den Dateiaustausch. Ersetzen Sie den vollständigen Ordner vendor/ecs/ustidchk durch das aktuelle OXID-7-/Twig-Paket. Führen Sie danach aus:

composer dump-autoload
vendor/bin/oe-console oe:module:install vendor/ecs/ustidchk
vendor/bin/oe-console oe:module:activate ecs_ustidchk
vendor/bin/oe-console oe:cache:clear

OXID 6 aktualisieren

Deaktivieren Sie das Modul und ersetzen Sie source/modules/ecs/UStIDOnline vollständig durch das aktuelle OXID-6-/Smarty-Paket. Führen Sie danach aus:

composer dump-autoload
vendor/bin/oe-console oe:module:install-configuration source/modules/ecs/UStIDOnline
vendor/bin/oe-console oe:module:activate ecs_ustidchk

Leeren Sie anschließend die temporären Shopdateien.

Nach jedem Update

  • Prüfen Sie das Feld ECSUSTIDCHECK und die aktualisierten OXID-Views.

  • Kontrollieren Sie alle drei Einstellungen; neue Paketvorgaben setzen vorhandene Betreiberwerte nicht automatisch zurück.

  • Testen Sie Onlineprüfung und Steuerberechnung in Kundenkonto und Checkout.

  • Prüfen Sie mit einer Testbestellung Zeitstempel und JSON-Bemerkung.

  • Kontrollieren Sie eine bestehende erfolgreich geprüfte Bestellung im Admin und bei einer Neuberechnung.

Prüfdaten bereinigen

Einzelne Bestellung und zugehörige Bemerkung

Warnung

Prüfzeitpunkt und API-Antwort können Teil des steuerlichen Nachweises sein. Löschen oder verändern Sie sie nur nach Freigabe durch die verantwortliche Stelle und nach einer gesicherten Archivierung. Ohne Backup ist die Bereinigung nicht rückgängig zu machen.

Für eine gezielte Bereinigung:

  1. Ermitteln Sie die konkrete Bestellung, den Bestellkunden und den gespeicherten Prüfzeitpunkt im Admin.

  2. Prüfen Sie die Bemerkungen des Kunden. Die Modulbemerkung ist eine JSON-Antwort mit BZSt-Status; sie trägt jedoch keine eigene Modul- oder Bestellkennung.

  3. Sichern Sie die Bestellung und die exakt ausgewählte Bemerkung.

  4. Löschen Sie nur die zuvor anhand ihrer OXID geprüfte Bemerkung.

  5. Setzen Sie bei Bedarf den Prüfzeitpunkt der konkreten Bestellung zurück:

    UPDATE oxorder
SET ECSUSTIDCHECK = '0000-00-00 00:00:00'
WHERE OXID = 'GEPRUEFTE_BESTELL_OXID';

  6. Regenerieren Sie die OXID-Views und leeren Sie den Shopcache.

Achtung

Löschen Sie Bemerkungen nicht pauschal nur nach OXTYPE = 'r'. Dies würde auch manuelle und von anderen Erweiterungen angelegte Kundenbemerkungen entfernen. Auch eine reine Textsuche nach einem Statuscode muss vor dem Löschen durch eine Liste der konkreten OXID-Werte und eine Sichtprüfung abgesichert werden.

Alle Modulprüfdaten aus dem Shop entfernen

Für eine vollständige, kontrollierte Entfernung:

  1. Deaktivieren Sie ecs_ustidchk und sichern Sie die vollständige Datenbank.

  2. Exportieren Sie alle Bestellungen mit gesetztem ECSUSTIDCHECK sowie alle nach Sichtprüfung eindeutig zugeordneten JSON-Bemerkungen.

  3. Löschen Sie die geprüften Bemerkungen ausschließlich über ihre konkreten OXID-Werte.

  4. Setzen Sie die Zeitstempel zurück, wenn das Feld für eine spätere Reaktivierung erhalten bleiben soll:

    UPDATE oxorder
SET ECSUSTIDCHECK = '0000-00-00 00:00:00'
WHERE ECSUSTIDCHECK IS NOT NULL
  AND ECSUSTIDCHECK <> '0000-00-00 00:00:00';

  5. Soll das Modul dauerhaft entfernt werden, löschen Sie das Feld erst nach der Datenbereinigung:

    ALTER TABLE oxorder DROP COLUMN ECSUSTIDCHECK;

  6. Regenerieren Sie die OXID-Views, leeren Sie Cache und temporäre Dateien und kontrollieren Sie Bestell- und Kunden-Admin.

  7. Entfernen Sie erst danach den Modulordner und den zugehörigen PSR-4-Eintrag aus der Projekt-composer.json; führen Sie anschließend composer dump-autoload aus.

Die in OXID gespeicherten Moduleinstellungen werden durch das Zurücksetzen der Prüfdaten nicht automatisch entfernt. Bereinigen Sie sie bei einer endgültigen Deinstallation mit den für die eingesetzte OXID-Hauptversion vorgesehenen Modulwerkzeugen und kontrollieren Sie anschließend oxtplblocks.

Datenaufbewahrung bei Deaktivierung

Eine normale Deaktivierung bewahrt ECSUSTIDCHECK und sämtliche Kundenbemerkungen auf. Bei erneuter Aktivierung stehen die bisherigen Prüfzeitpunkte weiter zur Verfügung; erfolgreich geprüfte Bestandsbestellungen werden im Admin weiterhin als solche erkannt. Es gibt keine automatische Aufbewahrungsfrist und keine automatische Bereinigung historischer Prüfantworten.

Technische Abnahme

Testen Sie mit freigegebenen Testdaten mindestens:

  1. deutsche Kunden, ausländische EU-Kunden mit und ohne USt-IdNr. sowie einen Nicht-EU-Kunden,

  2. gültige und ungültige USt-IdNr., abweichende Firma, Ort, Straße und PLZ,

  3. beide Zustände der Einstellung für Straße und PLZ,

  4. Kundenkonto, Gast-Checkout, angemeldeten Checkout und Kunden-Admin,

  5. Umsatzsteuerberechnung vor und nach einer fehlgeschlagenen Prüfung,

  6. erfolgreiche Bestellung, gespeicherten Prüfzeitpunkt und JSON-Bemerkung,

  7. Neuberechnung einer erfolgreich geprüften Bestandsbestellung,

  8. Verhalten bei blockierter Verbindung, DNS-Fehler und Zeitüberschreitung sowie

  9. alle betroffenen Subshops mit jeweils eigener deutscher Shop-USt-IdNr.

Verwenden Sie keine realen Kundendaten in ungeschützten Testsystemen und löschen Sie Testbestellungen und Bemerkungen nach dem vereinbarten Verfahren.

Technische Fehlerbehebung

Onlineprüfung ist nicht verfügbar

  • Prüfen Sie PHP-cURL in der PHP-Version des Webservers, nicht nur auf der Konsole.

  • Testen Sie DNS, HTTPS-Ausgang, Firewall, Proxy und CA-Zertifikate zum konfigurierten BZSt-Endpunkt.

  • Kontrollieren Sie die deutsche Shop-USt-IdNr. und die Formatierung beider USt-IdNrn. Leerzeichen und Satzzeichen entfernt das Modul selbst.

  • Das Modul behandelt fehlende, nicht decodierbare oder statuslose Antworten als nicht bestätigt und gewährt dann keine Umsatzsteuerbefreiung.

Datenbankfeld fehlt

Prüfen Sie Datenbankrechte und Serverprotokolle. Das Aktivierungsereignis unterdrückt den konkreten ALTER TABLE-Fehler. Legen Sie das Feld nur nach Backup und Prüfung mit dem oben dokumentierten SQL an, regenerieren Sie die Views und leeren Sie den Cache.

Prüfung passt nicht zur Steuerberechnung

  • Prüfen Sie Kundenland, EU-Zuordnung des Landes, USt-IdNr. und Rechnungsadresse.

  • Kontrollieren Sie die Einstellung für Straße und PLZ. Firma muss immer bestätigt sein; Ort muss bestätigt oder vom Prüfdienst als nicht prüfbar gemeldet sein.

  • Löschen Sie bei Tests die aktuelle Kundensitzung oder ändern und speichern Sie die relevanten Kundendaten, damit kein vorheriges Sitzungsergebnis wiederverwendet wird.

  • Prüfen Sie bei Bestandsbestellungen den gespeicherten ECSUSTIDCHECK-Zeitpunkt; im Admin bewahrt er die umsatzsteuerfreie Behandlung bei einer Neuberechnung.

Block- oder Darstellungsfehler

Kontrollieren Sie die zur OXID-Hauptversion passenden Smarty- oder Twig-Blöcke, Theme-Overrides, Modulreihenfolge und Übersetzungsdateien. Die Option zum Ausgrauen des Weiter-Buttons wählt im Programm lediglich einen zweiten Meldungsschlüssel. In den aktuell untersuchten deutschen und englischen Paketübersetzungen sind beide Meldungen identisch; eine zuverlässige Buttonsperre wird dadurch nicht umgesetzt. Die steuerliche Entscheidung darf deshalb nicht anhand der sichtbaren Schaltfläche getestet werden.

Übergabe an den Shop-Betreiber

Übergeben Sie mindestens:

  • die geprüfte Shop-USt-IdNr. für jeden Subshop,

  • die gewählten Werte aller drei Moduleinstellungen,

  • das Ergebnis der Checkout- und Steuerberechnungstests,

  • Speicherorte, Zugriffsrechte, Aufbewahrungs- und Löschverfahren für Prüfzeitpunkte und Kundenbemerkungen,

  • das Vorgehen bei Ausfall des externen Prüfdienstes,

  • die fachliche Verantwortlichkeit für abweichende Prüfergebnisse sowie

  • den Link zur Bedienung für Shop-Betreiber.