Guida API KSeF 2.0

1. Ambienti

KSeF fornisce tre ambienti distinti. Utilizza sempre TEST o DEMO per lo sviluppo.

2. Autenticazione

Ogni sessione API richiede l'autenticazione tramite token. Il flusso completo utilizza la crittografia RSA-OAEP del token con la chiave pubblica del KSeF.

Flusso completo (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

Header richiesti per le chiamate autenticate

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

Chiavi pubbliche

GET /security/public-key-certificates restituisce 2 certificati:

Nessun campo fingerprint nella risposta (contrariamente alla documentazione).

3. Sessione Online (interattiva)

Per inviare fatture senza allegati, una alla volta.

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

Apertura della sessione

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

Il client genera la chiave AES-256 e l'IV, crittografa la chiave con RSA e invia entrambi.

Invio di una fattura

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

Crittografia AES-256-CBC con padding PKCS#7. Stessa chiave/IV della sessione.

4. Sessione Batch (wsadowa)

Per inviare fatture con o senza allegati, in blocco (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

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

Risultati per fattura

Dopo la chiusura della sessione batch, ogni fattura viene elaborata in modo indipendente. Consultare i risultati tramite due endpoint separati.

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

L'elaborazione è parallela: le fatture accettate e rifiutate possono apparire in un ordine diverso rispetto allo ZIP.

5. Codici di elaborazione

Le risposte API utilizzano codici di elaborazione (processingCode) per indicare lo stato della richiesta. Lo stesso codice può avere significati leggermente diversi a seconda dell'endpoint (auth, sessione, fattura, export).

Progressione (100-299)

Errori (400-550)

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

6. Limiti

Verificabile tramite GET /limits/context.

7. Allegati (Zalacznik)

Prerequisiti

• 1.Attivazione : POST /testdata/attachment con {"nip": "..."} (ambiente TEST). In PROD: dichiarazione tramite e-Urząd Skarbowy.
• 2.Sessione batch obbligatoria : la modalità online rifiuta gli allegati (codice 415).

Verifica

GET /permissions/attachments/status (authenticated)

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

Struttura XML

'<Zalacznik>' è un figlio diretto di '<Faktura>' (non di '<Fa>'), con contenuto strutturato:

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

Tipi di colonna: txt, int, dec, date.

Codici errore allegati

8. Endpoint testdata (ambiente TEST)

Nessuna autenticazione richiesta. Questi endpoint permettono di configurare l'ambiente di test.

9. Endpoint informativi

Endpoint autenticati per consultare lo stato del proprio account e delle fatture.

10. Problemi noti

Punti di attenzione durante l'integrazione con l'API KSeF, basati sui nostri test reali:

Link utili

• 🔗 Documentazione KSeF (GitHub CIRFMF)
• 🔗 Specifica OpenAPI KSeF
• 🔗 Portale ufficiale KSeF (podatki.gov.pl)