Korygowanie dokumentów

Korekty wystawiasz tym samym endpointem co inne dokumenty, POST /external/v1/documents, podając jeden z trzech typów:

• FakturaKorygujaca — korekta zwykłej faktury,
• FakturaKorygujacaZaliczkowa — korekta faktury zaliczkowej,
• FakturaKorygujacaRozliczeniowa — korekta faktury rozliczeniowej.

Każda korekta wymaga correctedInvoiceId (id faktury korygowanej). Może mieć correctionCause (powód: zdarzenie po sprzedaży albo błąd na fakturze), od którego zależy typ korekty w KSeF, oraz correctionReason (opis przyczyny), patrz Powód korekty i jej skutek w KSeF. Korekty wysyłasz do KSeF jak zwykłe faktury (rodzaj KOR), patrz Wysyłka do KSeF.

Wspólna numeracja (zgodnie z KSeF). Wszystkie trzy typy korekt dzielą jeden licznik numeracji. Niezależnie od tego, którą korektę wystawiasz, kolejne numery idą z tej samej puli w obrębie okresu (np. miesiąca). Zasady numeracji opisuje Tworzenie dokumentów.

Zasada delty: przesyłasz stan „po"#

We wszystkich korektach podajesz docelowy stan dokumentu po korekcie, a backend sam liczy różnicę względem faktury korygowanej. Nie przesyłasz pozycji „+/−". Sumy korekty (netSum, vatSum, grossSum) to delta i mogą być ujemne (gdy korekta zmniejsza wartość). Bierz je z odpowiedzi API, nie wyliczaj samodzielnie.

Kolejna korekta tej samej faktury#

Dokument ma najwyżej jedną korektę. Kolejną zmianę wystawiasz jako korektę ostatniej korekty (correctedInvoiceId to id tej korekty). Stan „przed” to wtedy stan po poprzedniej korekcie, więc kwoty nie liczą jej drugi raz: po fakturze na 1000 zł netto i korekcie do 900 zł kolejna korekta do 700 zł ma netto −200 zł, nie −300 zł.

Nowa korekta dokumentu, który ma już korektę, dostaje 409 CORRECTED_INVOICE_HAS_CORRECTION. Komunikat w errors[0] podaje numer i id ostatniej korekty łańcucha, którą trzeba skorygować:

{
  "success": false,
  "message": "CORRECTED_INVOICE_HAS_CORRECTION",
  "errors": ["Dokument FV/1/07/2026 ma już korektę. Ostatnia korekta to KOR/1/08/2026 (id 6820a1b2c3d4e5f6a7b8c9d1): kolejną zmianę wystaw jako korektę tej korekty, żeby stan przed korektą uwzględniał poprzednie zmiany."]
}

Tak samo odpowiadają PUT i PATCH, gdy zmieniasz correctedInvoiceId korekty na dokument, który ma już inną korektę.

W KSeF korekta korekty wskazuje w DaneFaKorygowanej fakturę pierwotną (jej numer, datę wystawienia i numer KSeF, a gdy była wystawiona poza KSeF, znacznik NrKSeFN), a wiersze „przed korektą” i kwoty liczą się od stanu po poprzedniej korekcie. Tak każe Podręcznik KSeF 2.0, część II, punkt 2.13.3. Na wydruku „Korygowany dokument” to faktura pierwotna, a „Poprzednia korekta” wskazuje korektę, od której liczy się stan „przed”.

Faktura pierwotna bez numeru KSeF#

Gdy faktura pierwotna nie ma numeru KSeF, korekta trafia do KSeF ze znacznikiem NrKSeFN, czyli jako korekta faktury wystawionej poza KSeF. Fakturnia nie wstrzymuje takiej wysyłki i jej nie odrzuca. Na koncie połączonym z KSeF POST /documents/validate podaje wtedy w preview.warnings jeden z kodów:

Każdy wpis ma code i message po polsku, który możesz pokazać użytkownikowi. Lista jest pusta, gdy nie ma uwag.

Powód korekty i jej skutek w KSeF#

Korekta może powiedzieć, dlaczego ją wystawiasz. Od tego zależy pole TypKorekty w XML wysyłanym do KSeF oraz okres, w którym korekta wchodzi do rozliczenia w raportach aplikacji (rejestr VAT, JPK_V7, KPiR).

Gdy nie podasz correctionType, Fakturnia wylicza TypKorekty przy wysyłce do KSeF:

Reguła idzie za ustawą o VAT: zwiększenie podstawy należy do okresu, w którym powstała jego przyczyna (art. 29a ust. 17), czyli przy błędzie do okresu faktury pierwotnej, a przy zdarzeniu po sprzedaży do dnia z correctionEffectDate, obniżka wystawiona w KSeF do okresu wystawienia korekty (art. 29a ust. 13 i 14), a korekta do zera faktury, która nie powinna istnieć, do okresu faktury pierwotnej (stanowisko MF z 20.05.2026). W podatku dochodowym korekta błędu wraca do okresu faktury pierwotnej (art. 14 ust. 1m ustawy o PIT).

{
  "documentType": "FakturaKorygujaca",
  "issueDate": "2026-10-06",
  "correctedInvoiceId": "681a3b2c4d5e6f7a8b9c0d1e",
  "correctionCause": "mistake",
  "correctionReason": "Błędna cena jednostkowa",
  "products": [
    { "name": "Usługa", "unitOfMeasure": "szt.", "quantity": 1, "netPrice": 150, "vatRate": 23 }
  ]
}

Ta korekta poprawia błąd i podnosi podstawę, więc trafi do KSeF z TypKorekty 1.

Na co wpływają pola:

• KSeF. TypKorekty w XML korekty. Bez correctionCause i correctionType wysyłamy 2, jak dotychczas, więc istniejące integracje działają bez zmian.
• Raporty w aplikacji. Rejestr VAT i JPK_V7 umieszczają korektę z TypKorekty 1 w okresie faktury korygowanej, a KPiR korektę z powodem mistake w okresie przychodu faktury korygowanej. Oba okresy dostają uwagę o przeniesieniu.
• Odczyt. GET /documents/{id} i webhooki document.created oraz document.updated zwracają oba pola: null, gdy nie podano, a correctionType: null oznacza typ wyliczany.
• Zmiana. PUT i PATCH przyjmują oba pola do czasu wysłania korekty do KSeF. Przy dokumentach, które nie są korektą, pola są pomijane.
• Data i okres sprzedaży. Korekta bez subDate przejmuje datę albo okres sprzedaży faktury korygowanej: FA(3) wypełnia się według stanu po korekcie, a dostawa odbyła się wtedy, kiedy na fakturze pierwotnej. Korekta faktury zaliczkowej nie ma daty sprzedaży.
• Kurs waluty. Korekta bez exchangeRate przejmuje kurs faktury korygowanej razem z dniem i numerem tabeli NBP (art. 31b ust. 1), także gdy podasz tę samą walutę.
• Data wystawienia. Korekta nie może mieć daty wystawienia wcześniejszej niż faktura korygowana (422 DOCUMENT_DATES_INVALID).
• Walidacja. Wartość spoza słownika i przyczyna dłuższa niż 256 znaków dają błąd walidacji: 400 VALIDATION_ERROR przy POST, 422 VALIDATION_ERROR przy PUT i PATCH. Wcześniej za długą przyczynę odrzucał dopiero KSeF przy wysyłce.

Faktura korygująca (FakturaKorygujaca)#

Najczęstsza korekta: zmiana ilości, ceny, stawki VAT lub danych pozycji.

• products to pełny stan pozycji po korekcie (cały dokument taki, jaki ma być po zmianie).
• Sumy: grossSum = Σ(pozycje po) − grossSum faktury korygowanej (analogicznie netSum i vatSum).

{
  "documentType": "FakturaKorygujaca",
  "issueDate": "2026-06-04",
  "correctedInvoiceId": "681a3b2c4d5e6f7a8b9c0d1e",
  "correctionReason": "Zmiana ilości",
  "products": [
    { "name": "Usługa", "unitOfMeasure": "szt.", "quantity": 2, "netPrice": 100, "vatRate": 23 }
  ]
}

Wyzerowanie / anulowanie faktury#

Aby anulować dokument (np. po anulowaniu zamówienia), wystaw korektę z tymi samymi pozycjami, ale quantity: 0, zostawiając netPrice/grossPrice z faktury pierwotnej. Pozycja z ilością 0 ma wartość 0, więc stan „po" wynosi 0, a delta korekty to pełne odwrócenie faktury do zera.

{
  "documentType": "FakturaKorygujaca",
  "issueDate": "2026-06-04",
  "correctedInvoiceId": "681a3b2c4d5e6f7a8b9c0d1e",
  "correctionReason": "Anulowanie zamówienia",
  "products": [
    { "name": "Usługa", "unitOfMeasure": "szt.", "quantity": 0, "netPrice": 100, "vatRate": 23 }
  ]
}

Cenę jednostkową zostawiasz celowo. KSeF oczekuje pozycji „po" z ceną sprzed korekty i ilością 0, a nie pustej pozycji. Wartość pozycji liczy się z ilości, więc przy quantity: 0 wynosi 0.

Korekta faktury zaliczkowej (FakturaKorygujacaZaliczkowa)#

Koryguje wcześniej wystawioną fakturę zaliczkową (zmiana kwoty zaliczki lub pozycji powiązanego zamówienia).

Wymagane pola:

• correctedInvoiceId — korygowana faktura zaliczkowa (musi mieć powiązane zamówienie i advancePaymentAmount) albo, przy kolejnej zmianie, ostatnia korekta zaliczkowa tej faktury,
• products — pozycje zamówienia po korekcie (baza proporcjonalnego rozkładu),
• correctionAdvanceAmountAfter — nowa kwota zaliczki po korekcie (≥ 0).

Sumy:

• grossSum = correctionAdvanceAmountAfter − kwota zaliczki przed korektą (advancePaymentAmount faktury zaliczkowej albo correctionAdvanceAmountAfter poprzedniej korekty zaliczkowej; zamówienie przed korektą to wtedy jej pozycje),
• netSum / vatSum to różnica proporcjonalnych rozkładów VAT obu kwot (patrz Jak liczone są podatki).

{
  "documentType": "FakturaKorygujacaZaliczkowa",
  "issueDate": "2026-06-04",
  "correctedInvoiceId": "6820a1b2c3d4e5f6a7b8c9d0",
  "correctionReason": "Zmniejszenie zaliczki",
  "correctionAdvanceAmountAfter": 500,
  "products": [
    { "name": "Towar A", "unitOfMeasure": "szt.", "quantity": 10, "netPrice": 100, "vatRate": 23 }
  ]
}

Korekta faktury rozliczeniowej (FakturaKorygujacaRozliczeniowa)#

Koryguje fakturę rozliczeniową (końcową).

Wymagane pola:

• correctedInvoiceId — korygowana faktura rozliczeniowa,
• products — pozycje po korekcie,
• correctionSettlementAmountAfter — nowa kwota rozliczenia po korekcie (≥ 0).

Sumy:

• grossSum = correctionSettlementAmountAfter − kwota rozliczenia sprzed korekty,
• netSum / vatSum to różnica proporcjonalnych rozkładów VAT (jak wyżej).

{
  "documentType": "FakturaKorygujacaRozliczeniowa",
  "issueDate": "2026-06-04",
  "correctedInvoiceId": "6830a1b2c3d4e5f6a7b8c9d0",
  "correctionReason": "Korekta rozliczenia",
  "correctionSettlementAmountAfter": 1230,
  "products": [
    { "name": "Towar A", "unitOfMeasure": "szt.", "quantity": 10, "netPrice": 100, "vatRate": 23 }
  ]
}

Korekta faktury pobranej z KSeF#

Faktura sprzedaży wystawiona w innym programie i pobrana z KSeF (source: "ksef", direction: "income") może być korygowana tak samo jak własna: podaj jej _id w correctedInvoiceId. API samo czyta pozycje, sumy i adres nabywcy z XML faktury (pobiera go z KSeF, jeśli faktura nie była jeszcze otwierana w aplikacji), więc stan „przed" i wiersze StanPrzed w KSeF odpowiadają oryginałowi. W DaneFaKorygowanej korekta wskazuje numer KSeF faktury pierwotnej.

Ograniczenia: tylko faktura sprzedaży (zakupowej nie koryguje jej odbiorca) i tylko zwykła faktura VAT; faktury zaliczkowe, rozliczeniowe i korekty pobrane z KSeF nie mają w Fakturni danych, z których powstałby stan „przed".

Jak liczone są podatki#

Zwykła korekta (FakturaKorygujaca) liczy sumy wprost, jako różnicę pozycji: (suma pozycji po) − (suma faktury korygowanej), osobno dla netto, VAT i brutto.

Korekty zaliczki i rozliczenia działają inaczej, bo zaliczka i rozliczenie to jedna kwota brutto, którą trzeba rozbić na stawki VAT. Robi to proporcjonalny rozkład:

1. Pozycje (zamówienia dla zaliczki, faktury dla rozliczenia) grupowane są po stawce VAT i sumowane brutto.
2. Każda stawka dostaje udział w kwocie proporcjonalny do swojego brutto: udział = brutto stawki / brutto całości. Ostatnia stawka dostaje resztę, co eliminuje grosze z zaokrągleń.
3. Z przypadającej na stawkę kwoty brutto liczone są netto i VAT: netto = brutto / (1 + stawka/100), VAT = brutto − netto. Stawki specjalne (zw, oo, np …, 0 …) mają VAT = 0, netto = brutto.

Korekta to różnica dwóch takich rozkładów: rozkład kwoty „po" minus rozkład kwoty „przed". Dlatego grossSum to po prostu różnica kwot, a netSum / vatSum wynikają z różnicy proporcjonalnych podziałów. Przykład: gdy zaliczka 615 zł (stawka 23%) spada do 500 zł, grossSum = 500 − 615 = −115, a netto i VAT to różnica rozkładów obu kwot.

Proporcjonalny rozkład jest identyczny jak przy wystawianiu samej faktury zaliczkowej czy rozliczeniowej, więc korekta zawsze domyka się co do grosza względem dokumentu pierwotnego.

Najczęstsze błędy#

Co dalej#

• Tworzenie dokumentów — pełna anatomia żądania i numeracja.
• Typy dokumentów i kwoty — reguły obliczeń i zaokrąglanie.
• Wysyłka do KSeF — wyślij korektę do KSeF.
• Błędy — kody i obsługa.