PRO REST API

REST API im Namespace polski-pro/v1 zur Verwaltung von Rechnungen, Einstellungen und Rechtsdokumenten. Erfordert Authentifizierung und die Berechtigung manage_woocommerce.

Voraussetzungen

Polski PRO erfordert: Polski (kostenlos) v1.6.0+, WordPress 6.4+, WooCommerce 8.0+, PHP 8.1+

Authentifizierung

Die API erfordert zwei Autorisierungselemente:

1. WordPress-Nonce - der Header X-WP-Nonce mit einem durch wp_create_nonce('wp_rest') generierten Wert
2. Berechtigung - der angemeldete Benutzer muss über die Berechtigung manage_woocommerce verfügen

Authentifizierungsbeispiel (JavaScript)

const response = await fetch('/wp-json/polski-pro/v1/invoices', {
    headers: {
        'X-WP-Nonce': wpApiSettings.nonce,
        'Content-Type': 'application/json',
    },
});

Authentifizierungsbeispiel (PHP / cURL)

$nonce = wp_create_nonce('wp_rest');

$response = wp_remote_get(
    rest_url('polski-pro/v1/invoices'),
    [
        'headers' => [
            'X-WP-Nonce' => $nonce,
        ],
    ]
);

Eine Anfrage ohne gültigen Nonce weist WordPress selbst ab, bevor ein Handler läuft. Die fehlende Berechtigung weist dagegen der Endpunkt ab: Die Rechnungs-Endpunkte antworten mit dem Fehlercode polski_pro_forbidden und dem Status 403, auch dann, wenn niemand angemeldet ist, nie mit 401. Die Einstellungs- und Rechtsdokument-Routen greifen auf die WordPress-Vorgabe zurück, also rest_forbidden, mit 401, wenn niemand angemeldet ist, und sonst 403.

Rechnungs-Endpunkte

Rechnungsliste abrufen

GET /wp-json/polski-pro/v1/invoices

Query-Parameter:

Parameter	Typ	Standard	Beschreibung
page	int	1	Seitennummer
per_page	int	20	Ergebnisse pro Seite (max. 100)
status	string	null	Statusfilter: draft, issued, sent, paid, cancelled
type	string	null	Typfilter: faktura_vat, proforma, korygujaca, paragon, packing_slip
order_id	int	null	Filter nach WooCommerce-Bestell-ID

Das sind alle registrierten Parameter. Einen Zeitraumfilter und eine Volltextsuche gibt es hier nicht: Wenn Sie nach Datum oder nach Rechnungsnummer einschränken wollen, filtern Sie die Antwort auf der Clientseite.

Antwort (200 OK):

Der Body ist ein einfaches Array aus Rechnungsobjekten. Die Zähler kommen in den Headern X-WP-Total und X-WP-TotalPages zurück, nicht im Body. Listeneinträge enthalten keine Positionen: items füllt nur der Endpunkt für die einzelne Rechnung.

[
    {
        "id": 1,
        "order_id": 567,
        "original_invoice_id": null,
        "source_refund_id": null,
        "type": "faktura_vat",
        "type_label": "Faktura VAT",
        "number": "FV/2026/04/001",
        "status": "issued",
        "status_label": "Issued",
        "nip_seller": "9876543210",
        "nip_buyer": "1234567890",
        "buyer_name": "Firma Testowa Sp. z o.o.",
        "buyer_address": "ul. Testowa 1",
        "buyer_city": "Warszawa",
        "buyer_postcode": "00-001",
        "correction_reason": null,
        "net_total": 1000.00,
        "vat_total": 230.00,
        "gross_total": 1230.00,
        "currency": "PLN",
        "pdf_path": "/wp-content/uploads/polski-pro/invoices/FV-2026-04-001.pdf",
        "ksef_reference": null,
        "ksef_status": null,
        "issued_at": "2026-04-01T10:30:00+02:00",
        "created_at": "2026-04-01T10:30:00+02:00",
        "items": []
    }
]

Rechnung aus Bestellung erstellen

POST /wp-json/polski-pro/v1/invoices

Body-Parameter (JSON):

Parameter	Typ	Erforderlich	Beschreibung
order_id	int	Ja	WooCommerce-Bestell-ID
type	string	Nein	Typ: faktura_vat (Standard), proforma, korygujaca, paragon, packing_slip

Anfrage:

{
    "order_id": 567,
    "type": "faktura_vat"
}

Antwort (201 Created):

Die erstellte Rechnung, in derselben Form wie die Listeneinträge oben. Ein unbekannter type, eine fehlende Bestellung oder eine fehlgeschlagene Erstellung liefern 400 mit einem message-Feld.

{
    "id": 43,
    "order_id": 567,
    "original_invoice_id": null,
    "source_refund_id": null,
    "type": "faktura_vat",
    "type_label": "Faktura VAT",
    "number": "FV/2026/04/002",
    "status": "issued",
    "status_label": "Issued",
    "nip_seller": "9876543210",
    "nip_buyer": "1234567890",
    "buyer_name": "Firma Testowa Sp. z o.o.",
    "buyer_address": "ul. Testowa 1",
    "buyer_city": "Warszawa",
    "buyer_postcode": "00-001",
    "correction_reason": null,
    "net_total": 500.00,
    "vat_total": 115.00,
    "gross_total": 615.00,
    "currency": "PLN",
    "pdf_path": null,
    "ksef_reference": null,
    "ksef_status": null,
    "issued_at": "2026-04-05T14:00:00+02:00",
    "created_at": "2026-04-05T14:00:00+02:00",
    "items": []
}

Rechnungsdetails abrufen

GET /wp-json/polski-pro/v1/invoices/{id}

Gibt die vollständigen Rechnungsdaten einschließlich der Positionen zurück.

Antwort (200 OK):

{
    "id": 43,
    "order_id": 567,
    "original_invoice_id": null,
    "source_refund_id": null,
    "type": "faktura_vat",
    "type_label": "Faktura VAT",
    "number": "FV/2026/04/002",
    "status": "issued",
    "status_label": "Issued",
    "nip_seller": "9876543210",
    "nip_buyer": "1234567890",
    "buyer_name": "Firma Testowa Sp. z o.o.",
    "buyer_address": "ul. Testowa 1",
    "buyer_city": "Warszawa",
    "buyer_postcode": "00-001",
    "correction_reason": null,
    "net_total": 212.20,
    "vat_total": 48.80,
    "gross_total": 261.00,
    "currency": "PLN",
    "pdf_path": "/wp-content/uploads/polski-pro/invoices/FV-2026-04-002.pdf",
    "ksef_reference": null,
    "ksef_status": null,
    "issued_at": "2026-04-05T14:00:00+02:00",
    "created_at": "2026-04-05T14:00:00+02:00",
    "items": [
        {
            "id": 91,
            "product_id": 120,
            "name": "Produkt testowy",
            "quantity": 2,
            "unit": "szt.",
            "net_price": 100.00,
            "vat_rate": 23,
            "vat_amount": 46.00,
            "gross_price": 246.00
        },
        {
            "id": 92,
            "product_id": null,
            "name": "Dostawa - InPost Paczkomat",
            "quantity": 1,
            "unit": "szt.",
            "net_price": 12.20,
            "vat_rate": 23,
            "vat_amount": 2.80,
            "gross_price": 15.00
        }
    ]
}

Name und Anschrift des Verkäufers gehören nicht zu diesem Payload. Sie stammen aus den Verkäuferdaten in den Rechnungseinstellungen, auf der Rechnung selbst wird nur nip_seller gespeichert.

Antwort (404 Not Found):

{
    "message": "Invoice not found."
}

Rechnungs-PDF neu erzeugen

POST /wp-json/polski-pro/v1/invoices/{id}/pdf

Erzeugt die PDF-Datei der Rechnung neu. Der Endpunkt nimmt keine Body-Parameter entgegen: Vorlage und Sprache stammen aus den Rechnungseinstellungen.

Antwort (200 OK):

Das aktualisierte Rechnungsobjekt, dessen pdf_path auf die neue Datei zeigt. Eine fehlende Rechnung liefert 404, eine fehlende Bestellung 400 und ein fehlgeschlagener Druck 500, jeweils mit einem message-Feld.

Rechnung an KSeF übermitteln

POST /wp-json/polski-pro/v1/invoices/{id}/ksef

Reiht die Rechnung über den Action Scheduler zur Übermittlung an das Nationale System der elektronischen Rechnungen (KSeF) ein. Der Endpunkt nimmt keine Body-Parameter entgegen, und nichts im WordPress-Adminbereich ruft ihn auf: nur ein REST-Client erreicht ihn.

Der Aufruf kehrt zurück, sobald der Job eingereiht ist. Er liefert niemals eine KSeF-Referenznummer, einen KSeF-Status oder einen UPO-Link direkt mit, denn zu diesem Zeitpunkt existiert nichts davon. Lesen Sie diese Werte später aus ksef_reference und ksef_status der Rechnung.

Bevor Sie darauf aufbauen, lesen Sie KSeF-Integration: der API-Client ist fest auf die KSeF-Testumgebung eingestellt, und sein Authentifizierungsablauf ist nicht durchgängig nachgewiesen.

Antwort (202 Accepted):

{
    "invoice": {
        "id": 43,
        "number": "FV/2026/04/002",
        "status": "issued",
        "ksef_reference": null,
        "ksef_status": null
    },
    "message": "Invoice queued for KSeF submission."
}

Der Wert invoice ist das vollständige Rechnungsobjekt von oben, hier auf die für diesen Aufruf wichtigen Felder gekürzt.

Weitere Antworten:

Code	Wann
404	Keine Rechnung mit dieser ID
422	Das Dokument ist kein Buchhaltungsbeleg. Zulässig sind nur faktura_vat und korygujaca, Paragon, Proforma und Packing Slip werden hier abgelehnt
409	Die Rechnung trägt bereits eine KSeF-Referenz, und eine übermittelte Rechnung lässt sich nur korrigieren, nie erneut einreichen
503	Der Action Scheduler ist nicht verfügbar, es lässt sich also nichts einreihen

{
    "message": "Paragon documents are not eligible for KSeF submission."
}

Korrekturrechnung erstellen

POST /wp-json/polski-pro/v1/invoices/{id}/correction

Erstellt eine mit der Ursprungsrechnung verknüpfte Korrekturrechnung. Die korrigierten Beträge leitet das Plugin aus der Bestellung und, sofern angegeben, aus der WooCommerce-Rückerstattung ab. Über diesen Endpunkt lassen sich korrigierte Positionen nicht von Hand schreiben.

Body-Parameter (JSON):

Parameter	Typ	Erforderlich	Beschreibung
refund_id	int	Nein	WooCommerce-Rückerstattung, auf der die Korrektur beruht

Anfrage:

{
    "refund_id": 981
}

Antwort (201 Created):

Die Korrekturrechnung, in derselben Form wie jedes andere Rechnungsobjekt. type ist korygujaca, original_invoice_id verweist auf die Ursprungsrechnung, und die Summen sind negativ.

{
    "id": 44,
    "order_id": 567,
    "original_invoice_id": 43,
    "source_refund_id": 981,
    "type": "korygujaca",
    "type_label": "Faktura korygujaca",
    "number": "FK/2026/04/001",
    "status": "issued",
    "status_label": "Issued",
    "correction_reason": "Zwrot 1 sztuki produktu",
    "net_total": -100.00,
    "vat_total": -23.00,
    "gross_total": -123.00,
    "currency": "PLN",
    "ksef_reference": null,
    "ksef_status": null,
    "issued_at": "2026-04-05T15:00:00+02:00",
    "created_at": "2026-04-05T15:00:00+02:00",
    "items": []
}

Eine fehlende Ursprungsrechnung liefert 404, eine Korrektur, die der Dienst nicht bilden kann, 400.

Statistik-Endpunkt

Rechnungsstatistiken abrufen

GET /wp-json/polski-pro/v1/invoices/stats

Query-Parameter:

Parameter	Typ	Standard	Beschreibung
days	int	30	Anzahl der Tage rückwirkend, begrenzt auf 1 bis 365

days ist der einzige Parameter. Eine Gruppierung nach Tag, Woche oder Monat gibt es nicht.

Antwort (200 OK):

Sechs Felder, mehr nicht. total_revenue ist die Summe von gross_total über alle Rechnungen des Zeitraums außer den stornierten, by_type zählt dagegen auch die stornierten mit. ksef_sent zählt die Rechnungen mit einer KSeF-Referenz. by_type und by_status sind Listen, keine Objekte mit Schlüsseln. Eine Zeitreihe, eine Aufschlüsselung nach Steuersatz oder einen zusätzlichen zusammenfassenden Block liefert der Endpunkt nicht.

{
    "period_days": 30,
    "total": 156,
    "total_revenue": 150432.6,
    "ksef_sent": 12,
    "by_type": [
        { "type": "faktura_vat", "count": 150, "revenue": 156757.8 },
        { "type": "korygujaca", "count": 6, "revenue": -2478.9 }
    ],
    "by_status": [
        { "status": "issued", "count": 120 },
        { "status": "sent", "count": 25 },
        { "status": "paid", "count": 8 },
        { "status": "cancelled", "count": 3 }
    ]
}

Einstellungs-Endpunkt

PRO-Einstellungen lesen und aktualisieren

GET   /wp-json/polski-pro/v1/settings
PUT   /wp-json/polski-pro/v1/settings
PATCH /wp-json/polski-pro/v1/settings
POST  /wp-json/polski-pro/v1/settings

Lesen und Schreiben liegen auf derselben Route. GET gibt die vollständigen PRO-Einstellungen zurück, und die schreibende Seite ist als EDITABLE registriert, nimmt also PUT, PATCH und POST gleichermaßen an. Beide Seiten erfordern manage_woocommerce.

Body (JSON):

Der Body besteht aus Gruppen auf oberster Ebene. Es gibt weder einen Parameter section noch eine Hülle settings.

Gruppe	Gespeicherte Option
invoices	polski_pro_invoices
ksef	polski_pro_ksef
nip	polski_pro_nip
shipping	polski_pro_shipping
delivery_date	polski_delivery_date
checkout	polski_pro_checkout
abandoned_carts	polski_abandoned_carts
conditional_payments	polski_pro_conditional_payments
product_feed	polski_pro_product_feed
loyalty	polski_pro_loyalty
sms	polski_pro_sms
accounting	polski_pro_accounting

Jede gesendete Gruppe ersetzt die gespeicherte Option vollständig. Schlüssel, die Sie weglassen, gehen verloren, Schlüssel außerhalb der bekannten Liste einer Gruppe werden verworfen. Lesen Sie also erst mit GET, ändern Sie das gelesene Objekt und senden Sie die Gruppe wieder als Ganzes. Gruppen, die im Body fehlen, bleiben unangetastet.

Anfrage:

{
    "invoices": {
        "auto_generate": true,
        "numbering_format": "FV/{YYYY}/{MM}/{NR}",
        "number_reset": "year",
        "number_padding": 3,
        "payment_deadline_days": 14,
        "auto_generate_statuses": "completed"
    },
    "ksef": {
        "enabled": false,
        "environment": "test",
        "auto_send": false
    }
}

Antwort (200 OK):

Zurück kommen die vollständigen PRO-Einstellungen, also alle Gruppen, nicht nur die gesendeten. Ein Feld section oder updated_at gibt es in der Antwort nicht.

{
    "invoices": {
        "auto_generate": true,
        "numbering_format": "FV/{YYYY}/{MM}/{NR}",
        "number_reset": "year",
        "number_padding": 3,
        "payment_deadline_days": 14,
        "auto_generate_statuses": "completed"
    },
    "ksef": {
        "enabled": false,
        "environment": "test",
        "auto_send": false
    },
    "nip": {
        "checkout_field": true,
        "required": false,
        "validate_gus": true
    }
}

Endpunkte zur Erstellung von Rechtsdokumenten

Drei Routen: Variablen lesen, Text erzeugen, Text als WordPress-Seite anlegen. Alle drei erfordern manage_woocommerce.

Die Dokumente sind polnische Vorlagen. type nimmt genau drei Werte an: regulamin (Shop-AGB), polityka-prywatnosci (Datenschutzerklärung) und polityka-zwrotow (Widerrufsrecht und Rückgabebedingungen). Andere Werte liefern 400.

Verfügbare Variablen abrufen

GET /wp-json/polski-pro/v1/legal/variables

Nimmt keine Parameter entgegen. Gibt die Liste der Vorlagenvariablen, die aus WooCommerce vorbelegten Standardwerte und die Bezeichnungen der drei Dokumenttypen zurück.

Antwort (200 OK):

{
    "required": {
        "company_name": "Full company name",
        "company_address": "Company address",
        "company_nip": "NIP (tax ID)",
        "company_regon": "REGON number",
        "company_email": "Contact email",
        "company_phone": "Contact phone",
        "shop_url": "Shop URL",
        "shop_name": "Shop name",
        "bank_name": "Bank name",
        "bank_account": "Bank account number"
    },
    "defaults": {
        "company_name": "Mój Sklep",
        "company_address": "ul. Sklepowa 5, 02-222 Warszawa",
        "company_nip": "9876543210",
        "company_regon": "",
        "company_email": "[email protected]",
        "company_phone": "",
        "shop_url": "https://mojsklep.pl",
        "shop_name": "Mój Sklep",
        "bank_name": "",
        "bank_account": ""
    },
    "types": {
        "regulamin": "Regulamin sklepu",
        "polityka-prywatnosci": "Polityka prywatnosci",
        "polityka-zwrotow": "Prawo odstapienia / Polityka zwrotow"
    }
}

Rechtsdokument erstellen

POST /wp-json/polski-pro/v1/legal/generate

Erzeugt eine Vorschau des Textes aus der Shop-Vorlage. Es wird nichts gespeichert.

Body-Parameter (JSON):

Parameter	Typ	Erforderlich	Beschreibung
type	string	Ja	Dokumenttyp: regulamin, polityka-prywatnosci, polityka-zwrotow
variables	object	Nein	Vorlagenvariablen, standardmäßig leer. Fehlende Schlüssel füllen die Standardwerte aus /legal/variables

Ein Parameter company_data, ein Parameter format und ein Parameter language existieren nicht. Die Firmendaten gehören als flache Schlüssel in variables, die Ausgabe ist immer der Inhalt der Vorlage.

Anfrage:

{
    "type": "regulamin",
    "variables": {
        "company_name": "Mój Sklep Sp. z o.o.",
        "company_nip": "9876543210",
        "company_address": "ul. Sklepowa 5, 02-222 Warszawa",
        "company_email": "[email protected]",
        "company_phone": "+48 123 456 789"
    }
}

Antwort (200 OK):

{
    "type": "regulamin",
    "content": "<h1>Regulamin sklepu internetowego</h1>...",
    "variables_used": {
        "company_name": "Mój Sklep Sp. z o.o.",
        "company_nip": "9876543210",
        "company_address": "ul. Sklepowa 5, 02-222 Warszawa",
        "company_email": "[email protected]",
        "company_phone": "+48 123 456 789"
    }
}

Ein unbekannter type liefert 400, eine fehlende oder leere Vorlage 500, jeweils mit einem message-Feld.

Rechtsdokument als Seite anlegen

POST /wp-json/polski-pro/v1/legal/publish

Erzeugt denselben Text und legt ihn als WordPress-Seite ab. Die Seite entsteht immer im Status draft, also nie sofort öffentlich, und wird in den Polski-Einstellungen als AGB-, Datenschutz- oder Rückgabeseite hinterlegt.

Body-Parameter (JSON):

Parameter	Typ	Erforderlich	Beschreibung
type	string	Ja	Dokumenttyp: regulamin, polityka-prywatnosci, polityka-zwrotow
variables	object	Nein	Vorlagenvariablen wie bei /legal/generate
page_id	int	Nein	Bestehende Seite aktualisieren statt eine neue anzulegen. Standard 0

Antwort (201 Created):

{
    "page_id": 312,
    "edit_url": "https://mojsklep.pl/wp-admin/post.php?post=312&action=edit",
    "view_url": "https://mojsklep.pl/?page_id=312",
    "status": "draft",
    "message": "Page created as draft. Review and publish when ready."
}

Fehlercodes

Die Rechnungs- und Rechtsdokument-Endpunkte geben im Fehlerfall keinen maschinenlesbaren Fehlercode zurück. Der Body enthält nur ein Feld message, die Einordnung liefert der HTTP-Status:

{
    "message": "Invoice not found."
}

Werten Sie also den Status aus, nicht einen Code im Body. Diese Status kommen aus dem Rechnungs-Controller:

HTTP-Code	Wann
400	Unbekannter type, fehlende Bestellung, Korrektur nicht bildbar
404	Keine Rechnung mit dieser ID
409	Die Rechnung trägt bereits eine KSeF-Referenz
422	Der Dokumenttyp ist für KSeF nicht zulässig
500	PDF-Erzeugung fehlgeschlagen, Vorlage leer oder nicht gefunden
503	Action Scheduler nicht verfügbar

Benannte Fehlercodes gibt es nur an diesen Stellen:

Fehlercode	HTTP-Code	Herkunft
polski_pro_forbidden	403	Alle Rechnungs-Endpunkte, wenn dem Benutzer manage_woocommerce fehlt
polski_pro_invalid_nip	400	GUS-Abfrage mit ungültiger NIP
polski_pro_rate_limited	429	GUS-Abfrage über dem Limit, siehe unten
polski_pro_gus_unavailable	502	GUS antwortet nicht

Ein ungültiger Nonce wird von WordPress selbst beantwortet, nicht vom Plugin. Eine fehlende Anmeldung erreicht dagegen die Rechnungs-Endpunkte und wird dort vom Plugin mit polski_pro_forbidden und 403 abgewiesen, nicht von WordPress mit 401. Weitere benannte Fehlercodes als die vier in der Tabelle gibt es nicht.

Limits und Throttling

Es gibt kein allgemeines Anfragelimit. Die Rechnungs-, Einstellungs- und Rechtsdokument-Endpunkte drosseln nichts, senden keinen Retry-After-Header und antworten nie mit 429.

Der einzige Begrenzer in der PRO-REST-Schicht sitzt auf der GUS-Abfrage:

POST /wp-json/polski-pro/v1/gus/lookup

Angemeldete Benutzer mit manage_woocommerce sind ausgenommen. Für alle anderen gilt eine Begrenzung pro Client-IP, standardmäßig 10 Abfragen pro Stunde. Wird sie überschritten, kommt 429 mit dem Fehlercode polski_pro_rate_limited zurück.

Zwei Filter stellen das ein:

Filter	Standard	Bedeutung
polski-pro/gus/rate_limit_window_seconds	HOUR_IN_SECONDS	Länge des Zeitfensters
polski-pro/gus/rate_limit_max_attempts	10	Abfragen pro Fenster und IP

Ein Wert von 0 oder darunter bei einem der beiden schaltet die Begrenzung ab.

Nächste Schritte

• Probleme melden: GitHub Issues
• Verwandt: Buchhaltungsintegrationen

Diese Seite dient ausschließlich zu 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.