Accounting integrations

Das Modul verbindet WooCommerce mit den polnischen Rechnungssystemen: wFirma, Fakturownia und iFirma. Rechnungen werden automatisch gesendet, mit Wiederholung bei API-Fehlern.

Voraussetzungen

Polski PRO erfordert: Polski (kostenlos) v1.3.0+, WordPress 6.4+, WooCommerce 8.0+, PHP 8.1+. Zusätzlich ist ein aktives Konto im ausgewählten Buchhaltungssystem mit API-Zugang erforderlich.

Unterstützte Systeme

System	API-Format	API-Version	Authentifizierung
wFirma	XML	v2	API key + API secret
Fakturownia	JSON	v3	API token
iFirma	JSON	v1	Login + API key (Rechnungsschlüssel)

Es kann jeweils nur eine Buchhaltungsintegration aktiv sein.

Konfiguration

Gehen Sie zu WooCommerce > Einstellungen > Polski PRO > Buchhaltung.

Anbieterauswahl

Wählen Sie das Buchhaltungssystem aus und geben Sie die Authentifizierungsdaten an.

wFirma

Einstellung	Beschreibung
API key	API-Schlüssel aus dem wFirma-Panel
API secret	API-Geheimnis
Company ID	Firmenkennung in wFirma
Invoice series	Nummerierungsserie (z. B. “FV”, “FVS”)

Fakturownia

Einstellung	Beschreibung
Subdomain	Subdomain-Name (z. B. mojafirma.fakturownia.pl)
API token	API-Token aus den Kontoeinstellungen
Department ID	Optional - ID der Abteilung, die Rechnungen ausstellt
Invoice language	pl oder en

iFirma

Einstellung	Beschreibung
Login	Login zum iFirma-Konto
Invoice API key	API-Schlüssel zum Ausstellen von Rechnungen
Subscriber API key	API-Schlüssel des Abonnenten (zum Abrufen von Daten)

Gemeinsame Einstellungen

Einstellung	Standardwert	Beschreibung
Automatisches Ausstellen	Ja	Rechnung nach Bezahlung der Bestellung automatisch ausstellen
Auslösender Status	processing	Bestellstatus, der die Rechnungsausstellung auslöst
Dokumenttyp	Umsatzsteuerrechnung	Umsatzsteuerrechnung, Proformarechnung, Quittung
Zur E-Mail hinzufügen	Ja	Rechnungs-PDF an die Bestell-E-Mail anhängen
Wiederholung bei Fehler	Ja	Bei API-Fehler erneut versuchen
Maximale Anzahl an Versuchen	5	Grenze für Wiederholungsversuche

Rechnungssynchronisierung

Automatischer Ablauf

1. Die WooCommerce-Bestellung ändert den Status auf processing (oder einen anderen konfigurierten Status)
2. Das Modul sammelt die Bestelldaten und ordnet sie dem Anbieterformat zu
3. Die Daten werden asynchron an die API des Buchhaltungssystems gesendet
4. Nach erfolgreicher Erstellung wird die Rechnungs-ID im Bestell-Meta gespeichert
5. Das Rechnungs-PDF wird heruntergeladen und an die Kunden-E-Mail angehängt

Datenzuordnung

Das Modul ordnet die WooCommerce-Bestelldaten automatisch dem erforderlichen API-Format zu:

WooCommerce-Daten	wFirma (XML)	Fakturownia (JSON)	iFirma (JSON)
Firmenname	<contractor><name>	buyer_name	Kontrahent.Nazwa
USt-IdNr. (NIP)	<contractor><nip>	buyer_tax_no	Kontrahent.NIP
Adresse	<contractor><street>	buyer_street	Kontrahent.Ulica
Bestellpositionen	<invoicecontents>	positions	Pozycje
Umsatzsteuersatz	<vat_code>	tax	StawkaVat
Zahlungsmethode	<paymentmethod>	payment_type	SposobZaplaty

XML-Format (wFirma)

<api>
  <invoices>
    <invoice>
      <contractor>
        <name>Firma Testowa Sp. z o.o.</name>
        <nip>1234567890</nip>
        <street>ul. Testowa 1</street>
        <city>Warszawa</city>
        <zip>00-001</zip>
      </contractor>
      <invoicecontents>
        <invoicecontent>
          <name>Produkt testowy</name>
          <unit>szt.</unit>
          <count>2</count>
          <price>100.00</price>
          <vat_code>23</vat_code>
        </invoicecontent>
      </invoicecontents>
      <paymentmethod>transfer</paymentmethod>
      <paymentdate>2026-04-12</paymentdate>
    </invoice>
  </invoices>
</api>

JSON-Format (Fakturownia)

{
  "invoice": {
    "kind": "vat",
    "number": null,
    "buyer_name": "Firma Testowa Sp. z o.o.",
    "buyer_tax_no": "1234567890",
    "buyer_street": "ul. Testowa 1",
    "buyer_city": "Warszawa",
    "buyer_post_code": "00-001",
    "positions": [
      {
        "name": "Produkt testowy",
        "quantity": 2,
        "total_price_gross": "246.00",
        "tax": "23"
      }
    ],
    "payment_type": "transfer",
    "payment_to": "2026-04-12"
  }
}

Wiederholungsmechanismus

Exponentielles Backoff

Wenn die API einen Fehler zurückgibt (HTTP 5xx, Timeout, Verbindungsfehler), plant das Modul automatisch einen erneuten Versuch mit exponentiellem Backoff:

Versuch	Verzögerung	Zeit ab dem ersten Versuch
1	Sofort	0 s
2	30 s	30 s
3	2 Min.	2 Min. 30 s
4	8 Min.	10 Min. 30 s
5	32 Min.	42 Min. 30 s

Die Verzögerung wird mit der Formel berechnet: delay = base_delay * 2^(attempt - 1), wobei base_delay = 30 seconds.

Fehler, die nicht wiederholt werden

Client-Fehler (HTTP 4xx) werden nicht automatisch wiederholt, da sie auf ein Datenproblem und nicht auf ein API-Problem hinweisen:

• 400 Bad Request - ungültige Daten
• 401 Unauthorized - falscher API-Token
• 403 Forbidden - unzureichende Berechtigungen
• 422 Unprocessable Entity - Datenvalidierung

Diese Fehler werden protokolliert und erfordern das Eingreifen eines Administrators.

Asynchrones Senden

Rechnungen werden asynchron über WC_Action_Scheduler gesendet, das heißt, sie blockieren den Bestellvorgang nicht. Der Kunde sieht die Bestellbestätigung sofort, und die Rechnung wird im Hintergrund erzeugt.

/**
 * Akcja wywoływana po pomyślnym wystawieniu faktury.
 *
 * @param int    $order_id   ID zamówienia
 * @param string $invoice_id ID faktury w systemie księgowym
 * @param string $provider   Nazwa dostawcy ('wfirma', 'fakturownia', 'ifirma')
 */
do_action('polski_pro/accounting/invoice_created', int $order_id, string $invoice_id, string $provider);

Beispiel - Protokollierung in einem externen System:

add_action('polski_pro/accounting/invoice_created', function (
    int $order_id,
    string $invoice_id,
    string $provider
): void {
    error_log(sprintf(
        '[Polski PRO] Faktura %s wystawiona w %s dla zamówienia #%d',
        $invoice_id,
        $provider,
        $order_id
    ));
}, 10, 3);

Fehler-Hook

/**
 * Akcja wywoływana po wyczerpaniu prób wysłania faktury.
 *
 * @param int    $order_id   ID zamówienia
 * @param string $provider   Nazwa dostawcy
 * @param string $error      Komunikat błędu
 * @param int    $attempts   Liczba wykonanych prób
 */
do_action('polski_pro/accounting/invoice_failed', int $order_id, string $provider, string $error, int $attempts);

Beispiel - Benachrichtigung des Administrators:

add_action('polski_pro/accounting/invoice_failed', function (
    int $order_id,
    string $provider,
    string $error,
    int $attempts
): void {
    $admin_email = get_option('admin_email');
    wp_mail(
        $admin_email,
        sprintf('Błąd wystawienia faktury - zamówienie #%d', $order_id),
        sprintf(
            "Nie udało się wystawić faktury w %s po %d próbach.\n\nBłąd: %s\n\nSprawdź zamówienie: %s",
            $provider,
            $attempts,
            $error,
            admin_url(sprintf('post.php?post=%d&action=edit', $order_id))
        )
    );
}, 10, 4);

Filter für Rechnungsdaten

/**
 * Filtruje dane faktury przed wysłaniem do API.
 *
 * @param array     $invoice_data Dane faktury w formacie dostawcy
 * @param \WC_Order $order        Zamówienie WooCommerce
 * @param string    $provider     Nazwa dostawcy
 */
apply_filters('polski_pro/accounting/invoice_data', array $invoice_data, \WC_Order $order, string $provider): array;

Beispiel - Hinzufügen von Anmerkungen zur Rechnung:

add_filter('polski_pro/accounting/invoice_data', function (
    array $invoice_data,
    \WC_Order $order,
    string $provider
): array {
    if ($provider === 'fakturownia') {
        $invoice_data['invoice']['description'] = sprintf(
            'Zamówienie internetowe #%s',
            $order->get_order_number()
        );
    }
    return $invoice_data;
}, 10, 3);

Administrationsbereich

Synchronisierungsstatus

In der WooCommerce-Bestellliste wird eine Spalte “Rechnung” hinzugefügt, die Folgendes anzeigt:

• Grünes Symbol - Rechnung erfolgreich ausgestellt
• Gelbes Symbol - Senden läuft / Wiederholung
• Rotes Symbol - Fehler (zum Anzeigen der Details klicken)
• Graues Symbol - nicht zutreffend (kein automatisches Ausstellen)

Manuelles Ausstellen

Auf der Seite zur Bestellbearbeitung kann der Administrator im Panel Rechnung:

1. Eine Rechnung manuell ausstellen (falls das automatische Ausstellen fehlgeschlagen ist)
2. Das Rechnungs-PDF herunterladen
3. Das Senden der Rechnung erneut versuchen
4. Das Versuchs- und Fehlerprotokoll ansehen

Fehlerbehebung

Die Rechnung wird nicht automatisch ausgestellt Prüfen Sie, ob der auslösende Status korrekt ist. Stellen Sie sicher, dass der Action Scheduler läuft (WooCommerce > Status > Geplante Aktionen). Prüfen Sie das Fehlerprotokoll unter WooCommerce > Status > Protokolle.

Fehler “Unauthorized” beim Verbinden mit der API Überprüfen Sie die Authentifizierungsdaten. Prüfen Sie bei wFirma, ob API key und secret vom Hauptkonto stammen (nicht von einem Unterkonto). Stellen Sie bei Fakturownia sicher, dass die Subdomain korrekt ist.

Doppelte Rechnungen Das Modul verhindert Duplikate, indem es vor dem Ausstellen das Meta _polski_pro_invoice_id prüft. Falls Duplikate auftreten, prüfen Sie, ob ein anderes Plugin denselben Bestell-Hook auslöst.

Nächste Schritte

• Probleme melden: GitHub Issues
• Verwandt: PRO REST API

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