La PSB dispone di due hook KSeF: un hook outbound per le fatture in uscita (parte venditrice / Podmiot1) e un hook inbound per le fatture in entrata (parte acquirente / Podmiot2). Entrambi automatizzano lo scambio con il Krajowy System e-Faktur (KSeF), il sistema nazionale di fatturazione elettronica polacco. L'hook outbound è descritto per primo di seguito; l'hook inbound si trova in fondo a questa pagina.

L'hook outbound KSeF automatizza la registrazione delle fatture in uscita presso KSeF. Le fatture vengono trasformate dal formato Peppol BIS Billing 3.0 / UBL (internamente anche BisV3) al formato polacco FA(3) e registrate come batch. Il cliente può anche fornire direttamente il FA(3); in tal caso il passaggio di trasformazione viene saltato. Dopo l'elaborazione avvenuta con successo, l'hook restituisce il UPO (Urzędowe Poswiadczenie Odbioru, la ricevuta ufficiale) e una prova in PDF tramite la piattaforma PSB.

Per test e collaudo, l'amministrazione polacca offre due ambienti oltre alla produzione:

L'hook supporta sia un flusso online (registrazione diretta) sia un flusso offline (quando KSeF è temporaneamente non disponibile, ad esempio durante il cutoff giornaliero). Nel flusso offline viene generato un PDF offline basato sul certificato offline.

• Un certificato online valido per KSeF (.key + .crt; autenticazione durante il flusso online)
• Un certificato offline valido per KSeF (.key + .crt; codici QR nell'output PDF, sia in elaborazione online che offline)
• Le password corrispondenti di entrambi i certificati
• L'hook deve essere attivato nella configurazione

Dopo la ricezione di una notifica di fattura, l'hook esegue sette passaggi:

Quando KSeF non è disponibile (cutoff giornaliero o guasto), il flusso offline si avvia automaticamente: viene generato un PDF offline tramite il certificato offline, dopodiché la fattura viene inviata attraverso il canale regolare.

Registri l'hook tramite 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": "{{percorso-certificato-online}}",
    "onlineCertificatePassword": "{{password}}",
    "offlineCertificate": "{{percorso-certificato-offline}}",
    "offlineCertificatePassword": "{{password}}"
  },
  "isActive": true
}

Importante: Tutti e quattro i campi del certificato sono obbligatori. Il certificato online è necessario per l'autenticazione durante il flusso online. Il certificato offline è necessario per la generazione dei codici QR nel PDF, sia durante l'elaborazione online che offline.

Con il codice di stato 410, la PSB avvia automaticamente il flusso offline. La fattura viene quindi elaborata localmente con il certificato offline e inviata non appena KSeF è nuovamente disponibile. Con 429, la PSB pianifica un nuovo tentativo automatico.

KSeF ha un periodo di cutoff giornaliero durante il quale il sistema non è disponibile per la registrazione in batch. Dopo circa le 23:00 ora locale polacca, il flusso offline si attiva non appena KSeF non è raggiungibile (codice di stato 410):

• Online: la fattura viene registrata direttamente presso KSeF, il UPO viene recuperato e viene generato un PDF con codici QR
• Offline: la fattura viene elaborata localmente, un PDF offline con un codice QR offline viene generato tramite il certificato offline. La fattura viene inviata al destinatario senza essere ancora stata registrata presso KSeF.

Dopo il ritorno di KSeF, le fatture elaborate offline vengono comunque registrate successivamente e la fattura riceve il codice di stato 201 (InvoiceCleared). La fattura non viene reinviata al destinatario; il codice QR offline inviato in precedenza rimanda, dopo questa registrazione successiva, alla registrazione KSeF confermata.

Dopo la clearance online, KSeF restituisce un numero di riferimento. Questo numero compare nel UPO e nei dettagli del webhook in uscita, ad esempio:

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

Conservi il numero di riferimento nell'ERP mittente come prova di registrazione presso KSeF.

Per volumi elevati: posizioni un hook batch prima dell'hook KSeF in modo che le fatture vengano inviate periodicamente (ad esempio ogni 15 secondi fino a 1 minuto, o al massimo 100 alla volta) come batch a KSeF. In questo modo l'integrazione raggiunge meno rapidamente i rate limit di KSeF. Schema di topic preferito: ClearInvoice → batch → ClearInvoiceBatched → hook KSeF. È inoltre necessario un hook separato che pubblichi le fatture in uscita sul topic ClearInvoice (a seconda del flusso).

Esempio di hook batch (preferito; parametri da adattare per cliente):

{
  "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
}

Forma breve dell'azione (stesso target FA(3); period ad esempio 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

Alcuni clienti non possono inviare fatture con topic ClearInvoice (ad esempio Business Central). Adatti allora l'hook batch affinché ascolti SendInvoice e continui comunque a pubblicare 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
}

L'hook inbound KSeF elabora le fatture in entrata per la parte acquirente (Podmiot2). L'hook interroga periodicamente KSeF per nuove fatture, recupera l'XML della fattura per numero KSeF e lo consegna tramite la piattaforma PSB.

L'autenticazione verso KSeF avviene esclusivamente tramite un certificato online (.key + .crt + password). Il flusso inbound non prevede una variante offline, a differenza dell'hook outbound. In caso di temporanea irraggiungibilità di KSeF, il polling viene ritentato secondo la retry-policy configurata.

Se durante Fetch non viene trovata alcuna fattura, l'hook passa direttamente a Complete: non viene elaborato né pubblicato nulla.

• Un certificato online valido per KSeF (.key + .crt) più la password corrispondente.
• L'hook deve essere attivato nella configurazione.
• I campi init onlineCertificate e onlineCertificatePassword sono obbligatori (nessun campo certificato offline).

L'hook inbound viene configurato tramite TechSupport: la gestione dei certificati è una procedura riservata al supporto tecnico, non self-service.

Il parametro action determina la finestra temporale entro cui l'hook guarda indietro: ksef:inbound?lookbackWindow=<finestra>. In init è presente solo il certificato online.

Standard (pubblica sul topic ReceiveInvoice):

{
  "id": "ksef-inbound",
  "action": "ksef:inbound?lookbackWindow=08:00:00",
  "name": "KSeF Hook Inbound",
  "publishTopics": ["ReceiveInvoice"],
  "init": {
    "onlineCertificate": "{{percorso-certificato-online}}",
    "onlineCertificatePassword": "{{password}}"
  },
  "isActive": true
}

Dopo l'hook inbound deve sempre seguire un hook successivo che elabora ulteriormente la fattura ricevuta.

Variante piattaforma Collabrr: sulla piattaforma Collabrr, l'hook è in ascolto nel tenant con publishTopics: ["InvoiceReceived"]. L'organizzazione deve essere registrata per la ricezione Peppol sulla piattaforma. Esempio di action: ksef:inbound?lookbackWindow=08.00:00:00.

Il parametro lookbackWindow determina la finestra temporale entro cui l'hook guarda indietro durante il polling/la creazione:

• In ore, ad esempio "08:00:00"
• In giorni, ad esempio "60.00:00:00"

KSeF limita lo sguardo indietro a massimo 3 mesi. Il superamento genera un errore:

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

Esiste inoltre un limite di rate delle richieste verso KSeF. Ne tenga conto quando attiva più entità con un lookbackWindow (ampio).

Desidera saperne di più sulla fatturazione elettronica in Polonia? Consulti la pagina paese sull'obbligo KSeF polacco.