[1.8] Audit and complete KSeF v2.0 (Polish national e-invoice format)

[nielsdrost7]

Context

KSeF (Krajowy System e-Faktur) is Poland's national e-invoice system. It is mandatory for VAT-registered Polish businesses (B2B and B2G). Invoices are submitted to the KSeF hub operated by the Polish tax authority (Ministerstwo Finansów), which assigns each invoice a unique KSeF number.

Repository status (develop branch):

File	Status
application/helpers/XMLconfigs/Ksefv20.php	Exists
application/libraries/XMLtemplates/Ksefv20Xml.php	Exists

Both files already exist. This issue was not included in the original 1.8 planning because the implementation was not known at the time. The task is to audit and verify the existing implementation, not create from scratch.

KSeF is separate from Peppol and from all other standards covered in #16–#61. KSeF uses its own FA(2) XML schema defined by the Polish Ministry of Finance. Invoices are not delivered directly to the recipient — they must be submitted to KSeF, which stamps and forwards them.

---

What KSeF requires

• Polish NIP (tax identification number) for both seller and buyer: 10 digits, no country prefix in the raw number (though PL prefix is used in international contexts)
• KSeF authentication: Direct submission requires a qualified electronic signature or a token issued by KSeF — this is outside InvoicePlane's scope; export the XML and submit via the KSeF API or web interface
• Unique invoice numbering system as defined by the FA(2) schema
• The output file is a structured XML conforming to the FA(2) XSD published by the Polish Ministry of Finance

---

Deliverables

Audit existing files

• application/helpers/XMLconfigs/Ksefv20.php — verify countrycode: 'PL', XMLname, all required config keys
• application/libraries/XMLtemplates/Ksefv20Xml.php — verify generated XML validates against the FA(2) v2.0 XSD

Documentation

Add KSeF to the wiki's e-invoicing documentation:

• Add Poland row to the country → standard lookup table
• Link from the standards overview page
• Note that submission to KSeF (authentication, API call) is external to InvoicePlane

---

Acceptance criteria

• Config and generator audited; all required KSeF FA(2) elements present
• Generated XML validates against FA(2) v2.0 XSD (published by Ministerstwo Finansów)
• countrycode = 'PL' confirmed in config
• Wiki documentation updated to include Poland / KSeF
• Missing Polish NIP blocks generation with a clear error (see [1.8] Validate required fields per e-invoice standard before XML generation #21 — add KSeF to the validation matrix)

---

AAA tests

Test 1 — standard B2B invoice

Arrange: Polish B2B client with client_vat_id = 'PL1234567890'; standard invoice with two line items at 23% VAT (Polish standard rate)
Act: Generate KSeF v2.0 XML via Ksefv20.php + Ksefv20Xml.php
Assert:

• XML is well-formed
• Validates against FA(2) v2.0 XSD
• Seller and buyer NIP numbers present in correct elements

---

Test 2 — missing Polish NIP blocks generation

Arrange: Polish client with client_vat_id = NULL
Act: Attempt to generate KSeF XML
Assert: Validation error returned — "Tax ID is required for KSeF"; no XML file produced

---

Test 3 — credit note

Arrange: Credit note referencing an original KSeF invoice (must include the original KSeF number if available)
Act: Generate KSeF XML
Assert: Correct document type; original invoice reference present; XML validates