Die PSB kennt zwei KSeF-Hooks: einen Outbound-Hook für ausgehende Rechnungen (verkaufende Partei / Podmiot1) und einen Inbound-Hook für eingehende Rechnungen (kaufende Partei / Podmiot2). Beide automatisieren den Austausch mit dem Krajowy System e-Faktur (KSeF), dem polnischen nationalen E-Rechnungssystem. Der Outbound-Hook wird nachfolgend zuerst beschrieben; der Inbound-Hook steht am Ende dieser Seite.

Der KSeF-Outbound-Hook automatisiert die Registrierung ausgehender Rechnungen beim KSeF. Rechnungen werden von Peppol BIS Billing 3.0 / UBL (intern auch BisV3) in das polnische FA(3)-Format transformiert und als Batch registriert. Der Kunde kann auch selbst FA(3) liefern, dann entfällt der Transformationsschritt. Nach erfolgreicher Verarbeitung liefert der Hook das UPO (Urzędowe Poswiadczenie Odbioru, die offizielle Empfangsbestätigung) und einen PDF-Beleg über die PSB-Plattform zurück.

Für Test und Abnahme bietet die polnische Regierung neben der Produktionsumgebung zwei weitere Umgebungen an:

Der Hook unterstützt sowohl einen Online-Flow (direkte Registrierung) als auch einen Offline-Flow (wenn KSeF vorübergehend nicht erreichbar ist, beispielsweise während des täglichen Cutoffs). Im Offline-Flow wird eine Offline-PDF auf Basis des Offline-Zertifikats generiert.

• Ein gültiges Online-Zertifikat für KSeF (.key + .crt; Authentifizierung während des Online-Flows)
• Ein gültiges Offline-Zertifikat für KSeF (.key + .crt; QR-Codes in der PDF-Ausgabe, sowohl bei Online- als auch bei Offline-Verarbeitung)
• Die zugehörigen Passwörter beider Zertifikate
• Der Hook muss in der Konfiguration aktiviert sein

Nach Empfang einer Rechnungsbenachrichtigung durchläuft der Hook sieben Schritte:

Wenn KSeF nicht erreichbar ist (täglicher Cutoff oder Störung), startet automatisch der Offline-Flow: Es wird eine Offline-PDF über das Offline-Zertifikat generiert, woraufhin die Rechnung über den regulären Kanal versendet wird.

Registrieren Sie den Hook über die Hooks API:

{
  "id": "ksef-sender",
  "action": "ksef",
  "name": "KSeF Hook Sender",
  "topics": [
    "ClearInvoiceBatched"
  ],
  "output": [
    {
      "when": "200",
      "topic": "SendInvoice"
    },
    {
      "when": "410",
      "topic": "SendInvoice"
    }
  ],
  "init": {
    "onlineCertificate": "{{pfad-zum-online-zertifikat}}",
    "onlineCertificatePassword": "{{passwort}}",
    "offlineCertificate": "{{pfad-zum-offline-zertifikat}}",
    "offlineCertificatePassword": "{{passwort}}"
  },
  "isActive": true
}

Wichtig: Alle vier Zertifikatsfelder sind erforderlich. Das Online-Zertifikat wird für die Authentifizierung während des Online-Flows benötigt. Das Offline-Zertifikat wird für die Generierung von QR-Codes in der PDF benötigt, sowohl bei der Online- als auch bei der Offline-Verarbeitung.

Bei Statuscode 410 startet die PSB automatisch den Offline-Flow. Die Rechnung wird dann lokal mit dem Offline-Zertifikat verarbeitet und gesendet, sobald KSeF wieder verfügbar ist. Bei 429 plant die PSB einen automatischen Retry ein.

KSeF hat eine tägliche Cutoff-Periode, während der das System für die Batch-Registrierung nicht verfügbar ist. Nach etwa 23:00 Uhr polnischer Ortszeit greift der Offline-Flow, sobald KSeF nicht erreichbar ist (Statuscode 410):

• Online: Die Rechnung wird direkt bei KSeF registriert, das UPO wird abgerufen und eine PDF mit QR-Codes wird generiert
• Offline: Die Rechnung wird lokal verarbeitet, eine Offline-PDF mit einem Offline-QR-Code wird über das Offline-Zertifikat generiert. Die Rechnung wird an den Empfänger gesendet, ohne dass sie bereits bei KSeF angemeldet wurde.

Nach Rückkehr von KSeF werden offline verarbeitete Rechnungen nachträglich registriert, und die Rechnung erhält den Statuscode 201 (InvoiceCleared). Die Rechnung wird dann nicht erneut an den Empfänger gesendet; der zuvor gesendete Offline-QR-Code verweist nach dieser späteren Anmeldung auf die bestätigte KSeF-Registrierung.

Nach der Online-Clearance liefert KSeF eine Referenznummer. Diese Nummer steht im UPO und in den Details des ausgehenden Webhooks, zum Beispiel:

"details": {
  "clearanceReference": "234563218-20260220-50683A000001-11",
  "clearanceSystem": "KSeF"
}

Bewahren Sie die Referenznummer im versendenden ERP als Nachweis der Anmeldung bei KSeF auf.

Bei großen Volumina: Setzen Sie einen Batch-Hook vor den KSeF-Hook, sodass Rechnungen periodisch (beispielsweise alle 15 Sekunden bis zu 1 Minute, oder maximal 100 Stück) als Batch an KSeF gehen. So erreicht die Integration weniger schnell die KSeF-Ratelimits. Bevorzugtes Topic-Muster: ClearInvoice → Batch → ClearInvoiceBatched → KSeF-Hook. Zusätzlich ist ein separater Hook nötig, der ausgehende Rechnungen auf Topic ClearInvoice publiziert (abhängig vom Flow).

Beispiel Batch-Hook (bevorzugt; Parameter je Kunde abstimmen):

{
  "id": "batchClearInvoice",
  "name": "Batch Invoices for KSeF",
  "action": "batch://zip?period=00:01:00&maxBatchSize=100&excludePrimaryAttachment=false&includeAdditionalAttachments=true&hashAlgorithm=sha256&includeRefToMetaAttributes=true&targetDocumentTypeId=econnect-docid%3A%3Ahttp%3A%2F%2Fcrd.gov.pl%2Fwzor%2F2025%2F06%2F25%2F13775%3A%3AFaktura%23%23ksef%3A%3A3.0",
  "topics": ["ClearInvoice"],
  "isActive": true
}

Kurze Action-Form (gleiches FA(3)-Ziel; Period zum Beispiel 00:00:15):

batch://zip?period=00:00:15&maxBatchSize=100&excludePrimaryAttachment=false&includeAdditionalAttachments=true&hashAlgorithm=sha256&includeRefToMetaAttributes=true&targetDocumentTypeId=econnect-docid%3A%3Ahttp%3A%2F%2Fcrd.gov.pl%2Fwzor%2F2025%2F06%2F25%2F13775%3A%3AFaktura%23%23ksef%3A%3A3.0

Manche Kunden können keine Rechnungen mit Topic ClearInvoice versenden (zum Beispiel Business Central). Passen Sie den Batch-Hook dann so an, dass er auf SendInvoice lauscht und weiterhin ClearInvoiceBatched publiziert:

{
  "id": "batchClearInvoice",
  "name": "Batch Invoices for KSeF",
  "action": "batch://zip?period=00:01:00&maxBatchSize=100&excludePrimaryAttachment=false&includeAdditionalAttachments=true&hashAlgorithm=sha256&includeRefToMetaAttributes=true&targetDocumentTypeId=econnect-docid%3A%3Ahttp%3A%2F%2Fcrd.gov.pl%2Fwzor%2F2025%2F06%2F25%2F13775%3A%3AFaktura%23%23ksef%3A%3A3.0",
  "topics": ["SendInvoice"],
  "output": [
    { "when": "200", "topic": "ClearInvoiceBatched" },
    { "when": "500", "topic": "ClearInvoiceBatchedError" },
    { "when": "429", "topic": "ClearInvoiceBatchedRetry" }
  ],
  "isActive": true
}

Der KSeF-Inbound-Hook verarbeitet eingehende Rechnungen für die kaufende Partei (Podmiot2). Der Hook pollt periodisch KSeF auf neue Rechnungen, ruft die Rechnungs-XML pro KSeF-Nummer ab und liefert diese über die PSB-Plattform aus.

Die Authentifizierung gegenüber KSeF erfolgt ausschließlich über ein Online-Zertifikat (.key + .crt + Passwort). Der Inbound-Flow kennt keine Offline-Variante, im Gegensatz zum Outbound-Hook. Bei vorübergehender KSeF-Nichterreichbarkeit wird das Polling gemäß der konfigurierten Retry-Policy erneut versucht.

Wird während Fetch keine Rechnung gefunden, springt der Hook direkt zu Complete: Es wird nichts verarbeitet oder publiziert.

• Ein gültiges Online-Zertifikat für KSeF (.key + .crt) plus zugehöriges Passwort.
• Der Hook muss in der Konfiguration aktiviert sein.
• Die Init-Felder onlineCertificate und onlineCertificatePassword sind erforderlich (keine Offline-Zertifikatsfelder).

Der Inbound-Hook wird über TechSupport eingerichtet: Die Zertifikatsverarbeitung ist ein Techsupport-only-Verfahren, kein Self-Service.

Der Action-Parameter bestimmt das Zeitfenster, in das der Hook zurückblickt: ksef:inbound?lookbackWindow=<Fenster>. In init steht nur das Online-Zertifikat.

Standard (publiziert auf Topic ReceiveInvoice):

{
  "id": "ksef-inbound",
  "action": "ksef:inbound?lookbackWindow=08:00:00",
  "name": "KSeF Hook Inbound",
  "publishTopics": ["ReceiveInvoice"],
  "init": {
    "onlineCertificate": "{{pfad-zum-online-zertifikat}}",
    "onlineCertificatePassword": "{{passwort}}"
  },
  "isActive": true
}

Nach dem Inbound-Hook gehört immer ein Folgehook, der die empfangene Rechnung weiterverarbeitet.

Collabrr-Plattformvariante: Auf der Collabrr-Plattform lauscht der Hook im Tenant mit publishTopics: ["InvoiceReceived"]. Die Organisation muss auf der Plattform für den Peppol-Empfang registriert sein. Beispiel-Action: ksef:inbound?lookbackWindow=08.00:00:00.

Der Parameter lookbackWindow bestimmt das Zeitfenster, in das der Hook beim Polling/Erstellen zurückblickt:

• In Stunden, zum Beispiel "08:00:00"
• In Tagen, zum Beispiel "60.00:00:00"

KSeF begrenzt das Zurückblicken auf maximal 3 Monate. Bei Überschreitung erfolgt eine Fehlermeldung:

21405: Błąd walidacji danych wejściowych. - 'dateRange' must not exceed 3 months.

Zudem gilt ein Request-Rate-Limit gegenüber KSeF. Berücksichtigen Sie dies beim Aktivieren mehrerer Entitäten mit einem (großen) lookbackWindow.

Möchten Sie mehr über E-Rechnungsstellung in Polen erfahren? Lesen Sie die Länderseite zur polnischen KSeF-Pflicht.