ProductKennisDevelopers
Platform Control
KSeF outbound hook: facturen registreren bij het Poolse KSeF

De KSeF outbound hook configureren voor automatische registratie van facturen bij het Poolse e-facturatiesysteem.

De KSeF outbound hook automatiseert het registreren van uitgaande facturen bij het Krajowy System e-Faktur (KSeF), het Poolse nationale e-facturatiesysteem. 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.

Voorwaarden
  • 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
Workflow

Na ontvangst van een factuurnotificatie doorloopt de hook zeven stappen:

StapActieBeschrijving1UploadUploadt het factuurpakket als batch naar KSeF (POST /v2/sessions/batch)2StatusPollt de batchstatus totdat verwerking voltooid is (GET /v2/sessions/{referenceNumber}/status)3RetrieveInvoicesHaalt de verwerkte factuurresultaten op per pagina4RetrieveUpoHaalt het UPO-document op voor de sessie5PrintGenereert per document een PDF op basis van UPO-data en verificatielink, en registreert deze als bijlage6DispatchVerstuurt alle gebufferde events in een batch naar de Ingestor7FinalizeRuimt de state op en sluit de sessie af

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.

Configuratie

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
}
Parameters
ParameterBeschrijvingonlineCertificatePad naar het online certificaatbestand voor authenticatie bij KSeF tijdens de online flowonlineCertificatePasswordHet wachtwoord bij het online certificaatofflineCertificatePad naar het offline certificaatbestand, gebruikt voor het genereren van QR-codes in de PDF-outputofflineCertificatePasswordHet wachtwoord bij het offline certificaattopicsDe topics waarop de hook luistert. Gebruik ClearInvoiceBatched voor uitgaande facturenoutputDefinieert welke topic wordt verstuurd bij een bepaalde statuscodeisActiveMoet op true staan om de hook te activeren

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.

Statuscodes
CodeBeschrijvingOutput topic200Factuur succesvol geregistreerd bij KSeF (online)SendInvoice201Factuur succesvol geregistreerd na offline verwerkingInvoiceCleared410KSeF is offline; offline flow wordt gestartSendInvoice429Tijdelijk niet beschikbaar; retry wordt automatisch geplandInvoiceClearedRetry500Interne serverfoutInvoiceClearedError

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.

Online vs. offline flow

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).

Veelgestelde vragen
Waarom zijn zowel een online als een offline certificaat verplicht in de init-configuratie?

Het online certificaat gebruikt de PSB om zich bij KSeF te authenticeren tijdens de online registratieflow. Het offline certificaat is nodig voor QR-codes in de PDF-output, zowel bij online als bij offline verwerking. Alle vier de velden (beide certificaatpaden en wachtwoorden) moeten daarom gevuld zijn.

Wat doet de PSB bij statuscode 410 of 429 van KSeF?

Bij 410 is KSeF offline (bijvoorbeeld cutoff); de PSB start de offline flow met een offline PDF en stuurt daarna via het reguliere kanaal. Bij 429 is er tijdelijk geen capaciteit; de PSB plant automatisch een retry in op InvoiceClearedRetry.

Welk topic moet ik op de hook zetten voor uitgaande facturen naar KSeF?

Gebruik ClearInvoiceBatched in topics zodat de hook op de juiste batchnotificaties luistert. Het output-object koppelt HTTP-statuscodes aan vervolgtopics zoals SendInvoice of InvoiceCleared, afhankelijk van het registratieresultaat.

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

Bekijk de API-documentatie

Gerelateerd
PreviousMailfrom hooks
NextFactuur verzenden