Spécifications API KSeF

L'API KSeF est une API REST hébergée sur ksef.mf.gov.pl, exposant trois canaux d'usage — Sesja Interaktywna (interactive), Sesja Wsadowa (batch), et Common (consultation). Authentification par hiérarchie token, format JSON avec XML FA(2) embarqué en base64.

Environnements et endpoints

Le ministère opère trois environnements distincts pour KSeF :

• Production (Produkcja). ksef.mf.gov.pl — l'environnement de référence légal. Toute facture qui y transite reçoit un numer KSeF juridiquement valide.
• Préproduction (Przedprodukcyjna). ksef-test.mf.gov.pl — environnement miroir de production pour tests d'intégration éditeur. Aucune valeur juridique. Les NIP utilisés doivent être réels.
• Démo (Demonstracja). ksef-demo.mf.gov.pl — sandbox avec NIP fictifs et données générées. Idéal pour formation et développement initial.

Authentification — hiérarchie OAuth 2.0

KSeF utilise une hiérarchie à trois niveaux, inspirée d'OAuth 2.0 mais spécifique au ministère :

1. AuthorizationToken. Token primaire généré une fois par le contribuable, dans le portail KSeF (interface humaine) ou via signature XAdES par certificat e-IDAS. Valide 24 mois, scope par défaut fakturujący sur le NIP propriétaire.
2. SessionToken. Obtenu par InitToken en échange de l'AuthorizationToken. Valide 4 heures glissantes. Sert à enchaîner les opérations facture par facture sans repayer le coût de l'auth.
3. AccessToken (alias contextuel). Pour les délégations (e.g. comptable externe agissant pour le compte du contribuable). Lie l'AuthorizationToken à un Uprawnienie spécifique (droit) sur un NIP tiers.

POST /api/online/Session/InitToken HTTP/1.1
Host: ksef.mf.gov.pl
Content-Type: application/octet-stream
Content-Encoding: base64

PFNlc3Npb25Ub2tlblJlcXVlc3QgeG1sbnM9Imh0dHA6Ly9rc2VmLm1mLmdvdi5wbC8iPgogIDxJ
ZGVudGlmaWVyVHlwZT5vbmlwPC9JZGVudGlmaWVyVHlwZT4KICA8SWRlbnRpZmllcj41MjYwMjUw
Mjc0PC9JZGVudGlmaWVyPgogIDxBdXRob3JpemF0aW9uVG9rZW4+ZXk...PC9BdXRob3JpemF0
aW9uVG9rZW4+CjwvU2Vzc2lvblRva2VuUmVxdWVzdD4=

HTTP/1.1 201 Created
Content-Type: application/json

{
  "timestamp": "2026-05-19T08:42:11Z",
  "referenceNumber": "20260519-SE-3F4B7A2D9C-DA",
  "sessionToken": {
    "token": "eyJhbGciOiJSUzI1NiIs...",
    "context": {
      "nip": "5260250274",
      "name": "Spółka Sprzedaży Sp. z o.o.",
      "schemaVersion": "1-0E"
    }
  }
}

Flux interactive — Sesja Online

Le flux interactif est conçu pour l'émission au fil de l'eau, facture par facture. C'est le mode privilégié des ERP en intégration directe et des portails web.

1. POST /api/online/Session/InitToken — ouvrir la session, récupérer le SessionToken
2. POST /api/online/Invoice/Send — soumettre la facture FA(2) (en base64 dans invoiceBody)
3. GET /api/online/Invoice/Status/{ref} — récupérer le statut et le numer KSeF
4. POST /api/online/Session/Terminate — fermer la session (libère les ressources serveur)

POST /api/online/Invoice/Send HTTP/1.1
Host: ksef.mf.gov.pl
SessionToken: eyJhbGciOiJSUzI1NiIs...
Content-Type: application/json

{
  "invoiceHash": {
    "hashSHA": {
      "algorithm": "SHA-256",
      "encoding": "Base64",
      "value": "9c1185a5c5e9fc54612808977ee8f548b2258d31"
    },
    "fileSize": 4892
  },
  "invoicePayload": {
    "type": "plain",
    "invoiceBody": "PD94bWwgdmVyc2lvbj0iMS4wIi..."
  }
}

HTTP/1.1 201 Created
Content-Type: application/json

{
  "elementReferenceNumber": "20260519-SE-3F4B7A2D9C-DA",
  "processingDescription": "Przyjęte",
  "referenceNumber": "20260519-IN-7C8A3D4E5F-AA",
  "timestamp": "2026-05-19T08:42:17Z"
}

Le statut transactionnel est dans processingDescription. Trois valeurs principales :

• Przyjęte — facture acceptée par le validateur, numer KSeF attribué dans referenceNumber
• Odrzucone — facture rejetée par le validateur, code erreur dans statusCode
• W trakcie przetwarzania — traitement asynchrone en cours, requête à recommencer après 1-2 secondes

Flux batch — Sesja Wsadowa

Le mode Wsadowa permet d'envoyer un paquet de factures regroupées dans une archive ZIP signée, traitée de manière asynchrone par KSeF. Mode privilégié pour les éditeurs ERP gérant de gros volumes.

1. Préparation locale. Constituer une archive ZIP contenant chaque facture FA(2) en fichier XML individuel (un fichier = une facture). Limite : 50 factures par archive, taille maximale 100 Mo.
2. Calcul hash et chiffrement. Hash SHA-256 de chaque fichier XML inclus. Chiffrement AES-256-CBC de l'archive avec une clé symétrique aléatoire, elle-même chiffrée RSA avec le certificat public KSeF.
3. POST /api/batch/Session/Init. Soumettre le manifeste (liste factures + hashes + clé chiffrée). KSeF répond avec une URL de dépôt et un BatchSessionReferenceNumber.
4. PUT sur l'URL de dépôt. Uploader l'archive ZIP chiffrée.
5. POST /api/batch/Session/Close. Déclencher le traitement.
6. Polling GET /api/common/Status/{ref}. Suivre le statut. Délai cible : 5 à 30 minutes selon volume.

Limites et quotas

Codes d'erreur 21xxx

Les codes d'erreur KSeF suivent une convention 21xxx. Catalogue partiel des erreurs fréquentes :

Pièges courants

• Mauvaise base URL. L'environnement test (ksef-test) et démo (ksef-demo) sont souvent confondus. Vérifier les NIP utilisés — vrais pour test, fictifs pour démo. Une erreur est rejetée avec code 21200.
• Encodage base64 avec saut de ligne. Certaines libs base64 insèrent des sauts toutes les 76 chars (RFC 2045 MIME). KSeF n'accepte que le base64 sans saut de ligne (RFC 4648 strict).
• Content-Length manquant. Sur POST avec body binaire, KSeF exige un Content-Length exact. Les libs HTTP qui utilisent Transfer-Encoding: chunked sont rejetées.
• Pieces jointes binaires. KSeF n'accepte que du XML pur. Toute pièce jointe (PDF, image) doit être référencée hors KSeF et transmise par un autre canal. Les liens externes vers cloud storage sont acceptés dans FaWiersz/DodatkoweInfo.
• Caractères diacritiques polonais. Les ą, ć, ę, ł, ń, ó, ś, ź, ż doivent être encodés en UTF-8 (jamais en Windows-1250 ou ISO 8859-2). KSeF rejette les caractères mal encodés avec code 21420.

Liens transverses

• Hub Pologne — mandat KSeF complet
• KSeF obligatoire 2026
• FA(2) — format de facture structurée
• Numer KSeF — UUID juridique
• e-Doręczenia — notification associée
• OAuth 2.0 — RFC 6749 (IETF)
• ksef.mf.gov.pl — portail développeur
• Dokumentacja API KSeF (FA(2))