KSeF API 2.0 Leitfaden

1. Umgebungen

KSeF bietet drei verschiedene Umgebungen. Verwenden Sie für die Entwicklung immer TEST oder DEMO.

2. Authentifizierung

Jede API-Sitzung erfordert eine Token-Authentifizierung. Der vollständige Ablauf verwendet RSA-OAEP-Verschlüsselung des Tokens mit dem öffentlichen KSeF-Schlüssel.

Vollständiger Ablauf (API-Token)

1. GET  /security/public-key-certificates     → RSA keys
2. POST /auth/challenge                        → challenge + timestampMs
3. RSA-OAEP(token|timestampMs)                 → encrypt with "KsefTokenEncryption" key
4. POST /auth/ksef-token                       → challenge + encryptedToken
   → authenticationToken + referenceNumber (HTTP 202)
5. GET  /auth/{referenceNumber}                → poll until code=200
6. POST /auth/token/redeem                     → exchange → accessToken

Erforderliche Header für authentifizierte Aufrufe

Authorization: Bearer {accessToken}
Accept: application/json
Content-Type: application/json

Öffentliche Schlüssel

GET /security/public-key-certificates gibt 2 Zertifikate zurück:

Kein Fingerprint-Feld in der Antwort (entgegen der Dokumentation).

3. Online-Sitzung (interaktiv)

Zum Senden von Rechnungen ohne Anhänge, einzeln.

1. POST /sessions/online                           → open session
2. POST /sessions/online/{ref}/invoices             → send invoice
3. GET  /sessions/{ref}/invoices/{invoiceRef}        → check status
4. POST /sessions/online/{ref}/close                → close session

Sitzung öffnen

{
  "formCode": {"systemCode": "FA (3)", "schemaVersion": "1-0E", "value": "FA"},
  "encryption": {
    "encryptedSymmetricKey": "RSA-OAEP(aes_key, cert_SymmetricKeyEncryption)",
    "initializationVector": "base64(iv_16_bytes)"
  }
}

Der Client generiert den AES-256-Schlüssel und IV, verschlüsselt den Schlüssel mit RSA und sendet beides.

Rechnung senden

{
  "invoiceHash": "base64(SHA256(xml_raw))",
  "invoiceSize": 2048,
  "encryptedInvoiceHash": "base64(SHA256(xml_encrypted))",
  "encryptedInvoiceSize": 2064,
  "encryptedInvoiceContent": "base64(AES-256-CBC(xml_raw))"
}

AES-256-CBC-Verschlüsselung mit PKCS#7-Padding. Gleicher Schlüssel/IV wie die Sitzung.

4. Batch-Sitzung (wsadowa)

Zum Senden von Rechnungen mit oder ohne Anhänge, als Stapel (ZIP).

1. Create ZIP containing XML invoices (faktura_1.xml, faktura_2.xml, ...)
2. Encrypt ZIP with AES-256-CBC + PKCS#7 (NO IV prepend)
3. POST /sessions/batch           → open session, receive upload URL
4. PUT  {uploadUrl}               → upload encrypted ZIP (raw bytes)
5. POST /sessions/batch/{ref}/close  → close and start processing
6. GET  /sessions/{ref}           → poll session status
7. GET  /sessions/{ref}/invoices  → accepted invoices
8. GET  /sessions/{ref}/invoices/failed → rejected invoices

Batch-Sitzung öffnen

{
  "formCode": {"systemCode": "FA (3)", "schemaVersion": "1-0E", "value": "FA"},
  "batchFile": {
    "fileSize": 1078,
    "fileHash": "base64(SHA256(zip_raw))",
    "fileParts": [{
      "ordinalNumber": 1,
      "fileSize": 1088,
      "fileHash": "base64(SHA256(zip_encrypted))"
    }]
  },
  "encryption": {
    "encryptedSymmetricKey": "...",
    "initializationVector": "..."
  }
}

Ergebnisse pro Rechnung

Nach dem Schließen der Batch-Sitzung wird jede Rechnung unabhängig verarbeitet. Ergebnisse über zwei separate Endpoints abrufen.

GET /sessions/{ref}/invoices          → accepted invoices (with ksefNumber)
GET /sessions/{ref}/invoices/failed   → rejected invoices (with processingCode + error)

Die Verarbeitung ist parallel: Akzeptierte und abgelehnte Rechnungen können in anderer Reihenfolge als im ZIP erscheinen.

5. Verarbeitungscodes

API-Antworten verwenden Verarbeitungscodes (processingCode) zur Angabe des Anfragestatus. Derselbe Code kann je nach Endpoint (Auth, Sitzung, Rechnung, Export) leicht unterschiedliche Bedeutungen haben.

Fortschritt (100-299)

Fehler (400-550)

Source : Issue #526, OpenAPI spec, api-changelog.md

6. Limits

Überprüfbar über GET /limits/context.

7. Anhänge (Zalacznik)

Voraussetzungen

• 1.Aktivierung : POST /testdata/attachment mit {"nip": "..."} (TEST-Umgebung). In PROD: Erklärung über e-Urząd Skarbowy.
• 2.Batch-Sitzung erforderlich : der Online-Modus lehnt Anhänge ab (Code 415).

Überprüfung

GET /permissions/attachments/status (authenticated)

{"isAttachmentAllowed": true}
// or with revocation date:
{"isAttachmentAllowed": true, "revokedDate": "2026-12-31T23:59:59+00:00"}

XML-Struktur

'<Zalacznik>' ist ein direktes Kind von '<Faktura>' (nicht '<Fa>'), mit strukturiertem Inhalt:

<Faktura xmlns="http://crd.gov.pl/wzor/2025/06/25/13775/">
  <Naglowek>...</Naglowek>
  <Podmiot1>...</Podmiot1>
  <Podmiot2>...</Podmiot2>
  <Fa>...</Fa>
  <Zalacznik>
    <BlokDanych>
      <MetaDane>
        <ZKlucz>Key</ZKlucz>
        <ZWartosc>Value</ZWartosc>
      </MetaDane>
      <Tabela>
        <Opis>Table description</Opis>
        <TNaglowek>
          <Kol Typ="txt"><NKom>Column 1</NKom></Kol>
          <Kol Typ="int"><NKom>Column 2</NKom></Kol>
        </TNaglowek>
        <Wiersz>
          <WKom>Value 1</WKom>
          <WKom>42</WKom>
        </Wiersz>
      </Tabela>
    </BlokDanych>
  </Zalacznik>
</Faktura>

Spaltentypen: txt, int, dec, date.

Anhang-Fehlercodes

8. Testdata-Endpoints (TEST-Umgebung)

Keine Authentifizierung erforderlich. Diese Endpoints ermöglichen die Konfiguration der Testumgebung.

9. Informations-Endpoints

Authentifizierte Endpoints zur Überprüfung des Konto- und Rechnungsstatus.

10. Bekannte Probleme

Wichtige Punkte bei der Integration mit der KSeF-API, basierend auf unseren realen Tests:

Nützliche Links

• 🔗 KSeF-Dokumentation (GitHub CIRFMF)
• 🔗 KSeF OpenAPI-Spezifikation
• 🔗 Offizielles KSeF-Portal (podatki.gov.pl)