The KSeF API: a developer's orientation

If you're about to build against KSeF, this is the map of the moving parts. It won't replace the Ministry of Finance's official specification (always the source of truth, and it evolves), but it will orient you before you write a line of code.

1. Pick the environment

• Test / Demo — behave like production, no legal effect. Do all development

and QA here.

• Production — real, legally-issued invoices.

Keep credentials and base URLs strictly separated per environment.

2. Authenticate

Establish who is acting for the taxpayer:

• Qualified signature / seal or trusted profile for interactive use.
• Authorisation token for automated software (the common server-to-server

path).

Authentication yields a session token you use for subsequent calls. Scope and rotate credentials carefully — this token can issue legally binding invoices.

3. Open a session

• Interactive session — for real-time, one-at-a-time submission.
• Batch session — submit a package of invoices for volume processing.

4. Submit an FA_VAT invoice

Build the invoice as FA_VAT XML (schema FA(2), moving to FA(3)), validate it locally against the schema, then submit within the session. KSeF validates again and, on success, assigns a KSeF number.

5. Retrieve the UPO and status

• Fetch the UPO — your official proof of receipt.
• Query invoice/session status to confirm acceptance or read rejection

reasons.

• Persist the KSeF number + UPO + submitted XML on your side.

6. Fetch received invoices

KSeF is also how you receive: query for invoices addressed to your NIP (tax ID) and pull them in. Your integration should reconcile these into your accounting.

Practical concerns

□ Idempotency — never double-issue on a retry
□ Schema versioning — plan for FA(2) → FA(3)
□ Error handling — map KSeF rejection codes to actionable messages
□ Token lifecycle — obtain, use, refresh, revoke safely
□ Storage — KSeF number, UPO, raw XML, status history
□ Separation — test vs production credentials never mixed

A note on scope

The KSeF API is for domestic Polish invoicing. Cross-border EU invoices use a different channel — Peppol / EN 16931 — with its own API surface (Access Point). If your product serves exporters, you'll integrate both.

Where Eurobillr fits

Eurobillr's own e-invoicing integration targets the EU/Peppol side (via the Recommand API) — the same session-based "authenticate → build structured document → submit → confirm → fetch inbound" pattern, for Belgium, France and other EU destinations. KSeF is Poland's national API; for domestic PL you integrate with KSeF directly or through a KSeF provider. Building for both? We're glad to compare notes.

Related: KSeF integration · KSeF software.