Przewodnik API KSeF 2.0

1. Środowiska

KSeF udostępnia trzy odrębne środowiska. Do prac programistycznych zawsze używaj TEST lub DEMO.

2. Uwierzytelnianie

Każda sesja API wymaga uwierzytelnienia tokenem. Pełny przepływ wykorzystuje szyfrowanie RSA-OAEP tokenu kluczem publicznym KSeF.

Pełny przepływ (token API)

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

Wymagane nagłówki dla uwierzytelnionych wywołań

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

Klucze publiczne

GET /security/public-key-certificates zwraca 2 certyfikaty:

Brak pola fingerprint w odpowiedzi (w przeciwieństwie do dokumentacji).

3. Sesja Online (interaktywna)

Do wysyłania faktur bez załączników, pojedynczo.

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

Otwarcie sesji

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

Klient generuje klucz AES-256 i IV, szyfruje klucz RSA, wysyła oba.

Wysyłanie faktury

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

Szyfrowanie AES-256-CBC z paddingiem PKCS#7. Ten sam klucz/IV co sesja.

4. Sesja Batch (wsadowa)

Do wysyłania faktur z załącznikami lub bez, w paczce (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

Otwarcie sesji batch

{
  "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": "..."
  }
}

Wyniki per faktura

Po zamknięciu sesji batch każda faktura jest przetwarzana niezależnie. Sprawdź wyniki za pomocą dwóch oddzielnych endpointów.

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

Przetwarzanie jest równoległe: zaakceptowane i odrzucone faktury mogą pojawić się w innej kolejności niż w ZIP.

5. Kody przetwarzania

Odpowiedzi API używają kodów przetwarzania (processingCode) do wskazania statusu żądania. Ten sam kod może mieć nieco inne znaczenie w zależności od endpointu (auth, sesja, faktura, eksport).

Postęp (100-299)

Błędy (400-550)

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

6. Limity

Weryfikowalne przez GET /limits/context.

7. Załączniki (Zalacznik)

Wymagania wstępne

• 1.Aktywacja : POST /testdata/attachment z {"nip": "..."} (środowisko TEST). W PROD: deklaracja przez e-Urząd Skarbowy.
• 2.Wymagana sesja batch : tryb online odrzuca załączniki (kod 415).

Weryfikacja

GET /permissions/attachments/status (authenticated)

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

Struktura XML

'<Zalacznik>' jest bezpośrednim dzieckiem '<Faktura>' (nie '<Fa>'), ze strukturą ustrukturyzowaną:

<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>

Typy kolumn: txt, int, dec, date.

Kody błędów załączników

8. Endpointy testdata (środowisko TEST)

Nie wymaga uwierzytelnienia. Te endpointy pozwalają skonfigurować środowisko testowe.

9. Endpointy informacyjne

Uwierzytelnione endpointy do sprawdzania statusu konta i faktur.

10. Znane problemy

Kwestie do uwzględnienia podczas integracji z API KSeF, na podstawie naszych rzeczywistych testów:

Przydatne linki

• 🔗 Dokumentacja KSeF (GitHub CIRFMF)
• 🔗 Specyfikacja OpenAPI KSeF
• 🔗 Oficjalny portal KSeF (podatki.gov.pl)