KSeF

Das KSeF (Krajowy System e-Faktur – Nationales E-Rechnungssystem) ist Polens obligatorisches elektronisches Rechnungsstellungssystem, das vom polnischen Finanzministerium betrieben wird. KSeF gewährleistet die Integrität und Authentizität von Rechnungen durch die Einreichung im strukturierten XML-Format und digitale Zertifizierung.

Diese Vorschriften verpflichten in Polen tätige Unternehmen, Systeme einzusetzen, die Rechnungen sicher generieren, validieren und an die KSeF-Plattform übermitteln können. Die REST-API von B2Brouter bietet eine technische Lösung, die Ihrem Unternehmen ermöglicht, KSeF-konform zu sein, indem die Komplexität an B2Brouter ausgelagert wird und Sie sich auf Ihre Geschäftslogik konzentrieren können.

Was ist KSeF?

KSeF ist Polens zentralisierte E-Rechnungsplattform, die für MwSt.-Steuerpflichtige obligatorisch wurde. Sie stellt sicher, dass alle Rechnungen:

Gegen offizielle XML-Schemata (FA-Struktur) validiert werden
Mit qualifizierten Zertifikaten digital zertifiziert werden
Von der polnischen Steuerbehörde sicher gespeichert werden
Durch eine offizielle Empfangsbestätigung (UPO – Urzędowe Poświadczenie Odbioru) verifizierbar sind

In der Praxis erfordert KSeF:

Erstellung einer strukturierten Rechnungs-XML-Datei gemäß FA-Schema-Variante 3 – FA(3)
Authentifizierung bei der KSeF-Plattform mit einem qualifizierten elektronischen Zertifikat, das mit Ihrer polnischen NIP verknüpft ist
Einreichung der Rechnung bei KSeF zur Validierung und Registrierung
Empfang und Speicherung der UPO (amtliche Empfangsbestätigung) als Registrierungsnachweis
Aufnahme des QR-Codes mit der KSeF-Referenznummer auf ausgestellten Rechnungen

Mit B2Brouter können Sie einen Großteil der Komplexität dieses Prozesses abstrahieren und KSeF-konform werden. Sie müssen Ihr qualifiziertes elektronisches Zertifikat (PKCS#12-Format) bereitstellen, und B2Brouter übernimmt Authentifizierung, Einreichung und UPO-Abruf.

B2Brouter generiert Steuerberichte im FA(3)-Format (Formular-Variante 3, Schema-Version 1-0E), dem aktuellen Standard für KSeF-Einreichungen.

KSeF mit der B2Brouter API einrichten

Der erste Schritt besteht darin, KSeF für jedes Konto (identifiziert durch die polnische NIP) zu konfigurieren, für das Sie Steuerberichte einreichen möchten. Einen vollständigen Beschreibung des Prozesses finden Sie im Leitfaden für Steuerberichtseinstellungen.

B2Brouter-Umgebungen und KSeF-Integration

Beginnen Sie mit der Sandbox für erste API-Tests und Payload-Validierung – KSeF-Einreichungen werden in der Sandbox simuliert, sodass kein KSeF-Zertifikat erforderlich ist. Wechseln Sie zur Staging-Umgebung, wenn Sie mit einem echten KSeF-Zertifikat gegen die KSeF-Test- oder Demo-Umgebung testen möchten.

B2Brouter stellt je nach Ihrer Konfiguration eine Verbindung zu verschiedenen KSeF-Umgebungen her:

B2Brouter-Umgebung	Verfügbare KSeF-Umgebungen	Zertifikatsanforderungen
Produktions-API `api.b2brouter.net`	KSeF Produktion nur	Produktions-KSeF-Zertifikat
Staging-API `api-staging.b2brouter.net`	KSeF Test (Standard) KSeF Demo (konfigurierbar)	Test: Test-KSeF-Zertifikat oder selbstsigniert Demo: Vorproduktions-KSeF-Zertifikat

Für Entwicklung und Tests:

Verwenden Sie die Staging-API (api-staging.b2brouter.net)
Standardmäßig verbindet sie sich mit KSeFs Testumgebung
- Akzeptiert Test-KSeF-Zertifikate (empfohlen)
- Akzeptiert auch selbstsignierte Zertifikate für schnelle Entwicklung und Integrationstests
Sie können optional die Demo-Umgebung konfigurieren, indem Sie beim Erstellen der Steuerberichtseinstellung environment: "demo" setzen
- Erfordert ein Vorproduktions-KSeF-Zertifikat
Für die Produktion funktionieren nur Produktions-KSeF-Zertifikate

Zertifikatsanforderungen

Die Authentifizierung gegenüber KSeF verwendet digitale Zertifikate im PKCS#12-Format (.p12 oder .pfx). Die Art des erforderlichen Zertifikats hängt von der KSeF-Umgebung ab:

Für die Produktionsumgebung:

Produktions-KSeF-Zertifikat
Der Kunde muss sich mit seiner qualifizierten Signatur oder seinem vertrauenswürdigen Profil (Profil Zaufany) anmelden
Zugriff auf den KSeF-Bereich und Generierung eines dedizierten KSeF-Zertifikats, das mit der NIP verknüpft ist
Zertifikatssubjekt muss Ihrer polnischen NIP entsprechen oder über ZAW-FA autorisiert sein
Passwort/PIN für das Zertifikat

Für die Demo-Umgebung (Vorproduktion):

Vorproduktions-KSeF-Zertifikat
Zertifikat muss im PKCS#12-Format (.p12 oder .pfx) vorliegen
Zertifikatssubjekt muss Ihrer polnischen NIP entsprechen oder über ZAW-FA autorisiert sein
Passwort/PIN für das Zertifikat

Für die Testumgebung (Entwicklung):

Test-KSeF-Zertifikat (empfohlen) oder selbstsigniertes Zertifikat (nur für Entwicklung)
Zertifikat muss im PKCS#12-Format (.p12 oder .pfx) vorliegen
Für selbstsignierte Zertifikate: die Seriennummer des Zertifikats sollte der MwSt.-Nummer (NIP) entsprechen
Passwort/PIN für das Zertifikat

Beispiel: Ihr Zertifikat kodieren

# Zertifikat ohne Zeilenumbrüche in Base64 kodieren
base64 -w 0 your-certificate.p12 > certificate-base64.txt

KSeF-Steuerberichtseinstellung erstellen

Sie müssen die KSeF-Integration für jedes Unternehmen konfigurieren, für das Sie strukturierte Rechnungen einreichen möchten. Diese Konfiguration legt fest, wie B2Brouter die Rechnungserstellung und -einreichung bei KSeF in Ihrem Namen verwaltet. Sie müssen diese Einstellungen pro Unternehmen konfigurieren, bevor Sie eine Rechnung einreichen.

Dieser Konfigurationsschritt onboardet den Kunden bei KSeF und führt einen Verbindungstest durch.
Wenn das Zertifikat oder die Konfiguration ungültig ist, gibt der Endpunkt einen Fehler zurück.

Beispielanfrage:

curl --request GET \
  --url https://api-staging.b2brouter.net/accounts/{ACCOUNT_ID}/tax_report_settings \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'Content-Type: application/json' \
  --data '{
    "tax_report_setting": {
      "code": "ksef",
      "type_operation": "services",
      "credit_note_code": "1",
      "certificate": "MIIKZAIBAzCCCh4GCSqGSIb3DQEHAaCCCg8Egg...",
      "certificate_pin": "YourCertificatePassword",
      "auto_generate": true,
      "auto_send": true,
      "enabled": true
    }
  }'

Parameter:

code: Muss “ksef” sein
type_operation: Standard-Operationstyp (“services” oder “goods”)
credit_note_code: Standard-Korrekturwirkungscode (“1”, “2” oder “3”)
certificate: Ihr PKCS#12-Zertifikat in Base64 kodiert
certificate_pin: Passwort für das Zertifikat
auto_generate: Steuerberichte für Rechnungen automatisch generieren
auto_send: Steuerberichte automatisch an KSeF senden

Mit KSeF-Steuerberichten arbeiten

B2Brouter bietet zwei Möglichkeiten zur Arbeit mit KSeF:

Tax Report API: Für direkte Kontrolle über die Erstellung und Einreichung von Steuerberichten (EMPFOHLEN).
Invoice API: Wenn Sie B2Brouter für die Rechnungsausstellung verwenden, werden Steuerberichte automatisch generiert.

Tax Report API

Die Tax Report API gibt Ihnen maximale Kontrolle über den KSeF-Einreichungsprozess. Sie können Steuerberichte erstellen, indem Sie strukturierte JSON-Daten bereitstellen, die B2Brouter in das FA(3)-XML-Format konvertiert.

Die Struktur des JSON-Formats für B2Brouter-Steuerberichte basiert auf PEPPOL Continuous Transaction Control (CTC). Das bedeutet, dass die B2Brouter Tax Report API eine universelle API ist, die nicht nur auf KSeF ausgerichtet ist, sondern für die weltweite Steuerberichterstattung konzipiert wurde.

Wichtig: Steuerberichte für KSeF verwenden tax_report_lines und tax_breakdowns. Jede tax_report_line stellt eine Rechnungsposition mit eigener Menge, Position, Einheitencode, Preis und Steuerinformationen dar.

Einen Steuerbericht erstellen

Um einen KSeF-Steuerbericht zu erstellen, rufen Sie den Endpunkt zum Erstellen eines Steuerberichts auf.

Beispiel: Einfache MwSt.-Rechnung

curl --request POST \
  --url https://api-staging.b2brouter.net/accounts/{ACCOUNT_ID}/tax_reports \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'Content-Type: application/json' \
  --data '{
    "tax_report": {
      "type": "KSeF",
      "invoice_type_code": "VAT",
      "invoice_date": "2025-11-07",
      "tax_point_date": "2025-11-07",
      "invoice_number": "F/2025/11/001",
      "description": "Consulting services",
      "customer_party_name": "Example Company Sp. z o.o.",
      "customer_party_tax_id": "1234567890",
      "customer_party_address": "Address 1",
      "customer_party_country": "pl",
      "currency": "PLN",
      "tax_inclusive_amount": 1230.00,
      "tax_amount": 230.00,
      "type_operation": "services",
      "tax_report_lines": [
        {
          "position": 1,
          "quantity": 10,
          "unit_code": "EA",
          "description": "Consulting hours",
          "price": 100.00,
          "tax_code": "23",
          "tax_exclusive_amount": 1000.00,
          "tax_amount": 230.00,
          "tax_inclusive_amount": 1230.00
        }
      ],
      "tax_breakdowns": [
        {
          "name": "PTU",
          "category": "S",
          "percent": 23.0,
          "taxable_base": 1000.0,
          "tax_amount": 230.00
        }
      ]
    }
  }'

Beispiel: Korrekturrechnung (KOR)

curl --request POST \
  --url https://api-staging.b2brouter.net/accounts/{ACCOUNT_ID}/tax_reports \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'Content-Type: application/json' \
  --data '{
    "tax_report": {
      "type": "KSeF",
      "invoice_type_code": "KOR",
      "amend_type": "2",
      "invoice_date": "2025-11-08",
      "tax_point_date": "2025-11-07",
      "invoice_number": "FK/2025/11/001",
      "description": "Correction of invoice F/2025/11/001",
      "amended_ksef_number": "1234567890-20251107-ABCD1234-EF",
      "amended_date": "2025-11-07",
      "amended_number":  "F/2025/11/001",
      "customer_party_name": "Example Company Sp. z o.o.",
      "customer_party_tax_scheme": "9945",
      "customer_party_tax_id": "1234567890",
      "customer_party_address": "Address 1",
      "customer_party_country": "pl",
      "currency": "PLN",
      "tax_inclusive_amount": 1230.00,
      "tax_amount": 230.00,
      "type_operation": "services",
      "tax_report_lines": [
        {
          "position": 1,
          "quantity": 10,
          "unit_code": "EA",
          "description": "Consulting hours",
          "price": 100.00,
          "tax_code": "23",
          "tax_exclusive_amount": 1000.00,
          "tax_amount": 230.00,
          "tax_inclusive_amount": 1230.00,
          "ksef_amended": true
        },
        {
          "position": 1,
          "quantity": 10,
          "unit_code": "PCE",
          "description": "Consulting hours - new line",
          "price": 100.00,
          "tax_code": "23",
          "tax_exclusive_amount": 1000.00,
          "tax_amount": 230.00,
          "tax_inclusive_amount": 1230.00
        }
      ],
      "tax_breakdowns": [
        {
          "name": "PTU",
          "category": "S",
          "percent": 23.0,
          "taxable_base": 1000.0,
          "tax_amount": 230.00
        }
      ]
    }
  }'

Beispiel: Steuerbefreiter Warenexport – MwSt.-Rechnung (Fremdwährung)

curl --request POST \
  --url https://api-staging.b2brouter.net/accounts/{ACCOUNT_ID}/tax_reports \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'Content-Type: application/json' \
  --data '{
    "tax_report": {
      "type": "KSeF",
      "invoice_type_code": "VAT",
      "invoice_date": "2025-11-07",
      "tax_point_date": "2025-11-07",
      "invoice_number": "F/2025/11/003",
      "description": "Sample Exempt VAT Invoice -  Export of Goods",
      "customer_party_name": "EFG Ltd.",
      "customer_party_tax_id": "1234567890",
      "customer_party_address": "Flower (St) 1, Seattle, WA 99999",
      "customer_party_country": "us",
      "currency": "USD",
      "exchange_rate": 3.65,
      "tax_inclusive_amount": 8000,
      "tax_amount": 0,
      "type_operation": "goods",
      "tax_report_lines": [
        {
          "position": 1,
          "quantity": 20,
          "unit_code": "szt.",
          "description": "lodówka Zimnotech mk1",
          "price": 400,
          "tax_code": "0 EX",
          "tax_exclusive_amount": 8000,
          "tax_amount": 0,
          "tax_inclusive_amount": 8000
        }
      ],
      "tax_breakdowns": [
        {
          "name": "PTU",
          "category": "E",
          "percent": 0.0,
          "taxable_base": 8000,
          "tax_amount": 0,
          "comment": "reason why exempt"
        }
      ]
    }
  }'

Beispiel: MwSt.-Rechnung (vollständige Zahlung bei Ausstellung erhalten) – Zaplacono

curl --request POST \
  --url https://api-staging.b2brouter.net/accounts/{ACCOUNT_ID}/tax_reports \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'Content-Type: application/json' \
  --data '{
    "tax_report": {
      "type": "KSeF",
      "invoice_type_code": "VAT",
      "invoice_date": "2025-11-07",
      "tax_point_date": "2025-11-07",
      "payment_date": "2025-11-07",
      "payable_amount": 0,
      "invoice_number": "F/2025/11/004",
      "description": "Sample VAT Invoice (full payment has been received at the time of issue)",
      "customer_party_name": "Example Company Sp. z o.o.",
      "customer_party_tax_scheme": "9945",
      "customer_party_tax_id": "1234567890",
      "customer_party_address": "Address 1",
      "customer_party_country": "pl",
      "currency": "PLN",
      "tax_inclusive_amount": 1230.00,
      "tax_amount": 230.00,
      "type_operation": "goods",
      "tax_report_lines": [
        {
          "position": 1,
          "quantity": 10,
          "unit_code": "EA",
          "description": "product 1",
          "price": 100.00,
          "tax_code": "23",
          "tax_exclusive_amount": 1000.00,
          "tax_amount": 230.00,
          "tax_inclusive_amount": 1230.00
        }
      ],
      "tax_breakdowns": [
        {
          "name": "PTU",
          "category": "S",
          "percent": 23.0,
          "taxable_base": 1000.0,
          "tax_amount": 230.00
        }
      ]
    }
  }'

Beispiel: ZAL-Rechnung (Anzahlung)

curl --request POST \
  --url https://api-staging.b2brouter.net/accounts/{ACCOUNT_ID}/tax_reports \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'Content-Type: application/json' \
  --data '{
    "tax_report": {
      "type": "KSeF",
      "invoice_type_code": "ZAL",
      "invoice_date": "2025-11-07",
      "tax_point_date": "2025-11-07",
      "payment_date": "2025-11-07",
      "payable_amount": 0,
      "invoice_number": "F/2025/11/005",
      "description": "Sample ZAL Invoice (full payment has been received at the time of issue)",
      "customer_party_name": "Example Company Sp. z o.o.",
      "customer_party_tax_scheme": "9945",
      "customer_party_tax_id": "1234567890",
      "customer_party_address": "Address 1",
      "customer_party_country": "pl",
      "currency": "PLN",
      "tax_inclusive_amount": 1230.00,
      "tax_amount": 230.00,
      "type_operation": "goods",
      "tax_report_lines": [
        {
          "position": 1,
          "quantity": 10,
          "unit_code": "EA",
          "description": "product 1",
          "price": 100.00,
          "tax_code": "23",
          "tax_exclusive_amount": 1000.00,
          "tax_amount": 230.00,
          "tax_inclusive_amount": 1230.00
        }
      ],
      "tax_breakdowns": [
        {
          "name": "PTU",
          "category": "S",
          "percent": 23.0,
          "taxable_base": 1000.0,
          "tax_amount": 230.00
        }
      ]
    }
  }'

Beispiel: ROZ-Rechnung (Abrechnung von Anzahlungen)

Eine ROZ-Rechnung rechnet den Restbetrag nach allen Anzahlungen ab. Sie verweist über prepayment_references auf frühere ZAL-Rechnungen. Jede Referenz entspricht einem FakturaZaliczkowa-Element im FA(3)-XML.

curl --request POST \
  --url https://api-staging.b2brouter.net/accounts/{ACCOUNT_ID}/tax_reports \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'Content-Type: application/json' \
  --data '{
    "tax_report": {
      "type": "KSeF",
      "invoice_type_code": "ROZ",
      "invoice_date": "2026-08-17",
      "tax_point_date": "2026-09-17",
      "invoice_number": "FV2026/08/12",
      "description": "Settlement invoice",
      "customer_party_name": "Jan Kowalski",
      "customer_party_tax_id": "1234567890",
      "customer_party_address": "ul. Przykładowa 1",
      "customer_party_country": "pl",
      "currency": "PLN",
      "tax_inclusive_amount": 306899.80,
      "tax_amount": 22720.76,
      "type_operation": "goods",
      "prepayment_references": [
        { "registration_code": "9999999999-20260215-8BEF280C8D35-4D" },
        { "number": "FZ2026/03/200" }
      ],
      "tax_report_lines": [
        {
          "position": 1,
          "quantity": 1,
          "unit_code": "C62",
          "description": "mieszkanie 50m^2",
          "price": 280177.59,
          "tax_code": "8",
          "tax_exclusive_amount": 280177.59,
          "tax_amount": 22414.21,
          "tax_inclusive_amount": 302591.80
        },
        {
          "position": 2,
          "quantity": 1,
          "unit_code": "C62",
          "description": "usługi dodatkowe",
          "price": 4001.55,
          "tax_code": "23",
          "tax_exclusive_amount": 4001.55,
          "tax_amount": 306.55,
          "tax_inclusive_amount": 4308.00
        }
      ],
      "tax_breakdowns": [
        { "name": "PTU", "category": "S", "percent": 8.0, "taxable_base": 280177.59, "tax_amount": 22414.21 },
        { "name": "PTU", "category": "S", "percent": 23.0, "taxable_base": 4001.55, "tax_amount": 306.55 }
      ]
    }
  }'

prepayment_references — verwenden Sie registration_code für die KSeF-Nummer (NrKSeFFaZaliczkowej) oder number für die Rechnungsnummer (NrFaZaliczkowej), wenn die ZAL außerhalb von KSeF ausgestellt wurde.

Beispiel: KOR_ZAL-Rechnung (Korrektur einer Anzahlungsrechnung)

Eine KOR_ZAL korrigiert eine zuvor ausgestellte ZAL-Rechnung. Verwenden Sie previous_advance_total, um den ursprünglichen Anzahlungsbetrag anzugeben (P_15ZK im FA(3)-XML).

curl --request POST \
  --url https://api-staging.b2brouter.net/accounts/{ACCOUNT_ID}/tax_reports \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'Content-Type: application/json' \
  --data '{
    "tax_report": {
      "type": "KSeF",
      "invoice_type_code": "KOR_ZAL",
      "amend_type": "1",
      "invoice_date": "2026-03-17",
      "tax_point_date": "2026-02-15",
      "invoice_number": "FK2026/03/7",
      "description": "Correction of advance invoice FZ2026/02/150",
      "amended_ksef_number": "9999999999-20260215-8BEF280C8D35-4D",
      "amended_date": "2026-02-15",
      "amended_number": "FZ2026/02/150",
      "customer_party_name": "Jan Kowalski",
      "customer_party_tax_id": "1234567890",
      "customer_party_address": "ul. Przykładowa 1",
      "customer_party_country": "pl",
      "currency": "PLN",
      "tax_inclusive_amount": 25000.00,
      "tax_amount": 4674.80,
      "previous_advance_total": 20000.00,
      "type_operation": "goods",
      "tax_report_lines": [
        {
          "position": 1,
          "quantity": 1,
          "unit_code": "C62",
          "description": "mieszkanie 50m^2",
          "price": 300000,
          "tax_code": "23",
          "tax_exclusive_amount": 20325.20,
          "tax_amount": 4674.80,
          "tax_inclusive_amount": 25000.00
        }
      ],
      "tax_breakdowns": [
        { "name": "PTU", "category": "S", "percent": 23.0, "taxable_base": 20325.20, "tax_amount": 4674.80 }
      ]
    }
  }'

previous_advance_total: 20000.00 — der Bruttobetrag der zu korrigierenden Original-ZAL (entspricht P_15ZK).

Beispiel: JST-Rechnung (kommunale Körperschaft)

Eine Rechnung an eine untergeordnete kommunale Körperschaft (JST). Der Käufer (Podmiot2) ist die übergeordnete Einheit; der eigentliche Empfänger ist ein Podmiot3 mit Rolle 8.

curl --request POST \
  --url https://api-staging.b2brouter.net/accounts/{ACCOUNT_ID}/tax_reports \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'Content-Type: application/json' \
  --data '{
    "tax_report": {
      "type": "KSeF",
      "invoice_type_code": "VAT",
      "invoice_date": "2026-03-23",
      "tax_point_date": "2026-03-23",
      "invoice_number": "F/2026/JST/001",
      "description": "Services for local government unit",
      "customer_party_name": "Gmina Kraków",
      "customer_party_tax_id": "6762450871",
      "customer_party_address": "Plac Wszystkich Świętych 3-4",
      "customer_party_country": "pl",
      "customer_party_jst": true,
      "third_party_name": "Szkoła Podstawowa nr 7",
      "third_party_tax_id": "7654321098",
      "third_party_tax_scheme": "9945",
      "currency": "PLN",
      "tax_inclusive_amount": 1230.00,
      "tax_amount": 230.00,
      "type_operation": "services",
      "tax_report_lines": [
        {
          "position": 1,
          "quantity": 10,
          "unit_code": "EA",
          "description": "Consulting services",
          "price": 100.00,
          "tax_code": "23",
          "tax_exclusive_amount": 1000.00,
          "tax_amount": 230.00,
          "tax_inclusive_amount": 1230.00
        }
      ],
      "tax_breakdowns": [
        { "name": "PTU", "category": "S", "percent": 23.0, "taxable_base": 1000.0, "tax_amount": 230.00 }
      ]
    }
  }'

customer_party_jst: true — setzt Podmiot2/JST auf 1 im FA(3)-XML.
third_party_name / third_party_tax_id — der JST-Empfänger, als Podmiot3 mit Rolle 8 dargestellt.
Für MwSt.-Gruppenrechnungen verwenden Sie stattdessen customer_party_gv: true (Rolle 10).

Beispiel: UPR-Rechnung

Für UPR sind die Felder customer_party_tax_id und customer_party_country erforderlich.

curl --request POST \
  --url https://api-staging.b2brouter.net/accounts/{ACCOUNT_ID}/tax_reports \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'Content-Type: application/json' \
  --data '{
    "tax_report": {
      "type": "KSeF",
      "invoice_type_code": "UPR",
      "ticket": true,
      "invoice_date": "2025-11-07",
      "tax_point_date": "2025-11-07",
      "invoice_number": "F/2025/11/006",
      "description": "Sample UPR Invoice",
      "customer_party_tax_id": "1234567890",
      "customer_party_country": "pl",
      "currency": "PLN",
      "tax_inclusive_amount": 12.30,
      "tax_amount": 2.30,
      "type_operation": "goods",
      "tax_report_lines": [
        {
          "position": 1,
          "quantity": 1,
          "unit_code": "EA",
          "description": "product 1",
          "price": 10.00,
          "tax_code": "23",
          "tax_exclusive_amount": 10.00,
          "tax_amount": 2.30,
          "tax_inclusive_amount": 12.30
        }
      ],
      "tax_breakdowns": [
        {
          "name": "PTU",
          "category": "S",
          "percent": 23.0,
          "taxable_base": 10.0,
          "tax_amount": 2.30
        }
      ]
    }
  }'

Beispiel: Inländische Umkehrsteuerpflicht

curl --request POST \
  --url https://api-staging.b2brouter.net/accounts/{ACCOUNT_ID}/tax_reports \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'Content-Type: application/json' \
  --data '{
    "tax_report": {
      "type": "KSeF",
      "invoice_type_code": "VAT",
      "invoice_date": "2025-11-07",
      "tax_point_date": "2025-11-07",
      "invoice_number": "F/2025/11/007",
      "description": "Construction services - reverse charge",
      "customer_party_name": "Example Construction Sp. z o.o.",
      "customer_party_tax_id": "1234567890",
      "customer_party_address": "Address 1",
      "customer_party_country": "pl",
      "currency": "PLN",
      "tax_inclusive_amount": 5000.00,
      "tax_amount": 0.00,
      "type_operation": "services",
      "tax_report_lines": [
        {
          "position": 1,
          "quantity": 1,
          "unit_code": "EA",
          "description": "Construction services per contract X",
          "price": 5000.00,
          "tax_code": "oo",
          "tax_exclusive_amount": 5000.00,
          "tax_amount": 0.00,
          "tax_inclusive_amount": 5000.00
        }
      ],
      "tax_breakdowns": [
        {
          "name": "VAT",
          "category": "AE",
          "percent": 0.0,
          "taxable_base": 5000.0,
          "tax_amount": 0.0,
          "scope": "domestic"
        }
      ]
    }
  }'

Beispiel: Grenzüberschreitende Umkehrsteuerpflicht (Dienstleistungen)

curl --request POST \
  --url https://api-staging.b2brouter.net/accounts/{ACCOUNT_ID}/tax_reports \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'Content-Type: application/json' \
  --data '{
    "tax_report": {
      "type": "KSeF",
      "invoice_type_code": "VAT",
      "invoice_date": "2025-11-07",
      "tax_point_date": "2025-11-07",
      "invoice_number": "F/2025/11/008",
      "description": "Consulting services - cross-border",
      "customer_party_name": "Example Company GmbH",
      "customer_party_tax_id": "DE123456789",
      "customer_party_address": "Berlin Street 1, 10115 Berlin",
      "customer_party_country": "de",
      "currency": "EUR",
      "exchange_rate": 4.30,
      "tax_inclusive_amount": 3000.00,
      "tax_amount": 0.00,
      "type_operation": "services",
      "tax_report_lines": [
        {
          "position": 1,
          "quantity": 20,
          "unit_code": "HUR",
          "description": "IT consulting services",
          "price": 150.00,
          "tax_code": "np I",
          "tax_exclusive_amount": 3000.00,
          "tax_amount": 0.00,
          "tax_inclusive_amount": 3000.00
        }
      ],
      "tax_breakdowns": [
        {
          "name": "VAT",
          "category": "AE",
          "percent": 0.0,
          "taxable_base": 3000.0,
          "tax_amount": 0.0
        }
      ]
    }
  }'

Antwortstruktur

Die Antwort enthält den Steuerbericht mit dem Status “sending”:

{
  "tax_report": {
    "id": 12345,
    "type": "KSeF",
    "state": "sending",
    "fingerprint": "a3f2c1b9e8d7...",
    "identifier": "https://ksef-test.mf.gov.pl/client-app/invoice/5792000046/2025-11-07/a3f2c1b9e8d7...",
    "qr": "iVBORw0KGgoAAAANSUhEUgAA...",
    ...
  }
}

Wichtig: Im Gegensatz zu traditionellen Clearance-Modellen kann B2Brouter den fingerprint, identifier (QR-Code-URL) und qr (QR-Code-Bild) sofort beim Erstellen des Steuerberichts generieren, ohne auf die KSeF-Bestätigung zu warten. Diese Felder werden aus bereits vorhandenen Daten berechnet:

fingerprint: SHA-256-Hash des FA(3)-XML-Dokuments
identifier: URL aus: Lieferanten-NIP + Rechnungsdatum + Fingerabdruck (Base64URL-Format)
qr: QR-Code-Bild, das die identifier-URL kodiert

QR-Code-Bezeichnung:

Solange der Steuerbericht im Status sending ist (vor KSeF-Bestätigung), sollte die QR-Code-Bezeichnung “OFFLINE” anzeigen
Sobald der Steuerbericht den Status registered erreicht und Sie die to_net_id (KSeF-Referenznummer) erhalten, sollten Sie stattdessen die KSeF-Nummer unter dem QR-Code anzeigen

Best Practice: Obwohl die QR-Code-Daten sofort verfügbar sind, wird empfohlen zu warten, bis der Steuerbericht den Status registered erreicht, bevor Rechnungen gedruckt/an Kunden gesendet werden.

Status des Steuerberichts prüfen

Die Einreichung bei KSeF ist asynchron. Sie müssen den Status des Steuerberichts überwachen:

Option 1: Webhooks verwenden (empfohlen)

Konfigurieren Sie einen Steuerbericht-Webhook, um Benachrichtigungen zu erhalten, wenn der Status einen Endzustand erreicht: registered oder error.

Option 2: Polling

Rufen Sie den Endpunkt zum Abrufen des Steuerberichts auf, bis der Status final ist:

curl --request GET \
  --url https://api-staging.b2brouter.net/tax_reports/{TAX_REPORT_ID} \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}'

Den Status “Registriert” verstehen

Wenn der Steuerbericht den Status registered erreicht, enthält die Antwort die offizielle KSeF-Referenznummer:

{
  "tax_report": {
    "id": 12345,
    "type": "KSeF",
    "state": "registered",
    "to_net_id": "1234567890-20251107-ABCD1234-EF",
    "fingerprint": "a3f2c1b9e8d7...",
    "identifier": "https://ksef-test.mf.gov.pl/client-app/invoice/1234567890/2025-11-07/a3f2c1b9e8d7...",
    "qr": "iVBORw0KGgoAAAANSUhEUgAA...",
    ...
  }
}

Feld	Verfügbar	Beschreibung
`to_net_id`	Nach KSeF-Bestätigung	KSeF-Referenznummer – die von KSeF zugewiesene eindeutige Kennung. Diese Nummer unter dem QR-Code auf gedruckten/PDF-Rechnungen anzeigen.
`fingerprint`	Sofort bei Erstellung	SHA-256-Hash des eingereichten FA(3)-XML-Dokuments.
`identifier`	Sofort bei Erstellung	QR-Code-URL – die vollständige URL, auf die der QR-Code verweist.
`qr`	Sofort bei Erstellung	QR-Code-Bild – Base64-kodiertes PNG-Bild des QR-Codes.

UPO (amtliche Empfangsbestätigung) herunterladen

Sobald der Steuerbericht den Status registered erreicht, können Sie die UPO über den Endpunkt zum Herunterladen der Antwort herunterladen:

curl --request GET \
  --url https://api-staging.b2brouter.net/tax_reports/{TAX_REPORT_ID}/download_response \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'Accept: application/xml'

FA(3)-XML herunterladen

Sie können auch das vollständige FA(3)-XML, das an KSeF gesendet wurde, herunterladen:

curl --request GET \
  --url https://api-staging.b2brouter.net/tax_reports/{TAX_REPORT_ID}/download \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}' \
  --header 'Accept: application/xml'

Alternativ enthält das Feld xml_base64 in der Steuerbericht-Antwort das in Base64 kodierte XML.

Fehlerbehandlung

Wenn der Steuerbericht den Status error erreicht, prüfen Sie die Steuerberichtdetails auf Fehlerinformationen:

curl --request GET \
  --url https://api-staging.b2brouter.net/tax_reports/{TAX_REPORT_ID} \
  --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
  --header 'X-B2B-API-Version: {YOUR_API_VERSION}'

Äquivalenz zwischen B2Brouter-Steuerberichtsfeldern und KSeF FA(3)-XML-Knoten

Hauptrechnungsfelder

B2Brouter-Feld	KSeF FA(3) XML-Knoten
type	Muss “KSeF” sein
invoice_type_code	Fa > RodzajFaktury
invoice_date	Fa > P_1
invoice_number	Fa > P_2
tax_point_date	Fa > P_6
customer_party_name	Podmiot2 > DaneIdentyfikacyjne > Nazwa
customer_party_tax_id	Podmiot2 > DaneIdentyfikacyjne > NIP (PL) oder NrVatUE (EU) oder NrID (Nicht-EU)
customer_party_country	Podmiot2 > DaneIdentyfikacyjne > KodUE oder KodKraju
supplier_party_name	Podmiot1 > DaneIdentyfikacyjne > Nazwa
supplier_party_tax_id	Podmiot1 > DaneIdentyfikacyjne > NIP
supplier_party_country	Podmiot1 > PrefiksPodatnika
description	Stopka > Informacje > StopkaFaktury
currency	Fa > KodWaluty
exchange_rate	Fa > KursWalutyZ
payment_date	Fa > Platnosc > TerminPlatnosci > Termin (unbezahlt) oder Fa > Platnosc > DataZaplaty (bezahlt)
payable_amount	Wenn auf 0 mit payment_date gesetzt, markiert die Rechnung als bezahlt (Zaplacono=1)
payment_means_type_code	Fa > Platnosc > FormaPlatnosci
payment_account_identifier	Fa > Platnosc > RachunekBankowy > NrRB
payment_service_provider_identifier	Fa > Platnosc > RachunekBankowy > SWIFT
amended_ksef_number	Fa > DaneFaKorygowanej > NrKSeFFaKorygowanej
tax_inclusive_amount	Fa > P_15 (Gesamtbetrag)
customer_party_jst	Podmiot2 > JST (`1` wenn true, `2` wenn false)
customer_party_gv	Podmiot2 > GV (`1` wenn true, `2` wenn false)
third_party_name	Podmiot3 > DaneIdentyfikacyjne > Nazwa
third_party_tax_id	Podmiot3 > DaneIdentyfikacyjne > NIP (PL), NrVatUE (EU) oder NrID (Nicht-EU)
purchase_order_date	Fa > WarunkiTransakcji > Zamowienia > DataZamowienia
despatch_advice_reference	Fa > WZ
supplier_contact_email	Podmiot1 > DaneKontaktowe > Email
supplier_contact_phone	Podmiot1 > DaneKontaktowe > Telefon
supplier_party_regon	Stopka > Rejestry > REGON
supplier_party_krs	Stopka > Rejestry > KRS
supplier_party_bdo	Stopka > Rejestry > BDO
previous_advance_total	Fa > P_15ZK (nur KOR_ZAL)
prepayment_references	Fa > FakturaZaliczkowa (nur ROZ/KOR_ROZ)

Steuerberichtspositionen (FaWiersz)

B2Brouter-Feld	KSeF FA(3) XML-Knoten
position	FaWiersz > NrWierszaFa
description	FaWiersz > P_7
unit_code	FaWiersz > P_8A
quantity	FaWiersz > P_8B
price	FaWiersz > P_9A
discount_amount	FaWiersz > P_10
tax_code	FaWiersz > P_12
tax_exclusive_amount	FaWiersz > P_11
tax_amount	FaWiersz > P_11Vat
ksef_amended	FaWiersz > StanPrzed (markiert korrigierte Position)

Steueraufschlüsselungen

B2Brouter-Feld	KSeF FA(3) XML-Knoten
name	Steuerplan-Name (z. B. “PTU”, “VAT”)
category	Steuerkategorie: “S” (Standard), “E” (befreit), “AE” (Umkehrsteuer)
percent	Steuerprozentsatz
taxable_base	P_13_x (steuerpflichtige Basis pro Steuersatz-Bucket)
tax_amount	P_14_x (Steuerbetrag pro Steuersatz-Bucket)
comment	Adnotacje > Zwolnienie > P_19A (Befreiungsgrund, wenn Kategorie “E”)
exemption_code	P_12-Überschreibung — akzeptiert `zw`
no_subject_code	P_12-Überschreibung — akzeptiert `np I`, `np II`
non_exemption_code	P_12-Überschreibung — akzeptiert `0 KR`, `0 WDT`, `0 EX`, `oo`

FA(3)-Strukturübersicht

<tns:Faktura xmlns:tns="http://crd.gov.pl/wzor/2025/06/25/13775/">
  <tns:Naglowek>
    <tns:KodFormularza kodSystemowy="FA (3)" wersjaSchemy="1-0E">FA</tns:KodFormularza>
    <tns:WariantFormularza>3</tns:WariantFormularza>
    <tns:DataWytworzeniaFa><!-- Zeitstempel --></tns:DataWytworzeniaFa>
    <tns:SystemInfo>B2Brouter</tns:SystemInfo>
  </tns:Naglowek>

  <tns:Podmiot1><!-- Lieferant (Verkäufer) --></tns:Podmiot1>
  <tns:Podmiot2><!-- Kunde (Käufer) --></tns:Podmiot2>

  <tns:Fa>
    <!-- Rechnungsdetails: Währung, Daten, Steuerbeträge -->
    <!-- Steueraufschlüsselung: P_13_x, P_14_x, P_15 -->
    <!-- Adnotacje (Anmerkungen/Kennzeichen) -->
    <!-- RodzajFaktury (Rechnungstyp) -->

    <tns:FaWiersz><!-- Rechnungsposition 1 --></tns:FaWiersz>
    <tns:FaWiersz><!-- Rechnungsposition 2 --></tns:FaWiersz>

    <tns:Platnosc><!-- Zahlungsdetails (optional) --></tns:Platnosc>
    <tns:WarunkiTransakcji><!-- Transaktionsbedingungen (optional) --></tns:WarunkiTransakcji>
  </tns:Fa>

  <tns:Stopka><!-- Fußzeile/Hinweise (optional) --></tns:Stopka>
</tns:Faktura>

Codebeschreibungen für KSeF-spezifische Felder

Rechnungstyp-Codes

Parameter: invoice_type_code

Code	Beschreibung	Verwendet für
VAT	Standardrechnung	Reguläre Rechnungen
KOR	Korrekturrechnung	Korrekturen
ZAL	Anzahlungsrechnung (Art. 106f Abs. 4)	Anzahlungen
ROZ	Rechnung gemäß Art. 106f Abs. 3	Abrechnungen
UPR	Vereinfachte Rechnung (Art. 106e Abs. 5 Nr. 3)	Vereinfacht
KOR_ZAL	Korrekturrechnung für Anzahlung	Korrekturen
KOR_ROZ	Korrekturrechnung für ROZ	Korrekturen

Gutschrift-Wirkungscodes

Art der Wirkung der Korrektur in der MwSt.-Aufzeichnung. Verwendet für Korrekturrechnungen (KOR, KOR_ZAL, KOR_ROZ). Parameter: credit_note_code (in der Steuerberichtseinstellung)

Code	Beschreibung
1	Korrektur mit Wirkung zum Datum der Anerkennung der Originalrechnung
2	Korrektur mit Wirkung zum Ausstellungsdatum der Korrekturrechnung
3	Korrektur mit Wirkung zu einem anderen Datum (oder unterschiedlichen Daten für verschiedene Positionen)

Steuercodes

MwSt.-Sätze und -Kategorien in Polen. Auf Positionsebene verwendet. Parameter: tax_code (in tax_report_lines)

Code	Beschreibung
23	Standard-MwSt.-Satz 23%
22	Standard-MwSt.-Satz 22%
8	Ermäßigter MwSt.-Satz 8%
7	Ermäßigter MwSt.-Satz 7%
5	Ermäßigter MwSt.-Satz 5%
4	Ermäßigter MwSt.-Satz 4%
3	Ermäßigter MwSt.-Satz 3%
0 WDT	Innergemeinschaftliche Lieferung 0% (Wewnątrzwspólnotowa Dostawa Towarów)
0 EX	Export 0%
0 KR	Inländischer Nullsatz 0%
zw	Von der MwSt. befreit (zwolniona)
oo	Inländische Umkehrsteuerpflicht (odwrotne obciążenie)
np I	Nicht MwSt.-pflichtig – grenzüberschreitende Dienstleistungen
np II	Nicht MwSt.-pflichtig – inländische Dienstleistungen

Zahlungsmittel-Codes

Parameter: payment_means_type_code

Code	Beschreibung
1	Bargeld
2	Karte
3	Gutschein
4	Mobil
5	Scheck
6	Banküberweisung
7	Sonstige

Operationstypen

Parameter: type_operation (in der Steuerberichtseinstellung)

Code	Beschreibung
services	Dienstleistungen
goods	Waren