NIP at checkout

Geschäftskunden benötigen an der Kasse ein NIP-Feld, um eine Umsatzsteuerrechnung zu erhalten. Polski for WooCommerce fügt ein NIP-Feld mit Prüfsummenvalidierung und GUS-REGON-Verifizierung hinzu. Die Firmendaten werden automatisch ausgefüllt.

Funktionen

Das NIP-Modul verifiziert die Nummer auf drei Ebenen:

Formatvalidierung - Prüfung, ob die Nummer aus 10 Ziffern besteht
Prüfsummenvalidierung - Algorithmus zur Verifizierung der NIP-Prüfziffer
GUS-REGON-Verifizierung - Prüfung in der Datenbank des Statistischen Hauptamtes mit automatischem Abruf der Firmendaten

Konfiguration

Gehen Sie zu WooCommerce > Einstellungen > Polski > Kasse und konfigurieren Sie den Abschnitt “NIP”.

Grundeinstellungen

Einstellung	Standardwert	Beschreibung
NIP-Feld aktivieren	Ja	Fügt der Kassenseite ein NIP-Feld hinzu
Feld erforderlich	Nein	Ob NIP obligatorisch ist
Feldposition	Nach dem Firmenfeld	Wo das NIP-Feld angezeigt wird
Prüfsummenvalidierung	Ja	Prüft die Korrektheit der NIP-Nummer
GUS-REGON-Verifizierung	Nein	Verifiziert NIP in der GUS-Datenbank
Automatisches Ausfüllen	Ja	Ruft die Firmendaten aus GUS ab

Bedingte Anzeige

Das NIP-Feld kann angezeigt werden:

Immer - für alle Kunden sichtbar
Nach dem Anhaken von “Ich möchte eine Rechnung” - erscheint nach dem Anhaken
Nach der Eingabe eines Firmennamens - erscheint, wenn das Feld “Firma” ausgefüllt ist

Die empfohlene Option ist die Anzeige nach dem Anhaken von “Ich möchte eine Rechnung” - dies ist für den Kunden am übersichtlichsten.

Prüfsummenvalidierung

Der NIP-Validierungsalgorithmus basiert auf einem Gewichtungssystem. Die Prüfziffer (letzte, zehnte Ziffer) wird auf Basis der neun vorangehenden Ziffern berechnet.

Algorithmus

Gewichte für die aufeinanderfolgenden NIP-Ziffern: 6, 5, 7, 2, 3, 4, 5, 6, 7

NIP: 1234567890
Sum = 1*6 + 2*5 + 3*7 + 4*2 + 5*3 + 6*4 + 7*5 + 8*6 + 9*7 = 214
Remainder = 214 mod 11
If remainder == last NIP digit -> NIP is valid

Das Plugin validiert sowohl clientseitig (JavaScript) als auch serverseitig (PHP). Die serverseitige Validierung ist immer aktiv.

Behandlung von Eingabeformaten

Das Plugin akzeptiert NIP in verschiedenen Formaten:

1234567890 - nur Ziffern
123-456-78-90 - mit Bindestrichen
123 456 78 90 - mit Leerzeichen
PL1234567890 - mit Länderpräfix

Alle Formate werden vor der Validierung auf 10 Ziffern normalisiert.

GUS-REGON-Verifizierung

API-Konfiguration

Die GUS-REGON-API erfordert einen Zugangsschlüssel. Das Plugin unterstützt zwei Umgebungen:

Umgebung	URL	Schlüssel	Verwendung
Test	`https://wyszukiwarkaregontest.stat.gov.pl/wsBIR/UslugaBIRzewnwordbir.svc`	`abcde12345abcde12345` (öffentlicher Testschlüssel)	Entwicklung und Tests
Produktion	`https://wyszukiwarkaregon.stat.gov.pl/wsBIR/UslugaBIRzewnetrzny.svc`	Ihr eigener Schlüssel von GUS	Live-Shop

Beschaffung eines Produktionsschlüssels

Gehen Sie zu: https://api.stat.gov.pl/Home/BirIndex
Registrieren Sie sich und melden Sie sich an
Reichen Sie einen Antrag auf Zugang zur REGON-API ein
Der Schlüssel wird an die angegebene E-Mail-Adresse gesendet (Wartezeit: 1-3 Werktage)

Plugin-Konfiguration

Gehen Sie zu WooCommerce > Einstellungen > Polski > Kasse > NIP
Aktivieren Sie GUS-REGON-Verifizierung
Wählen Sie die Umgebung: Test oder Produktion
Fügen Sie den API-Schlüssel ein (für die Produktionsumgebung)
Speichern Sie die Einstellungen

Testmodus

Im Testmodus verwendet das Plugin den öffentlichen GUS-Testschlüssel. Die Testdatenbank enthält fiktive Daten. Verwenden Sie sie nur während der Entwicklung und beim Testen.

Automatischer Abruf der Firmendaten

Nach der Verifizierung von NIP in GUS REGON füllt das Plugin automatisch die Formularfelder aus:

WooCommerce-Feld	GUS-Daten
Firma	Firmenname
Adresse 1	Straße und Nummer
Stadt	Stadt
Postleitzahl	Postleitzahl
Bundesland/Region	Woiwodschaft

Der Kunde sieht die ausgefüllten Daten und kann sie vor der Bestellung korrigieren.

Verhalten beim automatischen Ausfüllen

Felder werden nur ausgefüllt, wenn sie leer sind oder zuvor abgerufene GUS-Daten enthalten
Wenn der Kunde die Daten manuell geändert hat, überschreibt das Plugin die Änderungen nicht
Der Kunde wird mit einer Meldung über den Datenabruf informiert

NIP-Speicherung

Die NIP-Nummer wird als Bestellmetadaten gespeichert:

Schlüssel: _billing_nip
sichtbar in der Bestellansicht im Admin-Bereich
verfügbar in E-Mail-Vorlagen
exportierbar in Berichten

Anzeige von NIP in der Bestellung

NIP wird automatisch angezeigt:

in den Bestelldetails (Admin-Bereich)
in der Bestellbestätigungs-E-Mail
auf der Seite “Mein Konto > Bestellungen”

Programmatischer Zugriff

NIP aus einer Bestellung abrufen

$order = wc_get_order($order_id);
$nip = $order->get_meta('_billing_nip');

NIP-Validierung in PHP

function validate_nip(string $nip): bool {
    $nip = preg_replace('/[^0-9]/', '', $nip);

    if (strlen($nip) !== 10) {
        return false;
    }

    $weights = [6, 5, 7, 2, 3, 4, 5, 6, 7];
    $sum = 0;

    for ($i = 0; $i < 9; $i++) {
        $sum += (int) $nip[$i] * $weights[$i];
    }

    return ($sum % 11) === (int) $nip[9];
}

Validierungs-Hook

add_filter('polski/checkout/validate_nip', function (bool $is_valid, string $nip): bool {
    // Additional validation logic
    // e.g. checking against a blocked NIP list
    $blocked_nips = ['0000000000'];

    if (in_array($nip, $blocked_nips, true)) {
        return false;
    }

    return $is_valid;
}, 10, 2);

Häufige Probleme

GUS-Verifizierung gibt einen Fehler zurück

Prüfen Sie, ob der API-Schlüssel korrekt und aktiv ist
Verifizieren Sie, ob der Server eine HTTPS-Verbindung zu api.stat.gov.pl herstellen kann
Die GUS-API kann nicht verfügbar sein - das Plugin behandelt Timeouts und zeigt eine entsprechende Meldung an
Stellen Sie sicher, dass die PHP-SOAP-Erweiterung auf dem Server installiert ist

NIP-Feld wird nicht angezeigt

Prüfen Sie, ob das NIP-Modul aktiviert ist
Verifizieren Sie die Einstellung der bedingten Anzeige
Leeren Sie den Cache (Caching-Plugins können das Kassenformular zwischenspeichern)

Firmendaten werden nicht automatisch ausgefüllt

Prüfen Sie die Browser-Konsole auf AJAX-Fehler
Verifizieren Sie, ob der REST-API-Endpunkt des Plugins erreichbar ist
Stellen Sie sicher, dass die NIP korrekt ist und die Firma in der GUS-Datenbank existiert