E-Invoice Finder
Menu
Pays Logiciels Échéances Guides Checker Vérifier obligation
ENFRDEPLNL
Pologne · exploitation KSeF

Surveiller l’API KSeF et gérer les incidents ERP

Surveillez sessions, statuts de facture, UPO, limites et incidents KSeF avec une procédure ERP de rapprochement, alerte et reprise sûre.

Résumé pratique :
  • Périmètre : suivre sessions, factures, références et UPO jusqu’au rapprochement ERP.
  • Risque : un transport réussi ou un délai dépassé ne prouve ni acceptation ni panne officielle.
  • Action : interroger l’état courant, conserver les preuves et soumettre les cas ambigus à revue.
Voir le rapport PologneSources officielles
Dernière vérification : 27 juillet 2026Sources officiellesRésumé clairInformation pratique, pas un conseil juridique
Sources officielles priorisées
Dates de vérification visibles
Checker gratuit, sans inscription

Ce qu’il faut savoir

Guide

Un modèle de surveillance fondé sur la corrélation

KSeF 2.0 traite les envois de manière asynchrone : la réponse de transport n’est donc que le début du suivi. Pour chaque opération, conservez la référence de session, la référence propre à chaque facture, l’identifiant local de l’ERP ou du job, les horodatages utiles et, lorsqu’ils sont retournés, le numéro KSeF et le statut courant. Cette chaîne relie l’écriture comptable, l’appel API et sa preuve sans conserver le contenu de la facture. Le modèle de surveillance doit couvrir les sessions interactives et batch. Le guide officiel des intégrateurs du 20 avril 2026 décrit notamment la liste des sessions, la consultation d’une session, les comptes agrégés de factures, la liste des factures d’une session et la consultation d’une facture par sa référence. Une vue agrégée aide à repérer un écart, mais ne remplace jamais le rapprochement facture par facture. Par exemple, 98 traitements sur 100 ne révèlent pas les deux factures à examiner. Ne fermez donc pas le job ERP sur le seul total de session.

Guide

Distinguer cycle de session, cycle de facture et disponibilité de l’UPO

Le tableau de bord doit représenter séparément l’état de la session et celui de chaque facture. Selon les réponses API courantes, une opération peut être en attente ou en cours de traitement, traitée avec succès, ou rejetée. N’attribuez pas une signification maison à un code et ne marquez jamais une facture comme acceptée parce que la requête HTTP a abouti : utilisez la documentation OpenAPI et les documents officiels actuels comme vérité d’exécution, car les points d’accès et les statuts peuvent évoluer. L’API permet de télécharger un UPO de facture ou de session lorsque la réponse expose une référence d’UPO disponible. Il faut donc vérifier cette disponibilité avant de proposer le téléchargement. Un UPO de session facilite l’archivage d’un traitement collectif ; un UPO de facture sert au dossier individuel correspondant. Ne promettez ni l’un ni l’autre avant leur mise à disposition. Affichez « UPO non encore disponible — état à recontrôler » et liez chaque preuve à la bonne session ou facture.

Guide

Champs d’observabilité, métriques et tableau de bord

Journalisez des métadonnées minimales et non sensibles : identifiant du job ERP, références KSeF de session et de facture, type d’opération, horodatage de la demande et de la réponse, statut observé, numéro KSeF retourné, présence d’une référence UPO, catégorie d’erreur, nombre de tentatives techniques et identifiant de trace interne. N’enregistrez jamais le XML de facture, les identifiants d’authentification, les jetons, les clés privées ni d’autres secrets. Masquez également les en-têtes et paramètres susceptibles d’en contenir. Les métriques utiles portent sur les volumes par état, l’âge des éléments non finalisés, les écarts entre totaux ERP et KSeF, les rejets par catégorie connue, les réponses 429, la profondeur des files d’attente et le nombre de cas en revue manuelle. Le tableau de bord doit relier session, factures et trace ERP sans exposer les données. Affichez la dernière observation : une API disponible peut masquer des écarts métier.

Guide

Alertes, gravité et responsabilités opérationnelles

Définissez la gravité à partir de l’impact vérifié, non d’un délai arbitraire. Une anomalie isolée et explicable peut rester dans la file opérationnelle ; plusieurs erreurs corrélées, une file qui ne se résorbe pas ou l’impossibilité de rapprocher des factures critiques justifient une escalade. Les seuils doivent être configurables à partir de vos volumes, de vos processus et des communications officielles, sans inventer un SLA KSeF. Attribuez un propriétaire à chaque étape : l’exploitation surveille les files et les réponses ; l’équipe ERP vérifie la corrélation et les écritures ; la sécurité traite les incidents de secrets ; la comptabilité ou la fiscalité décide des cas métier ; le fournisseur corrige son connecteur. L’alerte contient références, impact, dernières réponses et actions tentées, sans charge utile. Prévoyez suppléant et escalade : toute anomalie ne relève pas du développeur de garde.

Guide

HTTP 429, limites et reprise sans doublon

KSeF applique des limites d’API et de contexte. Les limites par défaut indiquent notamment un maximum de 10 000 factures dans une session interactive ou batch, mais les limites courantes ou individuelles peuvent différer et être consultées. Dimensionnez les lots sur les valeurs réellement obtenues, pas sur une constante cachée dans le code. Pour les téléchargements incrémentaux, la documentation officielle exige explicitement de gérer HTTP 429 et l’en-tête Retry-After. La reprise doit respecter cette indication, réduire la pression et conserver son point de progression ; n’inventez ni cadence de sondage ni nombre fixe de tentatives. Rendez les jobs idempotents avec une clé stable et une table de corrélation. Après un timeout ou une réponse ambiguë, ne renvoyez pas automatiquement la facture : recherchez d’abord la session et la référence de facture, puis rapprochez l’état présent. Si l’existence ou le résultat reste incertain, placez le dossier en quarantaine ou en revue manuelle. La file de reprise doit distinguer échec certain, état KSeF connu et état indéterminé.

Guide

Rejets, revue manuelle et rapprochement ERP

Un rejet doit devenir un objet de travail traçable, pas une simple ligne rouge. Conservez la référence concernée, la réponse structurée utile, la catégorie interne, le propriétaire, la décision et la date de résolution. Orientez les erreurs corrigibles vers une file contrôlée et les cas ambigus vers une file morte ou une revue manuelle. Toute correction doit préserver l’historique des versions et de la nouvelle soumission autorisée. Le rapprochement compare chaque facture attendue avec son état KSeF courant, son éventuel numéro KSeF et sa preuve disponible. Vérifiez aussi que les factures listées dans une session correspondent à celles prévues par le job ERP. Des totaux égaux peuvent concerner des éléments différents : produisez un rapport d’exception. Avant toute relance, classez le cas comme non reçu de façon démontrable, reçu et en cours, traité avec succès, rejeté, ou indéterminé. Seule une décision fondée sur les preuves disponibles doit déclencher la suite.

Guide

Communications officielles et frontière des modes hors ligne

Surveillez les communications techniques officielles de KSeF et archivez le message pertinent avec l’incident. La documentation distingue le mode offline24 choisi par le contribuable, le mode hors ligne pendant une indisponibilité annoncée, le mode d’urgence lors d’une panne officiellement annoncée et la défaillance totale. Ces catégories ne sont pas interchangeables et leurs procédures doivent suivre les communications et règles approuvées. Un timeout, une série de réponses lentes ou une panne de votre réseau ne suffit pas à autoriser un basculement vers un mode officiel d’indisponibilité ou d’urgence. L’ingénieur peut constater un symptôme et protéger les files, mais il ne doit pas déduire seul le régime applicable. Le runbook doit imposer une vérification de la source officielle, l’identification de l’autorité interne habilitée et la consignation de la décision. Séparez donc la réponse technique — suspendre, mettre en file, préserver les données — de la décision métier ou réglementaire. Cette frontière évite d’appliquer une procédure exceptionnelle sur un diagnostic local erroné.

Guide

Exercice sur table : timeout après un envoi batch

Scénario : un job ERP soumet un lot, reçoit une référence de session, puis subit un timeout avant d’afficher les résultats détaillés. L’opérateur gèle la relance automatique, ouvre un incident et rassemble l’identifiant du job, la référence de session, les références de facture, les horodatages, la trace non sensible et la dernière réponse connue. Il consulte ensuite l’état de la session, ses comptes agrégés, la liste des factures et le statut de chaque référence. Les éléments traités sont rapprochés avec leur numéro KSeF ; les rejets vont en revue ; les états encore non finalisés restent suivis ; un UPO n’est téléchargé que si sa référence est exposée. L’équipe vérifie aussi les communications techniques officielles. En leur absence, elle ne déclare pas un mode d’urgence à partir du timeout. Si des 429 apparaissent pendant les contrôles, elle respecte Retry-After et évite une boucle agressive. L’exercice réussit si chaque facture est classée, sans doublon, avec une décision reconstituable. Corrigez ensuite références manquantes, logs sensibles et responsabilités floues.

Guide

Choisir un fournisseur et passer à l’action

Évaluez un connecteur sur des démonstrations vérifiables : suivi séparé des sessions et factures, conservation des références, lecture des agrégats et des listes, téléchargement conditionnel des UPO, gestion de 429 et Retry-After, découverte des limites, reprise idempotente, files de revue, masquage des secrets et export des preuves. Demandez comment il évite les doublons après un résultat ambigu et suit l’OpenAPI actuelle ; une promesse de « haute disponibilité » ne suffit pas. Exigez un test avec succès, rejet, traitement non finalisé, UPO indisponible, 429 et timeout après soumission. Vérifiez que les opérateurs peuvent expliquer chaque écran et retrouver le dossier ERP sans consulter la charge utile. Convenez des responsabilités de mise à jour, du suivi des communications officielles et d’exercices réguliers. Enfin, commencez par cartographier vos identifiants et états, puis construisez le rapport d’exception avant d’automatiser la relance. Cette page fournit une base opérationnelle et non un avis juridique ou fiscal ; faites valider les procédures ayant une portée réglementaire par vos responsables compétents.

Checklist

Enregistrer la référence de session, chaque référence de facture et l’identifiant stable du job ERP.

Conserver les horodatages, le statut observé et tout numéro KSeF retourné sans journaliser la facture.

Rapprocher chaque facture individuellement même lorsque les comptes agrégés de session concordent.

Afficher un UPO comme téléchargeable uniquement lorsqu’une référence disponible est exposée.

Traiter les états en attente, les succès et les rejets selon les réponses API actuelles, sans déduction locale.

Respecter Retry-After après HTTP 429 et consulter les limites courantes avant de dimensionner les lots.

Bloquer toute relance automatique lorsque l’état de la facture demeure incertain.

Acheminer rejets et ambiguïtés vers des files de revue avec propriétaire et historique de décision.

Vérifier les communications officielles avant toute décision liée à une indisponibilité ou une urgence.

Tester régulièrement timeout, 429, rejet, UPO différé, reprise idempotente et absence de secrets dans les logs.

Questions fréquentes

Comment vérifier le statut d’une session KSeF ?

Listez les sessions ou consultez-en une par sa référence. Examinez son état, ses comptes et ses factures, puis rapprochez chaque référence avec le job ERP. Le total ne prouve pas le résultat individuel.

Comment vérifier le statut d’une facture KSeF ?

Conservez sa référence, puis utilisez la consultation correspondante. Classez le résultat d’après la réponse API actuelle : non finalisé, traité avec succès ou rejeté. Ne confondez pas transport HTTP réussi et résultat métier.

Quand peut-on télécharger un UPO ?

Seulement lorsque KSeF expose une référence d’UPO disponible. Sinon, indiquez que la preuve n’est pas encore disponible et poursuivez le suivi ; le traitement est asynchrone.

Faut-il conserver l’UPO de session ou celui de facture ?

Ils répondent à des niveaux différents : la session couvre le traitement collectif, l’UPO de facture le document individuel. Préservez les relations entre session, factures et preuves selon votre politique validée.

Quelles données faut-il conserver pour le rapprochement ?

Gardez les références de session et de facture, l’identifiant ERP, les horodatages, les statuts utiles, le numéro KSeF et les références d’UPO. Excluez des logs factures, jetons, clés et secrets.

Que faire face à un état pending, un rejet ou HTTP 429 ?

Surveillez un état non finalisé sans cadence inventée. Pour un rejet, ouvrez une exception traçable. Après HTTP 429, respectez Retry-After, réduisez la pression et reprenez au point conservé.

Comment relancer sans créer de doublon après un timeout ?

Ne renvoyez pas immédiatement. Recherchez la session et la facture, puis rapprochez leur état. S’il reste incertain, imposez quarantaine ou revue manuelle ; clé idempotente et historique sécurisent la reprise.

Un timeout permet-il de passer en mode hors ligne ou d’urgence ?

Non. Un timeout peut venir du réseau ou du connecteur et n’autorise aucun mode officiel. Vérifiez les communications et suivez la procédure approuvée pour offline24, indisponibilité annoncée, urgence ou défaillance totale.

Réglementation, formats et termes clés

Commission européenneEN 16931Directive 2014/55/UEfacture électronique structuréeSurveillance de l’API KSeF et procédure de gestion des incidentsPologne

À lire aussi

Sources officielles

Nous privilégions les sources gouvernementales et européennes officielles lorsque disponibles, avec des dates de vérification visibles.