ProductKnowledgeDevelopers
Platform Control
KSeF outbound hook: registering invoices with the Polish KSeF

Configure the KSeF outbound hook for automatic registration of invoices with the Polish e-invoicing system.

The KSeF outbound hook automates the registration of outgoing invoices with the Krajowy System e-Faktur (KSeF), the Polish national e-invoicing system. Invoices are transformed from Peppol BIS Billing 3.0 format to the Polish FA(3) format and registered as a batch. After successful processing, the hook returns the UPO (Urzędowe Poswiadczenie Odbioru, the official acknowledgement of receipt) and a PDF proof via the PSB platform.

The hook supports both an online flow (direct registration) and an offline flow (when KSeF is temporarily unavailable, for example during the daily cutoff). In the offline flow, an offline PDF is generated based on the offline certificate.

Prerequisites
  • A valid online certificate for KSeF
  • A valid offline certificate for KSeF
  • The corresponding passwords for both certificates
  • The hook must be activated in the configuration
Workflow

After receiving an invoice notification, the hook goes through seven steps:

StepActionDescription1UploadUploads the invoice package as a batch to KSeF (POST /v2/sessions/batch)2StatusPolls the batch status until processing is complete (GET /v2/sessions/{referenceNumber}/status)3RetrieveInvoicesRetrieves the processed invoice results per page4RetrieveUpoRetrieves the UPO document for the session5PrintGenerates a PDF per document based on UPO data and verification link, and registers it as an attachment6DispatchSends all buffered events in a batch to the Ingestor7FinalizeCleans up the state and closes the session

When KSeF is unavailable (daily cutoff or outage), the offline flow starts automatically: an offline PDF is generated via the offline certificate, after which the invoice is sent through the regular channel.

Configuration

Register the hook via the Hooks API:

{
  "id": "ksef-sender",
  "action": "ksef",
  "name": "KSeF Hook Sender",
  "topics": [
    "ClearInvoiceBatched"
  ],
  "output": [
    {
      "when": "200",
      "topic": "SendInvoice"
    },
    {
      "when": "410",
      "topic": "SendInvoice"
    }
  ],
  "init": {
    "onlineCertificate": "{{path-to-online-certificate}}",
    "onlineCertificatePassword": "{{password}}",
    "offlineCertificate": "{{path-to-offline-certificate}}",
    "offlineCertificatePassword": "{{password}}"
  },
  "isActive": true
}
Parameters
ParameterDescriptiononlineCertificatePath to the online certificate file for authentication with KSeF during the online flowonlineCertificatePasswordThe password for the online certificateofflineCertificatePath to the offline certificate file, used for generating QR codes in the PDF outputofflineCertificatePasswordThe password for the offline certificatetopicsThe topics the hook listens to. Use ClearInvoiceBatched for outgoing invoicesoutputDefines which topic is sent for a given status codeisActiveMust be set to true to activate the hook

Important: All four certificate fields are required. The online certificate is needed for authentication during the online flow. The offline certificate is needed for generating QR codes in the PDF, both during online and offline processing.

Status codes
CodeDescriptionOutput topic200Invoice successfully registered with KSeF (online)SendInvoice201Invoice successfully registered after offline processingInvoiceCleared410KSeF is offline; offline flow is startedSendInvoice429Temporarily unavailable; retry is automatically scheduledInvoiceClearedRetry500Internal server errorInvoiceClearedError

With status code 410, the PSB automatically starts the offline flow. The invoice is then processed locally with the offline certificate and sent once KSeF is available again. With 429, the PSB schedules an automatic retry.

Online vs. offline flow

KSeF has a daily cutoff period during which the system is unavailable for batch registration. The PSB detects this automatically (status code 410) and switches to the offline flow:

  • Online: the invoice is directly registered with KSeF, the UPO is retrieved and a PDF with QR codes is generated
  • Offline: the invoice is processed locally, an offline PDF with QR codes is generated via the offline certificate, and the invoice is sent through the regular channel

After KSeF returns, invoices processed offline are still registered and the invoice receives status code 201 (InvoiceCleared).

Frequently asked questions
Why are both an online and an offline certificate required in the init configuration?

The PSB uses the online certificate to authenticate with KSeF during the online registration flow. The offline certificate is needed for QR codes in the PDF output, both during online and offline processing. All four fields (both certificate paths and passwords) must therefore be filled in.

What does the PSB do with status code 410 or 429 from KSeF?

With 410, KSeF is offline (for example during the cutoff period); the PSB starts the offline flow with an offline PDF and then sends via the regular channel. With 429, there is temporarily no capacity; the PSB automatically schedules a retry on InvoiceClearedRetry.

Which topic should I set on the hook for outgoing invoices to KSeF?

Use ClearInvoiceBatched in topics so that the hook listens to the correct batch notifications. The output object maps HTTP status codes to follow-up topics such as SendInvoice or InvoiceCleared, depending on the registration result.

Want to learn more about e-invoicing in Poland? Read the country page on the Polish KSeF obligation.

View the API documentation

PreviousMailfrom hooks
NextConfigure webhooks