KSeF API wysyłanie faktur
Co musisz wiedzieć
Krajowy System e-Faktur (KSeF) jest centralnym systemem administracji skarbowej do wystawiania i otrzymywania faktur ustrukturyzowanych w formacie XML.
Na tej stronie znajdziesz uporządkowane informacje dotyczące tematu: KSeF API wysyłanie faktur. Opis koncentruje się na aktualnych przepisach oraz komunikatach Ministerstwa Finansów.
Instrukcja krok po kroku
1. Uwierzytelnij się i uzyskaj accessToken
Wykonaj proces autoryzacji: pobierz challenge (POST /api/v2/auth/challenge), podpisz AuthTokenRequest, uzyskaj token JWT. accessToken jest wymagany do wszystkich operacji wysyłki.
2. Otwórz sesję wysyłki
Wygeneruj klucz symetryczny AES-256. Zaszyfruj go kluczem publicznym KSeF (RSA-OAEP). Otwórz sesję interaktywną (POST /api/v2/sessions/online) lub wsadową (/sessions/batch) podając formCode (FA2 lub FA3).
3. Przygotuj fakturę XML
Utwórz fakturę zgodną ze schematem XSD: FA(2) do 31.01.2026 lub FA(3) od 01.02.2026. Plik musi być kodowany UTF-8 bez BOM. Zwaliduj strukturę przed wysyłką.
4. Zaszyfruj i wyślij fakturę
Zaszyfruj fakturę algorytmem AES-256-CBC z dopełnieniem PKCS#7. Oblicz skróty SHA przed i po szyfrowaniu. Wyślij do endpointu POST /api/v2/sessions/online/{ref}/invoices.
5. Sprawdź status i pobierz UPO
Sprawdzaj status wysłanej faktury przez GET /api/v2/invoices/{id}/status. Po pomyślnym przetworzeniu faktura otrzymuje numer KSeF. Zamknij sesję i pobierz zbiorcze UPO.
Najczęstsze problemy i rozwiązania
Faktura została odrzucona – błąd walidacji XSD
Sprawdź, czy faktura jest zgodna z aktualnym schematem (FA2 do 31.01.2026, FA3 od 01.02.2026). Użyj walidatora XML przed wysłaniem. Zweryfikuj wszystkie wymagane pola i formaty dat.
Przekroczony limit rozmiaru pliku
Maksymalny rozmiar faktury to 1 MB bez załączników lub 3 MB z załącznikami. Zoptymalizuj zawartość faktury lub podziel na mniejsze dokumenty.
Nie otrzymuję numeru KSeF po wysłaniu
Sprawdź status faktury przez dedykowany endpoint. Faktura może być w trakcie przetwarzania. Jeśli status to błąd, sprawdź szczegóły i popraw fakturę.
Wymagania formatu faktury
Faktura musi być w formacie XML zgodnym ze schematem XSD: FA(2) do 31 stycznia 2026 r., FA(3) od 1 lutego 2026 r. Plik musi być kodowany UTF-8 bez znaku BOM. Maksymalny rozmiar: 1 MB bez załączników, 3 MB z załącznikami.
Szyfrowanie w API 2.0
W API KSeF 2.0 wszystkie faktury muszą być zaszyfrowane. Algorytm: AES-256-CBC z dopełnieniem PKCS#7. Klucz symetryczny jest generowany dla sesji i szyfrowany algorytmem RSA-OAEP (SHA-256) przy użyciu klucza publicznego KSeF.
Tryb interaktywny vs wsadowy
Tryb interaktywny (online) służy do wysyłki pojedynczych faktur z natychmiastową odpowiedzią. Tryb wsadowy (batch) pozwala na wysyłkę paczki faktur. W API 2.0 błędy nie blokują całej paczki – każda faktura jest przetwarzana niezależnie.
Obsługa błędów
Błędy walidacji zwracane są z kodem błędu i opisem. Najczęstsze przyczyny: niezgodność ze schematem XSD, brakujące pola obowiązkowe, nieprawidłowe formaty dat, przekroczony limit rozmiaru. Popraw wskazane problemy i wyślij ponownie.
FAQ
Jak wysłać fakturę przez API KSeF?
Fakturę wysyłasz przez endpoint POST /invoices, przesyłając plik XML zgodny ze strukturą logiczną FA(2) lub FA(3). Przed wysłaniem upewnij się, że masz aktywną sesję autoryzacyjną i token JWT.
Jaki format pliku jest wymagany do wysłania faktury?
Faktura musi być w formacie XML zgodnym ze schematem XSD struktury FA(2) do 31 stycznia 2026 lub FA(3) od 1 lutego 2026. Plik nie może przekraczać 1 MB bez załączników lub 3 MB z załącznikami.
Jak sprawdzić status wysłanej faktury?
Po wysłaniu faktury API zwraca identyfikator sesji. Status faktury można sprawdzić przez dedykowany endpoint GET, który zwraca informację o powodzeniu walidacji i nadaniu numeru KSeF lub szczegóły błędów.
Co zrobić, gdy faktura zostanie odrzucona?
Jeśli faktura zostanie odrzucona, API zwraca kod błędu i opis problemu. Popraw wskazane błędy (np. strukturę XML, brakujące pola) i wyślij fakturę ponownie. Odrzucona faktura nie jest uznawana za wystawioną.