KSeF - National e-Invoice System

KSeF ist eine Plattform des polnischen Finanzministeriums für strukturierte Rechnungen. Das Plugin bereitet Ihren Shop auf die KSeF-Integration vor - es erkennt Bestellungen, die eine MwSt.-Rechnung erfordern, fügt eine Statusspalte und Hooks für die Integration mit Fakturierungssystemen hinzu.

Rechtlicher Status von KSeF

KSeF befindet sich in der Einführungsphase. Das Plugin stellt keine Rechnungen in KSeF aus, erleichtert aber die Integration mit Systemen, die dies tun (z. B. Fakturownia, iFirma, wFirma, InFakt).

Hauptfunktionen des KSeF-Moduls:

1. Automatische Erkennung von Bestellungen mit einer NIP-Nummer
2. KSeF-Statusspalte in der Bestellliste
3. Hooks für die Integration mit externen Fakturierungssystemen
4. Bestell-Metadaten, bereit zur Übergabe an das KSeF-System

Erkennung von Bestellungen mit NIP

Wenn ein Kunde bei der Bestellaufgabe eine NIP angibt (das NIP-Feld ist Teil des Checkout-Moduls), führt das Plugin automatisch Folgendes aus:

1. Validiert das NIP-Format (10 Ziffern, Prüfsummenverifizierung)
2. Markiert die Bestellung als eine, die eine MwSt.-Rechnung erfordert
3. Speichert die NIP in den Bestell-Metadaten
4. Ruft optional Unternehmensdaten aus der GUS/CEIDG-API ab

NIP-Validierung

Das Plugin prüft die Korrektheit der NIP auf zwei Ebenen:

• Format - 10 Ziffern, korrekte Prüfsumme (Gewichtungen: 6, 5, 7, 2, 3, 4, 5, 6, 7)
• Online-Verifizierung - optionale Prüfung in der VIES-Datenbank (für EU-NIPs) oder GUS-API

KSeF-Statusspalte

In der Bestellliste (WooCommerce > Bestellungen) erscheint eine Spalte KSeF mit Statussymbolen:

Symbol	Status	Beschreibung
Grau	Nicht zutreffend	Bestellung ohne NIP, keine Rechnung erforderlich
Blau	Ausstehend	Bestellung mit NIP, Rechnung auszustellen
Grün	Ausgestellt	Rechnung wurde ausgestellt (Status durch Hook gesetzt)
Rot	Fehler	Bei der Rechnungsausstellung ist ein Problem aufgetreten

Sie können Bestellungen nach KSeF-Status filtern, z. B. nur diejenigen anzeigen, die auf eine Rechnung warten.

Massenaktionen

In der Bestellliste können Sie mehrere Bestellungen gesammelt als “in KSeF ausgestellt” markieren.

Hooks

polski/ksef/invoice_ready

Wird ausgelöst, wenn eine Bestellung mit NIP bezahlt und zur Rechnungsausstellung bereit ist. Der Haupt-Hook für die Integration mit Fakturierungssystemen.

/**
 * @param int      $order_id   WooCommerce order ID.
 * @param WC_Order $order      Order object.
 * @param string   $nip        Customer NIP number.
 * @param array    $invoice_data Invoice data (company name, address, NIP).
 */
add_action('polski/ksef/invoice_ready', function (int $order_id, WC_Order $order, string $nip, array $invoice_data): void {
    // Example: send data to the Fakturownia API
    $api_token = get_option('fakturownia_api_token');
    $account = get_option('fakturownia_account');

    $invoice_payload = [
        'invoice' => [
            'kind'             => 'vat',
            'number'           => null, // auto-numbering
            'sell_date'        => $order->get_date_paid()->format('Y-m-d'),
            'issue_date'       => current_time('Y-m-d'),
            'payment_type'     => 'transfer',
            'seller_name'      => get_option('woocommerce_store_name'),
            'buyer_name'       => $invoice_data['company_name'],
            'buyer_tax_no'     => $nip,
            'buyer_street'     => $invoice_data['address'],
            'buyer_city'       => $invoice_data['city'],
            'buyer_post_code'  => $invoice_data['postcode'],
            'positions'        => [],
        ],
    ];

    foreach ($order->get_items() as $item) {
        $invoice_payload['invoice']['positions'][] = [
            'name'       => $item->get_name(),
            'quantity'   => $item->get_quantity(),
            'total_price_gross' => $item->get_total() + $item->get_total_tax(),
            'tax'        => round(($item->get_total_tax() / $item->get_total()) * 100),
        ];
    }

    $response = wp_remote_post("https://{$account}.fakturownia.pl/invoices.json", [
        'body'    => wp_json_encode($invoice_payload),
        'headers' => [
            'Content-Type' => 'application/json',
            'Authorization' => 'Token token=' . $api_token,
        ],
    ]);

    if (!is_wp_error($response) && wp_remote_retrieve_response_code($response) === 201) {
        $body = json_decode(wp_remote_retrieve_body($response), true);
        update_post_meta($order_id, '_ksef_status', 'issued');
        update_post_meta($order_id, '_ksef_invoice_id', $body['id'] ?? '');
    } else {
        update_post_meta($order_id, '_ksef_status', 'error');
    }
}, 10, 4);

polski/ksef/is_required

Filter, mit dem Sie programmgesteuert bestimmen können, ob eine Bestellung eine KSeF-Rechnung erfordert.

/**
 * @param bool     $is_required Whether a KSeF invoice is required.
 * @param WC_Order $order       Order object.
 * @return bool
 */
add_filter('polski/ksef/is_required', function (bool $is_required, WC_Order $order): bool {
    // Example: require KSeF invoice for orders above 450 PLN
    if ($order->get_total() > 450) {
        return true;
    }

    return $is_required;
}, 10, 2);

Beispiel - automatische Statusmarkierung nach Integration

/**
 * Update KSeF status after receiving a response from the invoicing system.
 */
add_action('my_invoicing/invoice_created', function (int $order_id, string $ksef_number): void {
    $order = wc_get_order($order_id);
    if (!$order) {
        return;
    }

    $order->update_meta_data('_ksef_status', 'issued');
    $order->update_meta_data('_ksef_number', $ksef_number);
    $order->add_order_note(
        sprintf('Invoice issued in KSeF. KSeF number: %s', $ksef_number)
    );
    $order->save();
}, 10, 2);

Bestell-Metadaten

Das KSeF-Modul speichert die folgenden Metadaten in Bestellungen:

Meta-Schlüssel	Beschreibung
_billing_nip	NIP-Nummer des Kunden
_billing_company	Firmenname
_ksef_required	Ob die Bestellung eine Rechnung erfordert (yes/no)
_ksef_status	Rechnungsstatus (pending, issued, error)
_ksef_number	KSeF-Rechnungsnummer (nach Ausstellung)
_ksef_invoice_id	Rechnungs-ID im externen System

Konfiguration

Einstellungen des KSeF-Moduls: WooCommerce > Einstellungen > Polski > KSeF.

Option	Beschreibung	Standardwert
KSeF-Modul aktivieren	Aktiviert Erkennung und Nachverfolgung	Ja
Online-NIP-Validierung	NIP in GUS/VIES-API prüfen	Nein
Unternehmensdaten automatisch abrufen	Daten aus GUS nach Eingabe der NIP abrufen	Nein
Auslösestatus für Hook	Bestellstatus, bei dem invoice_ready ausgelöst wird	processing

Fehlerbehebung

Die KSeF-Spalte wird nicht in der Bestellliste angezeigt Klicken Sie auf “Ansicht anpassen” und aktivieren Sie das Kontrollkästchen für die KSeF-Spalte. Stellen Sie sicher, dass das Modul in den Einstellungen aktiviert ist.

Die NIP wird nicht in der Bestellung gespeichert Prüfen Sie, ob das NIP-Feld unter WooCommerce > Einstellungen > Polski > Checkout aktiviert ist. Das Feld muss aktiv sein, damit Kunden es ausfüllen können.

Der Hook invoice_ready wird nicht ausgelöst Prüfen Sie die Einstellung “Auslösestatus für Hook”. Standardmäßig wird der Hook beim Status “In Bearbeitung” ausgelöst. Ändern Sie diese Option bei benutzerdefinierten Status.

Nächste Schritte

• Probleme melden: GitHub Issues
• Diskussionen und Fragen: GitHub Discussions

Diese Seite dient ausschließlich zu Informationszwecken und stellt keine Rechtsberatung dar. Konsultieren Sie vor der Implementierung einen Anwalt. Polski for WooCommerce ist Open-Source-Software (GPLv2), die ohne Gewährleistung bereitgestellt wird.