Poradniki krok po kroku: wystawianie, wysyłka i śledzenie e-faktur w KSeF przez API Notaly.
Fakturą prawnie wiążącą w KSeF jest ustrukturyzowany plik XML FA(3), a UPO wraz z numerem KSeF to Twoje potwierdzenie, że dokument został przyjęty. KSeF przechowuje faktury, które u siebie gromadzi, przez 10 lat, więc możesz je odzyskać, dopóki masz dostęp; lokalnie archiwizuj razem XML, numer UPO i numer KSeF. PDF traktuj jako kopię do czytania dla ludzi, a nie jako dokument źródłowy.
KSeF zgłasza problemy jako kody wyjątków w treści odpowiedzi, obok statusu HTTP — i to kod, a nie sam numer HTTP, mówi, co naprawdę się nie powiodło. Najczęstsze przyczyny to nieprawidłowe wyzwanie uwierzytelniające, nieprawidłowy certyfikat albo faktura, która nie przechodzi schematu FA(3) i jest następnie raportowana jako nieprawidłowo przetworzona. Zamiast zgadywać, porównaj polski opis z oficjalną tabelą kodów KSeF — ten sam numer potrafi znaczyć co innego w różnych endpointach.
Przejście na KSeF to zmiana danych i procesu, a nie tylko podmiana API: potrzebujesz czystych identyfikatorów stron, odwzorowania faktury dającego poprawny FA(3), metody uwierzytelnienia i przebiegu testowego przed produkcją. Przejście przez tę krótką listę w sandboksie sprawia, że wejście na produkcję staje się zmianą konfiguracji, a nie pierwszą próbą.
Tryb offline KSeF to procedura awaryjna Ministerstwa Finansów na fakturowanie, gdy platforma jest niedostępna; dokument i tak trzeba później przesłać do KSeF, w oknie wyznaczonym przez Ministerstwo. W KSeF 2.0 faktura offline ma dwa kody QR: KOD I to link weryfikacyjny generowany przez wystawcę z sumy SHA-256 pliku XML, a KOD II to kod QR wystawcy podpisany certyfikatem KSeF typu Offline.
Gdy faktura zostaje przyjęta, KSeF zwraca UPO (urzędowe poświadczenie odbioru) i numer KSeF; czytelny PDF to wizualizacja, którą Notaly generuje z danych FA(3) i na której umieszcza oficjalny kod QR KOD I. KOD I i KOD II to dwa różne kody, a nie dwa stany jednego: KOD I to link weryfikacyjny budowany przez wystawcę z sumy SHA-256 pliku XML, a KOD II to kod QR wystawcy podpisany certyfikatem KSeF typu Offline, dodawany tylko na fakturze offline.
Integrację z KSeF testujesz w środowisku testowym (api-test.ksef.mf.gov.pl), gdzie każde zgłoszenie nie ma skutku prawnego ani podatkowego. Sandbox Notaly wysyła dokumenty do TEST KSeF z użyciem testowych poświadczeń platformy i daje Ci trzy darmowe faktury testowe, dzięki czemu sprawdzisz XML FA(3) i cały przepływ, zanim w ogóle zbliżysz się do produkcji.
Gdy tworzysz fakturę, odpowiedź POST /invoices zwraca status submitted z numerem referencyjnym KSeF, a ostateczna decyzja — accepted lub rejected — przychodzi później. Status sprawdzisz, odpytując GET /invoices/{id} (który ponownie odpytuje KSeF, dopóki faktura jest w submitted) albo nasłuchując podpisanego webhooka. UPO i numer KSeF przychodzą razem ze statusem accepted.
Środowisko testowe KSeF (api-test.ksef.mf.gov.pl) to sandbox Ministerstwa Finansów, w którym wysyłasz faktury w formacie FA(3) bez dotykania danych produkcyjnych. Działa na tym samym schemacie FA(3) i z tym samym cyklem statusów, więc to bezpieczne miejsce, by sprawdzić XML, uwierzytelnienie i obsługę statusów przed startem. Sandbox Notaly jest podpięty do KSeF TEST i obejmuje trzy darmowe faktury testowe.
Token KSeF to poświadczenie, którym Twój system uwierzytelnia się w API KSeF i otwiera sesję. Generujesz go w portalu KSeF (albo przez API), podajesz integracji — lub Notaly w Connect KSeF — i dzięki temu wysyłasz faktury bez pieczęci kwalifikowanej. Token uwierzytelnia sesję; nie służy do podpisywania faktury.
KSeF przyjmuje dwa sposoby uwierzytelnienia sesji: token wydany przez KSeF albo podpis XAdES złożony podpisem kwalifikowanym, pieczęcią kwalifikowaną lub certyfikatem KSeF. To alternatywy dla tego samego kroku — potwierdzenia, kim jesteś, zanim wyślesz fakturę — a w obu przypadkach sam plik XML faktury nie jest podpisywany: jest szyfrowany i wysyłany w sesji. Notaly używa tokenu, więc pieczęć kwalifikowana nie jest Ci potrzebna.
KSeF rozstrzyga, czy faktura została przyjęta, asynchronicznie, więc samo wywołanie wysyłki to nie koniec: Notaly odpytuje KSeF za Ciebie i wypycha ostateczny wynik na Twój endpoint jako podpisany webhook — invoice.accepted (z numerem KSeF i UPO), invoice.rejected albo invoice.error. Każdy webhook jest podpisany HMAC i ponawiany z narastającym opóźnieniem, dzięki czemu budujesz niezawodną automatyzację zamówienie → faktura bez własnego pollingu.
Załóż konto sandbox: klucz API w kilka sekund, 3 darmowe faktury testowe w KSeF TEST, bez karty płatniczej.
