name: ksef-correction
description: >
  Guides the user through correcting an invoice that was already issued (korekta, faktura
  korygująca) and generates the corrective FA(3) XML: KOR, KOR_ZAL, KOR_ROZ, correction to zero,
  wrong buyer NIP (zero and reissue), changed seller or buyer data, batch corrections (korekta
  zbiorcza). Use when the user has a faulty invoice and says correct, fix, korekta, faktura
  korygująca, pomyłka w fakturze or błędny NIP. Asks for any missing data, then produces
  validator-passing XML.

KSeF Corrective Invoice Wizard

Collect the original invoice, find out what was wrong, ask for missing data, then produce complete corrective XML. Never put TODOs or placeholder values in the XML; ask the user instead.

Bundled references, loaded on demand:

• references/invoice-base.md: FA(3) skeleton with Podmiot patterns, Adnotacje, P_12 rates and field order
• references/correction-procedures.md: the Ministry of Finance rules for corrections (Podręcznik KSeF 2.0, Part II, section 2.13)

---

Wizard Flow

Step 1: Accept the Original Invoice

Ask for the original (faulty) invoice in one of these forms:

• XML file: the full FA(3) XML of the original invoice
• Pasted XML
• Key data, at minimum: seller NIP, buyer NIP, invoice number (P_2), issue date (P_1), original amounts (P_13_x, P_14_x, P_15), line items, and the KSeF number if it was submitted to KSeF

If the user gives a file path, read it. If they describe the invoice in words, extract what you can and fill the gaps in Step 3.

Step 2: Identify Correction Type

Based on what the user wants to fix, determine the correction scenario:

Scenario	RodzajFaktury	Key rule
Fix amounts, quantities, prices, descriptions	KOR	Amounts are deltas (differences)
Fix advance invoice (ZAL)	KOR_ZAL	Delta amounts + Zamowienie before/after
Fix settlement invoice (ROZ)	KOR_ROZ	Delta amounts + FakturaZaliczkowa reference
Wrong buyer NIP	KOR (to zero) + new VAT	The NIP cannot be changed: zero and reissue
Wrong seller data (name, address)	KOR with Podmiot1K	Old data in Podmiot1K, correct in Podmiot1
Wrong buyer data (name, address, not NIP)	KOR with Podmiot2K	Old data in Podmiot2K, correct in Podmiot2

Ask:

What needs to be corrected? (e.g., wrong price, wrong quantity, wrong buyer name, wrong buyer NIP, add missing line, remove a line, change VAT rate)

Step 3: Gather Missing Data

Based on the correction type, ask only for data you do not already have:

For amount or line corrections:

• Which line(s) need correcting?
• What are the correct values? (new quantity, new unit price, or new total)
• Reason for correction? (optional but recommended; fills PrzyczynaKorekty)

For a wrong buyer NIP:

• Confirm that two documents will be generated: a correction to zero and a new invoice with the correct NIP
• What is the correct buyer NIP?
• What is the correct buyer name and address?

For seller or buyer data corrections (not NIP):

• What are the correct data values?

For all corrections, confirm:

• Was the original invoice submitted to KSeF? (determines NrKSeF vs NrKSeFN)
• If yes: what is the KSeF number? (NrKSeFFaKorygowanej)
• What date should the correction have? (P_1, default today)
• What number should the corrective invoice have? (P_2)
• When should the correction take effect? (TypKorekty: 1=original date, 2=correction date, 3=other)

Step 4: Calculate Deltas

For amount corrections, calculate the differences:

Delta P_13_x = new_P_13_x - original_P_13_x
Delta P_14_x = new_P_14_x - original_P_14_x
Delta P_15   = new_P_15   - original_P_15

For "correction to zero":

Delta P_13_x = -original_P_13_x
Delta P_14_x = -original_P_14_x
Delta P_15   = -original_P_15

Step 5: Generate XML

Produce the complete corrective invoice XML using the structure below.

---

XML Structure

Required Elements (All Corrective Types)

<RodzajFaktury>KOR</RodzajFaktury>
<PrzyczynaKorekty>...</PrzyczynaKorekty>  <!-- optional but recommended -->
<TypKorekty>2</TypKorekty>  <!-- 1=original date, 2=correction date, 3=other -->
<DaneFaKorygowanej>
  <DataWystFaKorygowanej>2026-03-01</DataWystFaKorygowanej>
  <NrFaKorygowanej>FV/001/03/2026</NrFaKorygowanej>
  <!-- Original was in KSeF: -->
  <NrKSeF>1</NrKSeF>
  <NrKSeFFaKorygowanej>9999999999-20260301-XXXXXX-YYYYYY-ZZ</NrKSeFFaKorygowanej> <!-- KSeF number assigned to the original invoice -->
  <!-- OR original was NOT in KSeF: -->
  <!-- <NrKSeFN>1</NrKSeFN> -->
</DaneFaKorygowanej>

Exactly one of NrKSeF or NrKSeFN must be set to 1 (KOR_NRKSEF_CONSISTENCY). When NrKSeF=1, NrKSeFFaKorygowanej is required. When NrKSeFN=1, NrKSeFFaKorygowanej must be absent.

Delta Amounts

P_13_x, P_14_x, P_15 contain the difference, not the corrected total.

<!-- Correction in minus: reducing net by 100 PLN at 23% -->
<P_13_1>-100.00</P_13_1>
<P_14_1>-23.00</P_14_1>
<P_15>-123.00</P_15>

<!-- Correction in plus: increasing net by 50 PLN at 23% -->
<P_13_1>50.00</P_13_1>
<P_14_1>11.50</P_14_1>
<P_15>61.50</P_15>

FaWiersz Correction Methods

Method 1, delta (difference only). Simplest, for plain amount changes:

<FaWiersz>
  <NrWierszaFa>1</NrWierszaFa>
  <P_7>Product A</P_7>
  <P_8B>-1</P_8B>
  <P_9A>90.00</P_9A>
  <P_11>-90.00</P_11>
  <P_12>23</P_12>
</FaWiersz>

Method 2, before/after with StanPrzed. Recommended when changing the VAT rate or currency:

<!-- Before state -->
<FaWiersz>
  <NrWierszaFa>1</NrWierszaFa>
  <P_7>Product A</P_7>
  <P_8B>3</P_8B>
  <P_9A>90.00</P_9A>
  <P_11>270.00</P_11>
  <P_12>23</P_12>
  <StanPrzed>1</StanPrzed>
</FaWiersz>
<!-- After state (no StanPrzed) -->
<FaWiersz>
  <NrWierszaFa>1</NrWierszaFa>
  <P_7>Product A</P_7>
  <P_8B>2</P_8B>
  <P_9A>90.00</P_9A>
  <P_11>180.00</P_11>
  <P_12>23</P_12>
</FaWiersz>

With StanPrzed, duplicate NrWierszaFa values are expected. The validator skips DUPLICATE_LINE_NUMBERS and NEGATIVE_QUANTITY_NOT_ALLOWED for corrective types.

Method 3, storno. Like StanPrzed but without the flag, using negative values:

<!-- Reversal of original (negative quantity) -->
<FaWiersz>
  <NrWierszaFa>1</NrWierszaFa>
  <P_7>Product A</P_7>
  <P_8B>-3</P_8B>
  <P_9A>90.00</P_9A>
  <P_11>-270.00</P_11>
  <P_12>23</P_12>
</FaWiersz>
<!-- Corrected state (positive) -->
<FaWiersz>
  <NrWierszaFa>2</NrWierszaFa>
  <P_7>Product A</P_7>
  <P_8B>2</P_8B>
  <P_9A>90.00</P_9A>
  <P_11>180.00</P_11>
  <P_12>23</P_12>
</FaWiersz>

Wrong Buyer NIP: Two-Document Flow

A wrong NIP cannot be corrected with a standard corrective invoice. Generate two documents.

Document 1, correction to zero:

<!-- Podmiot2 = the WRONG buyer (same as original) -->
<Podmiot2>
  <DaneIdentyfikacyjne>
    <NIP>WRONG_NIP</NIP>
    <Nazwa>Wrong Buyer Name</Nazwa>
  </DaneIdentyfikacyjne>
  ...
</Podmiot2>
<!-- All amounts negated -->
<P_13_1>-1000.00</P_13_1>
<P_14_1>-230.00</P_14_1>
<P_15>-1230.00</P_15>
<RodzajFaktury>KOR</RodzajFaktury>
<PrzyczynaKorekty>Błędny NIP nabywcy</PrzyczynaKorekty>

Document 2, new invoice with the correct NIP:

<!-- Podmiot2 = the CORRECT buyer -->
<Podmiot2>
  <DaneIdentyfikacyjne>
    <NIP>CORRECT_NIP</NIP>
    <Nazwa>Correct Buyer Name</Nazwa>
  </DaneIdentyfikacyjne>
  ...
</Podmiot2>
<RodzajFaktury>VAT</RodzajFaktury>
<!-- Full original amounts (positive) -->

Podmiot1K and Podmiot2K: Data Corrections

When correcting seller or buyer data (not NIP), use the K-variant elements:

Podmiot1K holds the old seller data from the original invoice:

<Podmiot1K>
  <DaneIdentyfikacyjne>
    <NIP>1234563218</NIP>
    <Nazwa>Old Company Name</Nazwa>
  </DaneIdentyfikacyjne>
  <Adres>
    <KodKraju>PL</KodKraju>
    <AdresL1>Old Address</AdresL1>
  </Adres>
</Podmiot1K>

Podmiot2K holds the old buyer data from the original invoice:

<Podmiot2K>
  <DaneIdentyfikacyjne>
    <NIP>9876543210</NIP>
    <Nazwa>Old Buyer Name</Nazwa>
  </DaneIdentyfikacyjne>
  <Adres>
    <KodKraju>PL</KodKraju>
    <AdresL1>Old Buyer Address</AdresL1>
  </Adres>
  <IDNabywcy>buyer-001</IDNabywcy>  <!-- links to Podmiot2, max 32 chars -->
</Podmiot2K>

When Podmiot2K is present, Podmiot2 must also include IDNabywcy with the same value. The correct data goes in Podmiot1/Podmiot2 as usual.

Batch Corrections (Korekta Zbiorcza)

For corrections covering multiple original invoices (e.g., quarterly rebate):

<RodzajFaktury>KOR</RodzajFaktury>
<PrzyczynaKorekty>Opust za I kwartał 2026</PrzyczynaKorekty>
<DaneFaKorygowanej>
  <DataWystFaKorygowanej>2026-01-15</DataWystFaKorygowanej>
  <NrFaKorygowanej>FV/001/01/2026</NrFaKorygowanej>
  <NrKSeF>1</NrKSeF>
  <NrKSeFFaKorygowanej>...</NrKSeFFaKorygowanej>
</DaneFaKorygowanej>
<DaneFaKorygowanej>
  <DataWystFaKorygowanej>2026-02-10</DataWystFaKorygowanej>
  <NrFaKorygowanej>FV/005/02/2026</NrFaKorygowanej>
  <NrKSeF>1</NrKSeF>
  <NrKSeFFaKorygowanej>...</NrKSeFFaKorygowanej>
</DaneFaKorygowanej>
<OkresFaKorygowanej>styczeń–marzec 2026</OkresFaKorygowanej>

DaneFaKorygowanej can appear up to 50,000 times. OkresFaKorygowanej is a free-text period description.

When the correction covers all deliveries in the period, FaWiersz can be omitted. When it covers only some items, include FaWiersz with P_7 naming the corrected goods or services.

KOR_ZAL: Corrective Advance Invoice

Same as KOR, plus:

• KursWalutyZ at Fa level is valid (for foreign currency advances)
• P_15ZK: advance amount before correction
• If correcting order details: include Zamowienie with before/after state
• WartoscZamowienia in correction = correct order value after correction

KOR_ROZ: Corrective Settlement Invoice

Same as KOR, plus:

• P_15ZK: settlement amount before correction
• FakturaZaliczkowa: references to the advance invoice(s) remain as in the original ROZ

---

Chaining Multiple Corrections

When correcting an already-corrected invoice:

1. DaneFaKorygowanej always references the original invoice, not the previous correction.
2. Deltas are relative to the current state (original plus all previous corrections).

Example: original 1000 net, correction 1 = -100 (to 900), correction 2 = -200 (to 700). Correction 2 references the original in DaneFaKorygowanej and has P_13_1 = -200.

---

Validation

Validate the result:

npx @ksefuj/validator correction.xml

Validator codes that matter for corrective invoices:

• RODZAJ_FAKTURY_SECTIONS: KOR, KOR_ZAL and KOR_ROZ require DaneFaKorygowanej
• KOR_NRKSEF_CONSISTENCY: exactly one of NrKSeF/NrKSeFN
• REVERSE_CHARGE_CONSISTENCY: P_18 must match the line-level rate codes
• TAX_CALCULATION_MISMATCH, DUPLICATE_LINE_NUMBERS, NEGATIVE_QUANTITY_NOT_ALLOWED: skipped for corrective types, because deltas, repeated line numbers and negative quantities are expected
• PODMIOT2_JST_MISSING, PODMIOT2_GV_MISSING: Podmiot2 always needs JST and GV
• KURS_WALUTY_Z_PLACEMENT: Fa/KursWalutyZ is valid only on ZAL and KOR_ZAL

---

Constraints

• A buyer NIP is never changed by a correction: zero the invoice and reissue.
• Noty korygujące (buyer-issued correction notes) no longer exist since 1 February 2026. All corrections are corrective invoices issued by the seller.
• Once in KSeF, an invoice cannot be edited or deleted. It is stored for 10 years.
• A test invoice sent to production is a real invoice. If one was sent by mistake, correct it to zero immediately.
• If data is ambiguous or missing, ask the user. Do not guess or insert placeholder values.