Guide API KSeF 2.0

1. Environnements

Le KSeF propose trois environnements distincts. Utilisez toujours TEST ou DEMO pour le développement.

2. Authentification

Chaque session API nécessite une authentification par token. Le flux complet utilise un chiffrement RSA-OAEP du token avec la clé publique du KSeF.

Flux complet (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

Headers requis pour les appels authentifiés

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

Clés publiques

GET /security/public-key-certificates renvoie 2 certificats :

Pas de champ fingerprint dans la réponse (contrairement à la documentation).

3. Session Online (interactive)

Pour envoyer des factures sans pièce jointe, une par une.

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

Ouverture de session

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

Le client génère la clé AES-256 et l'IV, chiffre la clé avec RSA, envoie les deux.

Envoi d'une facture

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

Chiffrement AES-256-CBC avec PKCS#7 padding. Même clé/IV que la session.

4. Session Batch (wsadowa)

Pour envoyer des factures avec ou sans pièces jointes, en lot (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

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

Retours par facture

Après fermeture de la session batch, chaque facture est traitée indépendamment. Consultez les résultats via deux endpoints distincts.

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

Le traitement est parallèle : les factures acceptées et rejetées peuvent apparaître dans un ordre différent de celui du ZIP.

5. Codes de traitement

Les réponses API utilisent des codes de traitement (processingCode) pour indiquer l'état de la requête. Un même code peut avoir des significations légèrement différentes selon l'endpoint (auth, session, facture, export).

Progression (100-299)

Erreurs (400-550)

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

6. Limites

Vérifiable via GET /limits/context.

7. Pièces jointes (Zalacznik)

Prérequis

• 1.Activation : POST /testdata/attachment avec {"nip": "..."} (env TEST). En PROD : déclaration via e-Urząd Skarbowy.
• 2.Session batch obligatoire : le mode online rejette les PJ (code 415).

Vérification

GET /permissions/attachments/status (authenticated)

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

Structure XML

'<Zalacznik>' est un enfant direct de '<Faktura>' (pas de '<Fa>'), avec structure structurée :

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

Types de colonnes : txt, int, dec, date.

Codes erreur PJ

8. Endpoints testdata (env TEST)

Pas besoin d'authentification. Ces endpoints permettent de configurer l'environnement de test.

9. Endpoints d'information

Endpoints authentifiés pour consulter l'état de votre compte et de vos factures.

10. Problèmes connus

Points d'attention lors de l'intégration avec l'API KSeF, basés sur nos tests réels :

Liens utiles

• 🔗 Documentation KSeF (GitHub CIRFMF)
• 🔗 Spécification OpenAPI KSeF
• 🔗 Portail officiel KSeF (podatki.gov.pl)