Jak wysłać fakturę do KSeF

Co musisz wiedzieć przed wysyłką

KSeF przyjmuje wyłącznie faktury w formacie XML zgodne ze schemą XSD. Do 31 stycznia 2026 obowiązuje struktura FA(2), od 1 lutego 2026 - wyłącznie FA(3).

Dokument po wysyłce otrzymuje nadany numer KSeF, który identyfikuje go w systemie. Numer ten jest unikalny i niezmienny.

Większość błędów wynika z nieprawidłowej struktury dokumentu, brakujących pól obowiązkowych lub problemów z szyfrowaniem.

W API 2.0 wszystkie faktury muszą być zaszyfrowane algorytmem AES-256-CBC z dopełnieniem PKCS#7. Klucz symetryczny szyfrowany jest algorytmem RSAES-OAEP (SHA-256/MGF1) przy użyciu klucza publicznego KSeF.

Maksymalny rozmiar faktury bez załączników to 1 MB (1 000 000 bajtów), z załącznikami - 3 MB (3 000 000 bajtów). W jednej sesji można przesłać maksymalnie 10 000 faktur.

Faktura ustrukturyzowana jest uznana za wystawioną w dniu jej przesłania do KSeF (tryb online), pod warunkiem że data przesłania jest taka sama jak data wskazana w polu P_1.

Instrukcja krok po kroku

1. Przygotuj fakturę w formacie XML

Upewnij się, że dokument jest zgodny z aktualnym schematem XSD (FA(2) do 31 stycznia 2026, FA(3) od 1 lutego 2026). Plik musi być kodowany w UTF-8 bez znaku BOM. Wypełnij wszystkie pola obowiązkowe zgodnie z wymaganiami struktury logicznej faktury ustrukturyzowanej.

2. Zaloguj się do systemu KSeF

Użyj jednej z dostępnych metod: Profil Zaufany, ePUAP, podpis kwalifikowany lub certyfikat KSeF. W przypadku API, najpierw przejdź przez proces uwierzytelniania (pobranie challenge, podpisanie AuthTokenRequest lub użycie tokena KSeF, uzyskanie accessToken).

3. Otwórz sesję interaktywną (dla API)

Wygeneruj klucz symetryczny AES-256 bitów i wektor inicjujący IV (128 bitów). Zaszyfruj klucz symetryczny kluczem publicznym KSeF algorytmem RSAES-OAEP. Otwórz sesję za pomocą POST /api/v2/sessions/online, podając formCode (schemat faktury) oraz zaszyfrowany klucz. Sesja jest ważna przez 12 godzin.

4. Zaszyfruj fakturę

Zaszyfruj dokument XML algorytmem AES-256-CBC z dopełnieniem PKCS#7, używając wygenerowanego klucza symetrycznego. Oblicz skróty SHA faktury przed i po szyfrowaniu wraz z rozmiarami plików. IV dołącz jako prefiks do szyfrogramu.

5. Wyślij fakturę do KSeF

Prześlij zaszyfrowaną fakturę wraz z metadanymi (skróty i rozmiary) do odpowiedniego endpointu. W portalu webowym: przejdź do sekcji ‘Wyślij fakturę’ i prześlij plik XML. W API: użyj POST /api/v2/sessions/online/{referenceNumber}/invoices/. Po przesłaniu KSeF wyświetli numer referencyjny dokumentu.

6. Sprawdź status wysyłki

Po przesłaniu faktury rozpoczyna się asynchroniczna weryfikacja. Sprawdź status faktury - system zweryfikuje zgodność ze schematem XSD, unikalność (sprawdzenie duplikatów), walidację dat, poprawność szyfrowania oraz wymagane uprawnienia.

7. Zamknij sesję i pobierz UPO

Po wysłaniu wszystkich faktur zamknij sesję (POST /api/v2/sessions/online/{referenceNumber}/close dla API). Sprawdź status sesji i pobierz zbiorcze UPO (Urzędowe Poświadczenie Odbioru), które potwierdza przyjęcie faktury do systemu.

Najczęstsze problemy i rozwiązania

Błąd walidacji XML

Dokument ma strukturę niezgodną z XSD. Sprawdź, czy używasz właściwej wersji schematu (FA(2) do 31 stycznia 2026, FA(3) od 1 lutego 2026), czy wszystkie pola obowiązkowe są wypełnione, czy struktura XML jest poprawna i czy plik jest kodowany w UTF-8 bez znaku BOM. Użyj walidatora XSD do sprawdzenia dokumentu przed wysyłką.

Odrzucenie faktury

Sprawdź komunikat błędu zwrócony przez system. Najczęstsze przyczyny: brakujące pola obowiązkowe, nieprawidłowe wartości w polach, błąd walidacji dat (data wystawienia P_1 nie może być późniejsza niż data przyjęcia do KSeF), przekroczony limit rozmiaru (max 1 MB bez załączników, 3 MB z załącznikami) lub brak odpowiednich uprawnień do wystawienia faktury.

Błąd 440 - Duplikat faktury

KSeF wykrywa duplikaty na podstawie kombinacji: NIP sprzedawcy (Podmiot1:NIP), RodzajFaktury i numer faktury (P_2). Unikalność faktury utrzymywana jest przez 10 pełnych lat. Jeśli wystawiasz faktury w imieniu tego samego podmiotu przez różne jednostki (np. oddziały), muszą one uzgodnić zasady numeracji, aby uniknąć duplikatów.

Błąd szyfrowania - faktura nie może być odszyfrowana

Upewnij się, że używasz algorytmu AES-256-CBC z dopełnieniem PKCS#7. Klucz symetryczny musi być zaszyfrowany algorytmem RSAES-OAEP (SHA-256/MGF1) przy użyciu aktualnego klucza publicznego KSeF. Sprawdź, czy IV jest poprawnie dołączony jako prefiks do szyfrogramu. Upewnij się, że używasz tego samego klucza, który został przekazany przy otwieraniu sesji.

Błąd uprawnień - brak możliwości wystawienia faktury

Wysłanie faktury do KSeF wymaga posiadania odpowiednich uprawnień do jej wystawienia w kontekście danego podmiotu. Sprawdź, czy masz uprawnienie InvoiceWrite w kontekście NIP, dla którego próbujesz wystawić fakturę. Jeśli jesteś osobą fizyczną, upewnij się, że masz nadane odpowiednie uprawnienia przez właściciela lub administratora podmiotu.

Faktura nie pojawia się w systemie po wysyłce

Proces weryfikacji faktury jest asynchroniczny. Sprawdź status faktury używając numeru referencyjnego otrzymanego po wysyłce. Jeśli status wskazuje na błąd, sprawdź szczegóły komunikatu błędu. W przypadku sesji interaktywnej, upewnij się, że zamknąłeś sesję, aby zainicjować generowanie UPO.

Weryfikacja faktury w KSeF

Po przesłaniu faktury do KSeF, system przeprowadza szereg kontroli: zgodność ze schematem XSD, unikalność faktury (wykrywanie duplikatów na podstawie NIP sprzedawcy, RodzajFaktury i numeru faktury P_2), walidacja dat (data wystawienia P_1 nie może być późniejsza niż data przyjęcia do systemu), weryfikacja rozmiaru pliku, poprawne szyfrowanie oraz wymagane uprawnienia do wystawienia faktury. Proces weryfikacji jest asynchroniczny.

Struktura logiczna faktury ustrukturyzowanej

Faktura ustrukturyzowana składa się z nagłówka (dane techniczne), danych podmiotów (Podmiot1 - sprzedawca, Podmiot2 - nabywca, Podmiot3 - dodatkowe podmioty, PodmiotUpowazniony - np. komornik), szczegółowych danych faktury (wartości kwotowe, stawki podatku, adnotacje, informacje o płatności i transporcie), stopki (dodatkowe informacje) oraz opcjonalnie załącznika (wymaga zgłoszenia w e-US).

Tryby wysyłki faktur

Sesja interaktywna służy do przesyłania pojedynczych faktur ustrukturyzowanych. Sesja jest ważna przez 12 godzin od momentu utworzenia. Sesja wsadowa umożliwia przesyłanie wielu faktur w jednej paczce (maksymalnie 10 000 faktur). W wersji 2.0 każda faktura w paczce przetwarzana jest niezależnie - błędy dotyczą tylko konkretnych faktur, nie całej paczki. Tryb offline umożliwia wystawienie faktury podczas niedostępności KSeF, z obowiązkiem przesłania do systemu po zakończeniu awarii.

FAQ

Powiązane tematy

• KSeF faktura ustrukturyzowana
• KSeF API 2.0