De PSB kent twee KSeF-hooks: een outbound hook voor uitgaande facturen (verkopende partij / Podmiot1) en een inbound hook voor inkomende facturen (kopende partij / Podmiot2). Beide automatiseren de uitwisseling met het Krajowy System e-Faktur (KSeF), het Poolse nationale e-facturatiesysteem. De outbound hook staat hieronder als eerste beschreven; de inbound hook staat onderaan deze pagina.

De KSeF outbound hook automatiseert het registreren van uitgaande facturen bij KSeF. Facturen worden vanuit Peppol BIS Billing 3.0-formaat getransformeerd naar het Poolse FA(3)-formaat en als batch geregistreerd. Na succesvolle verwerking levert de hook het UPO (Urzędowe Poswiadczenie Odbioru, het officiële ontvangstbewijs) en een PDF-bewijs terug via het PSB-platform.

De hook ondersteunt zowel een online flow (directe registratie) als een offline flow (wanneer KSeF tijdelijk niet bereikbaar is, bijvoorbeeld tijdens de dagelijkse cutoff). In de offline flow wordt een offline PDF gegenereerd op basis van het offline certificaat.

• Een geldig online certificaat voor KSeF
• Een geldig offline certificaat voor KSeF
• De bijbehorende wachtwoorden van beide certificaten
• De hook moet geactiveerd zijn in de configuratie

Na ontvangst van een factuurnotificatie doorloopt de hook zeven stappen:

Wanneer KSeF niet bereikbaar is (dagelijkse cutoff of storing), start automatisch de offline flow: er wordt een offline PDF gegenereerd via het offline certificaat, waarna de factuur via het reguliere kanaal wordt verstuurd.

Registreer de hook via de Hooks API:

{
  "id": "ksef-sender",
  "action": "ksef",
  "name": "KSeF Hook Sender",
  "topics": [
    "ClearInvoiceBatched"
  ],
  "output": [
    {
      "when": "200",
      "topic": "SendInvoice"
    },
    {
      "when": "410",
      "topic": "SendInvoice"
    }
  ],
  "init": {
    "onlineCertificate": "{{pad-naar-online-certificaat}}",
    "onlineCertificatePassword": "{{wachtwoord}}",
    "offlineCertificate": "{{pad-naar-offline-certificaat}}",
    "offlineCertificatePassword": "{{wachtwoord}}"
  },
  "isActive": true
}

Belangrijk: Alle vier de certificaatvelden zijn verplicht. Het online certificaat is nodig voor authenticatie tijdens de online flow. Het offline certificaat is nodig voor het genereren van QR-codes in de PDF, zowel bij online als bij offline verwerking.

Bij statuscode 410 start de PSB automatisch de offline flow. De factuur wordt dan lokaal verwerkt met het offline certificaat en verstuurd zodra KSeF weer beschikbaar is. Bij 429 plant de PSB een automatische retry in.

De KSeF kent een dagelijkse cutoff-periode waarin het systeem niet beschikbaar is voor batchregistratie. De PSB detecteert dit automatisch (statuscode 410) en schakelt over naar de offline flow:

• Online: factuur wordt direct geregistreerd bij KSeF, UPO wordt opgehaald en PDF met QR-codes wordt gegenereerd
• Offline: factuur wordt lokaal verwerkt, offline PDF met QR-codes wordt gegenereerd via het offline certificaat, en de factuur wordt via het reguliere kanaal verstuurd

Na terugkeer van KSeF worden offline verwerkte facturen alsnog geregistreerd en ontvangt de factuur statuscode 201 (InvoiceCleared).

De KSeF inbound hook verwerkt inkomende facturen voor de kopende partij (Podmiot2). De hook pollt periodiek KSeF op nieuwe facturen, haalt de factuur-XML op per KSeF-nummer en levert deze af via het PSB-platform.

Authenticatie richting KSeF verloopt uitsluitend via een online certificaat (.key + .crt + wachtwoord). De inbound flow kent geen offline-variant, in tegenstelling tot de outbound hook. Bij tijdelijke KSeF-onbereikbaarheid wordt de polling opnieuw geprobeerd conform de geconfigureerde retry-policy.

Wordt tijdens Fetch geen factuur gevonden, dan springt de hook direct door naar Complete: er wordt niets verwerkt of gepubliceerd.

• Een geldig online certificaat voor KSeF (.key + .crt) plus bijbehorend wachtwoord.
• De hook moet geactiveerd zijn in de configuratie.

De inbound hook wordt via TechSupport ingericht: certificaatverwerking is een techsupport-only procedure, niet self-service.

Meer weten over e-facturatie in Polen? Lees de landenpagina over de Poolse KSeF-verplichting.