Program wysłał do Krajowego Systemu e-Faktur (KSeF) korektę techniczną faktury i dostał odmowę. Komunikat brzmi „Korekta techniczna niedostępna.” (kod 21166) albo „Status faktury nie pozwala na korektę techniczną.” (kod 21167).
Oba kody znaczą, że w tej sytuacji korekta techniczna nie jest potrzebna albo nie jest już możliwa. Poniżej wyjaśniamy, czym jest korekta techniczna, z czym się ją myli i co zrobić po każdym z tych kodów. Pozostałe kody opisujemy na stronie z pełną listą kodów błędów KSeF.
Czym jest korekta techniczna w KSeF
Dokumentacja MF (korekta-techniczna.md) opisuje ją jednym zdaniem. Korekta techniczna „umożliwia ponowne przesłanie faktury wystawionej w trybie offline, która po przesłaniu do systemu KSeF została odrzucona z powodu błędów technicznych”. Chodzi o błędy takie jak niezgodność ze schematem albo zbyt duży plik.
Z tej samej dokumentacji wynikają cztery zasady:
- Tylko faktura z trybu offline. Korekta techniczna dotyczy faktury wystawionej w trybie offline i odrzuconej po przesłaniu do KSeF.
- Bez zmiany treści. Dane faktury zostają takie same. To ta sama faktura, przesłana w technicznie poprawnej postaci.
- Tylko w sesji interaktywnej. Korekty technicznej nie wysyła się w paczce wsadowej.
- Tylko jedna przyjęta. Po przyjęciu poprawnej korekty technicznej drugiej do tej samej faktury już nie wyślesz.
Dokumentacja wyłącza też jeden przypadek. Korekta techniczna nie służy do naprawy braku uprawnień podmiotów. Jeżeli faktura offline została odrzucona z tego powodu, ta droga nie pomoże.
Kody 21166 i 21167 dotyczą więc tylko programów, które wystawiają faktury w trybie offline i obsługują korektę techniczną. FakturaFlow nie wystawia faktur w trybie offline, więc ten opis opiera się wyłącznie na dokumentacji MF. Czym są tryby offline i kiedy się z nich korzysta, wyjaśniamy w tekście KSeF nie działa? Tryby offline i awaria krok po kroku.
Korekta techniczna, faktura korygująca czy duplikat
Te trzy rzeczy łatwo pomylić. Każda służy do czegoś innego.
Korekta techniczna to ponowne wysłanie faktury z trybu offline, którą KSeF odrzucił z przyczyn technicznych. Taka faktura nie ma jeszcze numeru KSeF, bo system jej nie przyjął.
Faktura korygująca to nowy dokument, który zmienia dane faktury już przyjętej, na przykład kwoty albo stawki. Dostaje własny numer KSeF. Gdy błąd tkwi w treści faktury, potrzebujesz właśnie jej. Szczegóły opisujemy w tekście o korekcie faktury w KSeF.
Duplikat powstaje, gdy wyślesz zwykłą drogą fakturę, którą KSeF już przyjął. System odrzuca ją wtedy kodem 440 „Duplikat faktury”. Rozpoznaje go po NIP-ie sprzedawcy, rodzaju faktury i jej numerze. Więcej w tekście o błędzie 440 w KSeF.
Prosty test: czy KSeF przyjął fakturę? Jeżeli tak, ma ona numer KSeF i korekta techniczna jej nie dotyczy. Jeżeli nie, a faktura pochodzi z trybu offline i odrzucenie było techniczne, wchodzi w grę korekta techniczna.
Co oznaczają kody 21166 i 21167
Oba to kody wyjątków, czyli odpowiedzi HTTP 400 na wysłanie faktury w sesji interaktywnej. Nie są to statusy faktury ani sesji. W dokumentacji API KSeF 2.0 (repozytorium CIRF) każdy z nich ma jedno znaczenie.
Kod 21166: „Korekta techniczna niedostępna.”
Szczegóły brzmią: „Faktura posiada już przetworzoną prawidłowo korektę techniczną.”. Do tej faktury KSeF przyjął już jedną poprawną korektę techniczną. Druga nie jest możliwa. Skoro pierwsza została przetworzona prawidłowo, faktura jest w KSeF.
Kod 21167: „Status faktury nie pozwala na korektę techniczną.”
Szczegóły brzmią: „Nie można wysłać korekty technicznej do prawidłowo przetworzonej faktury.”. Tu chodzi o fakturę pierwotną. KSeF przetworzył ją prawidłowo, więc nie ma czego poprawiać technicznie. Faktura jest w KSeF i ma numer KSeF.
Najczęstsze przyczyny
Dokumentacja MF podaje znaczenie obu kodów, ale nie opisuje, jak do nich dochodzi. Poniższe przyczyny wynikają z zasad korekty technicznej, a nie z oficjalnego opisu.
1. Program ponowił korektę, która już przeszła (21166)
Program wysłał korektę techniczną, ale nie dostał odpowiedzi KSeF. Uznał wysyłkę za nieudaną i wysłał ją drugi raz. Tymczasem pierwsza została przyjęta. Rozpoznasz po tym, że w historii wysyłek tej faktury widać dwie korekty techniczne.
2. Faktura pierwotna wcale nie została odrzucona (21167)
Ktoś uznał, że faktura offline nie przeszła, na przykład po błędzie połączenia. Tymczasem KSeF ją przyjął. Rozpoznasz po tym, że faktura ma numer KSeF i status 200 „Sukces”.
3. Korekta techniczna pomylona z fakturą korygującą (21167)
Ktoś chciał zmienić dane przyjętej faktury i wybrał w programie korektę techniczną. Rozpoznasz po tym, że faktura pierwotna ma numer KSeF, a zmiana dotyczy jej treści.
4. Korekta wskazuje niewłaściwą fakturę (21167)
Korekta techniczna wskazuje fakturę pierwotną przez jej skrót. Jeżeli program podał skrót innej, przyjętej faktury, odpowiedź może być taka sama. Rozpoznasz po tym, że faktura, którą chcesz poprawić, ma status odrzucenia, a mimo to KSeF odpowiada 21167.
Co zrobić krok po kroku
- Sprawdź status faktury pierwotnej. Zajrzyj do historii wysyłek w programie. Jeżeli faktura ma numer KSeF i status 200 „Sukces”, jest w systemie.
- Przy 21166 znajdź pierwszą korektę techniczną. Została przyjęta. Zapisz numer KSeF faktury i pobierz UPO, czyli Urzędowe Poświadczenie Odbioru. Kolejnej korekty nie wysyłaj.
- Przy 21167 nie ponawiaj korekty technicznej. Faktura pierwotna jest w KSeF. Jeżeli jej dane są poprawne, nic więcej nie robisz.
- Jeżeli dane faktury są błędne, wystaw fakturę korygującą. Do zmiany treści faktury przyjętej przez KSeF służy właśnie ona, nie korekta techniczna.
- Jeżeli faktura ma status odrzucenia, a KSeF i tak odpowiada 21167, zgłoś to dostawcy programu. Korekta musi wskazywać skrót tej odrzuconej faktury. Sprawdzi to tylko program, który ją wysyła.
- Nie wysyłaj tej samej faktury zwykłą drogą „na wszelki wypadek”. Skoro jest już w KSeF, skończy się to kodem 440.
Jak temu zapobiec
- Przed korektą techniczną sprawdź status faktury pierwotnej. Nie polegaj na samym komunikacie programu o błędzie połączenia.
- Po zgubionej odpowiedzi najpierw sprawdź status, potem wysyłaj. Ta sama zasada chroni przed duplikatami przy zwykłej wysyłce.
- Rozdziel dwa rodzaje błędów. Błąd techniczny faktury offline naprawia korekta techniczna. Błąd w treści faktury naprawia faktura korygująca.
Dla programisty
Korektę techniczną wysyła się w sesji interaktywnej, POST /sessions/online/{referenceNumber}/invoices, z offlineMode: true i hashOfCorrectedInvoice. To skrót SHA-256 faktury korygowanej, czyli tej odrzuconej, zakodowany w Base64. Kody 21166 i 21167 przychodzą jako wyjątki HTTP 400 z polami ExceptionCode, ExceptionDescription i Details. Ponowienie tego samego żądania nie zmieni stanu faktury, więc nie obejmuj tych kodów automatycznymi ponowieniami. Jeszcze jedna zasada z dokumentacji: faktury z załącznikami wolno wysyłać tylko w sesji wsadowej, ale korekta techniczna faktury offline może zostać wysłana w sesji interaktywnej.
Chcesz widzieć, co KSeF zrobił z każdą fakturą? W FakturaFlow okno „Szczegóły KSeF” pokazuje historię statusów faktury, numer KSeF, link do publicznej strony weryfikacji MF i wysłany plik XML. Każdy błąd KSeF widzisz po polsku, z informacją, co poprawić. Działa obok Twojego programu księgowego, nie zamiast niego. Zobacz, jak działa FakturaFlow.
Podsumowanie
Kod 21166 znaczy, że faktura ma już przyjętą korektę techniczną, a drugiej wysłać nie można. Kod 21167 znaczy, że faktura pierwotna została przetworzona prawidłowo, więc nie ma czego poprawiać technicznie. W obu przypadkach faktura jest w KSeF, a błędne dane poprawia faktura korygująca. Opisy innych kodów znajdziesz na pełnej liście kodów błędów KSeF.
Stan na październik 2026 r. Opis na podstawie dokumentacji API KSeF 2.0 (wersja 2.8). Kody i komunikaty mogą się zmienić wraz z nowymi wersjami API.