La PSB dispose de deux hooks KSeF : un hook outbound pour les factures sortantes (partie vendeuse / Podmiot1) et un hook inbound pour les factures entrantes (partie acheteuse / Podmiot2). Les deux automatisent l'échange avec le Krajowy System e-Faktur (KSeF), le système national de facturation électronique polonais. Le hook outbound est décrit en premier ci-dessous ; le hook inbound se trouve en bas de cette page.

Le hook outbound KSeF automatise l'enregistrement des factures sortantes auprès de KSeF. Les factures sont transformées du format Peppol BIS Billing 3.0 / UBL (également appelé BisV3 en interne) au format polonais FA(3) et enregistrées en batch. Le client peut aussi fournir lui-même le FA(3) ; dans ce cas, l'étape de transformation est ignorée. Après traitement réussi, le hook renvoie le UPO (Urzędowe Poswiadczenie Odbioru, l'accusé de réception officiel) et une preuve PDF via la plateforme PSB.

Pour les tests et la recette, l'administration polonaise propose deux environnements en plus de la production :

Le hook prend en charge un flux en ligne (enregistrement direct) ainsi qu'un flux hors ligne (lorsque KSeF est temporairement indisponible, par exemple pendant la coupure quotidienne). Dans le flux hors ligne, un PDF hors ligne est généré sur la base du certificat hors ligne.

• Un certificat en ligne valide pour KSeF (.key + .crt ; authentification pendant le flux en ligne)
• Un certificat hors ligne valide pour KSeF (.key + .crt ; codes QR dans le PDF de sortie, tant en traitement en ligne que hors ligne)
• Les mots de passe correspondants pour les deux certificats
• Le hook doit être activé dans la configuration

Après réception d'une notification de facture, le hook passe par sept étapes :

Lorsque KSeF n'est pas disponible (coupure quotidienne ou panne), le flux hors ligne démarre automatiquement : un PDF hors ligne est généré via le certificat hors ligne, puis la facture est envoyée par le canal régulier.

Enregistrez le hook via l'API Hooks :

{
  "id": "ksef-sender",
  "action": "ksef",
  "name": "KSeF Hook Sender",
  "topics": [
    "ClearInvoiceBatched"
  ],
  "output": [
    {
      "when": "200",
      "topic": "SendInvoice"
    },
    {
      "when": "410",
      "topic": "SendInvoice"
    }
  ],
  "init": {
    "onlineCertificate": "{{chemin-vers-certificat-en-ligne}}",
    "onlineCertificatePassword": "{{mot-de-passe}}",
    "offlineCertificate": "{{chemin-vers-certificat-hors-ligne}}",
    "offlineCertificatePassword": "{{mot-de-passe}}"
  },
  "isActive": true
}

Important : Les quatre champs de certificat sont obligatoires. Le certificat en ligne est nécessaire pour l'authentification pendant le flux en ligne. Le certificat hors ligne est nécessaire pour la génération des codes QR dans le PDF, tant pour le traitement en ligne que hors ligne.

Avec le code de statut 410, la PSB lance automatiquement le flux hors ligne. La facture est alors traitée localement avec le certificat hors ligne et envoyée dès que KSeF est de nouveau disponible. Avec 429, la PSB planifie une nouvelle tentative automatique.

KSeF a une période de coupure quotidienne pendant laquelle le système n'est pas disponible pour l'enregistrement en batch. Après environ 23h00 heure locale polonaise, le flux hors ligne se déclenche dès que KSeF est injoignable (code de statut 410) :

• En ligne : la facture est directement enregistrée auprès de KSeF, le UPO est récupéré et un PDF avec codes QR est généré
• Hors ligne : la facture est traitée localement, un PDF hors ligne avec un code QR hors ligne est généré via le certificat hors ligne. La facture est envoyée au destinataire sans avoir encore été enregistrée auprès de KSeF.

Après le retour de KSeF, les factures traitées hors ligne sont enregistrées a posteriori et la facture reçoit le code de statut 201 (InvoiceCleared). La facture n'est pas renvoyée au destinataire ; le code QR hors ligne envoyé précédemment pointe, après cet enregistrement tardif, vers l'enregistrement KSeF confirmé.

Après la clearance en ligne, KSeF renvoie un numéro de référence. Ce numéro figure dans le UPO et dans les détails du webhook sortant, par exemple :

"details": {
  "clearanceReference": "234563218-20260220-50683A000001-11",
  "clearanceSystem": "KSeF"
}

Conservez le numéro de référence dans l'ERP émetteur comme preuve d'enregistrement auprès de KSeF.

Pour des volumes importants : placez un hook de batch avant le hook KSeF afin que les factures partent périodiquement (par exemple toutes les 15 secondes à 1 minute, ou au maximum 100 à la fois) en batch vers KSeF. L'intégration atteint ainsi moins vite les limites de débit de KSeF. Schéma de topic privilégié : ClearInvoice → batch → ClearInvoiceBatched → hook KSeF. Un hook distinct est en outre nécessaire pour publier les factures sortantes sur le topic ClearInvoice (selon le flux).

Exemple de hook de batch (préféré ; paramètres à ajuster par client) :

{
  "id": "batchClearInvoice",
  "name": "Batch Invoices for KSeF",
  "action": "batch://zip?period=00:01:00&maxBatchSize=100&excludePrimaryAttachment=false&includeAdditionalAttachments=true&hashAlgorithm=sha256&includeRefToMetaAttributes=true&targetDocumentTypeId=econnect-docid%3A%3Ahttp%3A%2F%2Fcrd.gov.pl%2Fwzor%2F2025%2F06%2F25%2F13775%3A%3AFaktura%23%23ksef%3A%3A3.0",
  "topics": ["ClearInvoice"],
  "isActive": true
}

Forme d'action courte (même cible FA(3) ; period par exemple 00:00:15) :

batch://zip?period=00:00:15&maxBatchSize=100&excludePrimaryAttachment=false&includeAdditionalAttachments=true&hashAlgorithm=sha256&includeRefToMetaAttributes=true&targetDocumentTypeId=econnect-docid%3A%3Ahttp%3A%2F%2Fcrd.gov.pl%2Fwzor%2F2025%2F06%2F25%2F13775%3A%3AFaktura%23%23ksef%3A%3A3.0

Certains clients ne peuvent pas envoyer de factures avec le topic ClearInvoice (par exemple Business Central). Adaptez alors le hook de batch pour qu'il écoute SendInvoice tout en publiant ClearInvoiceBatched :

{
  "id": "batchClearInvoice",
  "name": "Batch Invoices for KSeF",
  "action": "batch://zip?period=00:01:00&maxBatchSize=100&excludePrimaryAttachment=false&includeAdditionalAttachments=true&hashAlgorithm=sha256&includeRefToMetaAttributes=true&targetDocumentTypeId=econnect-docid%3A%3Ahttp%3A%2F%2Fcrd.gov.pl%2Fwzor%2F2025%2F06%2F25%2F13775%3A%3AFaktura%23%23ksef%3A%3A3.0",
  "topics": ["SendInvoice"],
  "output": [
    { "when": "200", "topic": "ClearInvoiceBatched" },
    { "when": "500", "topic": "ClearInvoiceBatchedError" },
    { "when": "429", "topic": "ClearInvoiceBatchedRetry" }
  ],
  "isActive": true
}

Le hook inbound KSeF traite les factures entrantes pour la partie acheteuse (Podmiot2). Le hook interroge périodiquement KSeF pour les nouvelles factures, récupère le XML de la facture par numéro KSeF et le livre via la plateforme PSB.

L'authentification auprès de KSeF passe exclusivement par un certificat en ligne (.key + .crt + mot de passe). Le flux inbound ne dispose d'aucune variante hors ligne, contrairement au hook outbound. En cas d'indisponibilité temporaire de KSeF, l'interrogation est retentée selon la politique de retry configurée.

Si aucune facture n'est trouvée pendant Fetch, le hook passe directement à Complete : rien n'est traité ni publié.

• Un certificat en ligne valide pour KSeF (.key + .crt) ainsi que le mot de passe correspondant.
• Le hook doit être activé dans la configuration.
• Les champs init onlineCertificate et onlineCertificatePassword sont obligatoires (pas de champs de certificat hors ligne).

Le hook inbound est mis en place via TechSupport : le traitement des certificats est une procédure réservée au support technique, non en self-service.

Le paramètre d'action détermine la fenêtre temporelle sur laquelle le hook revient en arrière : ksef:inbound?lookbackWindow=<fenêtre>. Le bloc init ne contient que le certificat en ligne.

Standard (publie sur le topic ReceiveInvoice) :

{
  "id": "ksef-inbound",
  "action": "ksef:inbound?lookbackWindow=08:00:00",
  "name": "KSeF Hook Inbound",
  "publishTopics": ["ReceiveInvoice"],
  "init": {
    "onlineCertificate": "{{chemin-vers-certificat-en-ligne}}",
    "onlineCertificatePassword": "{{mot-de-passe}}"
  },
  "isActive": true
}

Le hook inbound doit toujours être suivi d'un hook de suivi qui traite ensuite la facture reçue.

Variante plateforme Collabrr : sur la plateforme Collabrr, le hook écoute dans le tenant avec publishTopics: ["InvoiceReceived"]. L'organisation doit être enregistrée pour la réception Peppol sur la plateforme. Exemple d'action : ksef:inbound?lookbackWindow=08.00:00:00.

Le paramètre lookbackWindow détermine la fenêtre temporelle sur laquelle le hook revient en arrière lors de l'interrogation/création :

• En heures, par exemple "08:00:00"
• En jours, par exemple "60.00:00:00"

KSeF limite le retour en arrière à 3 mois maximum. Un dépassement entraîne une erreur :

21405: Błąd walidacji danych wejściowych. - 'dateRange' must not exceed 3 months.

Il existe en outre une limite de débit de requêtes vers KSeF. Tenez-en compte lors de l'activation de plusieurs entités avec un lookbackWindow (important).

Vous souhaitez en savoir plus sur la facturation électronique en Pologne ? Consultez la page pays sur l'obligation KSeF polonaise.