API KSeF: wysyłaj e-faktury do KSeF jednym żądaniem POST

Czym jest API KSeF

KSeF (Krajowy System e-Faktur) to krajowy system e-fakturowania prowadzony przez Ministerstwo Finansów. Każda faktura ustrukturyzowana to dokument XML FA(3), który trzeba wysłać do KSeF. Tam otrzymuje unikalny numer KSeF i urzędowe poświadczenie odbioru, czyli UPO.

Oficjalne API KSeF 2.0 (https://api.ksef.mf.gov.pl/v2) to niskopoziomowy interfejs REST. Bezpośrednia integracja oznacza samodzielną obsługę:

• logowania przez challenge z tokenem lub certyfikatem KSeF, z tokenem szyfrowanym kluczem publicznym MF (RSA-OAEP);
• tokenów dostępowych i odświeżających oraz kluczy AES sesji do szyfrowania każdej faktury;
• generowania XML FA(3) zgodnego z oficjalnym XSD, łącznie z sumami i adnotacjami VAT;
• odpytywania o status sesji i faktury aż do decyzji KSeF oraz pobierania UPO;
• osobnych hostów, kluczy i tokenów dla środowisk TEST, DEMO i PRODUKCYJNEGO.

Jedno POST zamiast integracji z KSeF

Notaly to API do e-faktur w Polsce, które robi to za Ciebie. Wysyłasz fakturę jako JSON, a Notaly generuje XML FA(3), waliduje go, wysyła do KSeF, śledzi status i informuje o wyniku.

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": "Przykład Sp. z o.o.",
                "address": { "line1": "ul. Testowa 1, 00-001 Warszawa", "country": "PL" } },
    "buyer":  { "nip": "1234563218", "name": "Klient Testowy S.A.",
                "address": { "line1": "ul. Próbna 2, 30-001 Kraków", "country": "PL" } },
    "items": [ { "name": "Abonament SaaS", "quantity": 1, "unitNetPrice": 1000, "vatRate": 23 } ]
  }'

Odpowiedź to obiekt faktury ze statusem "submitted" i numerem referencyjnym KSeF. Gdy KSeF podejmie decyzję, otrzymasz podpisany webhook invoice.accepted z numerem KSeF, UPO i linkiem do PDF. Szczegóły znajdziesz w dokumentacji API.

Cykl życia faktury

Faktura przechodzi przez cztery statusy API. KSeF ma też wewnętrzną fazę przetwarzania, ale API utrzymuje wtedy status submitted, dopóki KSeF nie zdecyduje.

Środowiska KSeF

KSeF ma trzy rozdzielone środowiska. Tokeny, klucze i faktury z jednego nie działają w innym.

Dziś cały proces Notaly działa w KSeF TEST. Produkcja zostanie uruchomiona po weryfikacji podatkowej i prawnej; plany płatne będą wtedy korzystać z tokena KSeF Twojej firmy.

Kogo dotyczy KSeF

KSeF stał się obowiązkowy dla faktur B2B w Polsce w 2026 roku: od 1 lutego 2026 dla firm, których sprzedaż w 2024 roku przekroczyła 200 mln zł, a od 1 kwietnia 2026 dla pozostałych podatników VAT. Najmniejsze firmy otrzymały późniejszy termin. Jeśli tworzysz oprogramowanie do fakturowania, ERP, e-commerce lub billingu dla polskich firm, Twój produkt musi wystawiać faktury przez KSeF.

Notaly wystawia i śledzi e-faktury. Nie świadczy usług księgowych ani nie nalicza podatków.

Cennik

Załóż konto sandbox na stronie głównej. Klucz API dostajesz w kilka sekund, bez karty płatniczej.