Praktyczne odpowiedzi o KSeF, FA(3) i e-fakturowaniu w Polsce.
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.
Gotowość na KSeF to dane stron, pola faktury, sposób uwierzytelniania i przetestowany przepływ — wszystko przygotowane, zanim obejmie Cię obowiązek. Przejdź krótką listę: NIP-y nabywcy i sprzedawcy, mapowanie pól FA(3), uwierzytelnianie tokenem i jeden przebieg testowy, żeby zmiana była mechaniczna, a nie gorączkowa.
Bezmyślne ponowienie żądania KSeF po timeoutcie może utworzyć duplikat faktury, bo żądanie mogło dotrzeć do KSeF, choć Ty nigdy nie zobaczyłeś odpowiedzi. Bezpieczny wzorzec to stały klucz idempotencji po Twojej stronie przy każdym zgłoszeniu, sprawdzenie statusu faktury w KSeF przed ponowną wysyłką i ponowne wysłanie tylko wtedy, gdy masz pewność, że wcześniejsza próba się nie powiodła.
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.
Token KSeF to poświadczenie uwierzytelniające z okresem ważności — gdy wygaśnie, integracja przestaje otwierać sesje i wysyłać faktury. Rutyna, która trzyma Cię w ruchu, jest prosta: sprawdź datę ważności, wygeneruj nowy token zanim stary umrze i podmień go w jednym miejscu — w Connect KSeF w Notaly.
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.
UPO (Urzędowe Poświadczenie Odbioru) to oficjalne potwierdzenie, które KSeF zwraca po przyjęciu wysłanej faktury w formacie FA(3). Po wysłaniu dokument przechodzi przez krótki cykl statusów, a UPO jest dowodem, który warto zarchiwizować razem z fakturą. Umiejętność odczytania statusu to podstawa automatyzacji ponowień i rzetelnej informacji dla klienta.
Notaly przyjmuje w API e-faktur cztery stawki VAT: 23%, 8%, 5% i 0% — po jednej na pozycję faktury. Stawka 7%, zwolnienie (zw) i odwrotne obciążenie (oo) nie są dziś obsługiwane. Taka pozycja zostaje odrzucona z kodem 422, zanim faktura dotrze do KSeF.
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.
