KSeF API: send e-invoices to Poland's KSeF with one POST

What the KSeF API is

KSeF (Krajowy System e-Faktur) is Poland's national e-invoicing system, run by the Ministry of Finance. Every structured invoice is an FA(3) XML document that has to be submitted to KSeF, where it receives a unique KSeF number and an official receipt, the UPO.

The official KSeF 2.0 API (https://api.ksef.mf.gov.pl/v2) is a low-level REST interface. Integrating it directly means building all of this yourself:

• a challenge-based login with a KSeF token or certificate, with the token encrypted using the Ministry's RSA-OAEP public key;
• access and refresh tokens, and per-session AES keys to encrypt each invoice;
• generating FA(3) XML that passes the official XSD, down to totals and VAT annotations;
• polling the session and invoice status until KSeF decides, then fetching the UPO;
• separate hosts, keys and tokens for the TEST, DEMO and PRODUCTION environments.

One POST instead of a KSeF integration

Notaly is an e-invoicing API for Poland that does that work for you. You send the invoice as JSON; Notaly generates FA(3) XML, validates it, submits it to KSeF, follows the status and tells you the result.

curl -X POST https://api.getnotaly.com/invoices \
  -H "Authorization: Bearer $NOTALY_API_KEY" \
  -H "Idempotency-Key: FV-2026-10-001" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "FV/2026/10/001",
    "issueDate": "2026-10-12",
    "currency": "PLN",
    "seller": { "nip": "2745013933", "name": "Example Sp. z o.o.",
                "address": { "line1": "ul. Testowa 1, 00-001 Warszawa", "country": "PL" } },
    "buyer":  { "nip": "1234563218", "name": "Test Customer S.A.",
                "address": { "line1": "ul. Probna 2, 30-001 Kraków", "country": "PL" } },
    "items": [ { "name": "SaaS subscription", "quantity": 1, "unitNetPrice": 1000, "vatRate": 23 } ]
  }'

The response is the invoice object with "status": "submitted" and a KSeF reference number. When KSeF decides, you receive a signed invoice.accepted webhook with the KSeF number, the UPO and a PDF link. Full details are in the API reference.

Invoice lifecycle

An invoice moves through four API statuses. KSeF also has an internal processing phase, but the API keeps the invoice as submitted until KSeF decides.

KSeF environments

KSeF has three separate environments. Tokens, keys and invoices from one never work in another.

Today the whole Notaly flow runs on KSeF TEST. Production follows after tax and legal validation; paid plans then use your own company's KSeF token.

Who has to use KSeF

KSeF became mandatory for B2B invoices in Poland in 2026: from 1 February 2026 for companies whose 2024 sales exceeded PLN 200 million, and from 1 April 2026 for the other VAT taxpayers. The smallest businesses got a later start date. If you build invoicing, ERP, e-commerce or billing software that serves Polish companies, your product needs to issue invoices through KSeF.

Notaly issues and tracks e-invoices. It is not an accounting service and does not calculate taxes.

Pricing

Create a sandbox account on the home page. Your API key appears in seconds, and no credit card is needed.