/** * @ksefuj/validator - Error code registry * * Comprehensive catalog of all validation errors, warnings, and issues * that can be detected in KSeF FA(3) XML documents. * * All 38 semantic validation error codes are included, each with detailed * descriptions, common causes, and fix suggestions based on the official * FA(3) information sheet from the Ministry of Finance. */ import type { ErrorCodeDefinition, FixSuggestion } from "./types.js"; export declare const XSD_ERRORS: { readonly SCHEMA_VALIDATION_FAILED: { readonly code: { readonly domain: "xsd"; readonly category: "schema"; readonly code: "SCHEMA_VALIDATION_FAILED"; readonly severity: "error"; }; readonly description: "XML does not conform to FA(3) XSD schema"; readonly commonCauses: readonly ["Invalid element order", "Missing required elements", "Invalid element values", "Wrong namespace"]; readonly fixTemplates: readonly []; }; readonly ELEMENT_NOT_ALLOWED: { readonly code: { readonly domain: "xsd"; readonly category: "schema"; readonly code: "ELEMENT_NOT_ALLOWED"; readonly severity: "error"; }; readonly description: "Element not allowed at this location"; readonly commonCauses: readonly ["Element in wrong parent", "Typo in element name", "Wrong element order"]; readonly fixTemplates: readonly []; }; readonly REQUIRED_ELEMENT_MISSING: { readonly code: { readonly domain: "xsd"; readonly category: "schema"; readonly code: "REQUIRED_ELEMENT_MISSING"; readonly severity: "error"; }; readonly description: "Required element missing according to schema"; readonly commonCauses: readonly ["Mandatory element not provided", "Incomplete structure"]; readonly fixTemplates: readonly []; }; readonly INVALID_ELEMENT_VALUE: { readonly code: { readonly domain: "xsd"; readonly category: "schema"; readonly code: "INVALID_ELEMENT_VALUE"; readonly severity: "error"; }; readonly description: "Element value does not match schema constraints"; readonly commonCauses: readonly ["Value outside allowed range", "Wrong data type", "Pattern mismatch"]; readonly fixTemplates: readonly []; }; }; export declare const PARSE_ERRORS: { readonly MALFORMED_XML: { readonly code: { readonly domain: "parse"; readonly category: "syntax"; readonly code: "MALFORMED_XML"; readonly severity: "error"; }; readonly description: "XML is not well-formed"; readonly commonCauses: readonly ["Missing closing tags", "Invalid characters", "Mismatched tags", "Invalid XML declaration"]; readonly fixTemplates: readonly []; }; readonly XML_DISCOURAGED_CHARACTER: { readonly code: { readonly domain: "parse"; readonly category: "ksef_strict_xml"; readonly code: "XML_DISCOURAGED_CHARACTER"; readonly severity: "error"; }; readonly description: "Character discouraged by the W3C XML spec ([#x7F-#x84], [#x86-#x9F], [#xFDD0-#xFDEF], [#xNFFFE-#xNFFFF]); KSeF rejects such invoices from 2026-10-19 (KSeF API 2.4.0, Weryfikacja faktury)"; readonly commonCauses: readonly ["C1 control characters (U+0080-U+009F) pasted from Word, PDF or a legacy system", "Noncharacters from a corrupted export or a wrong text conversion"]; readonly fixTemplates: readonly []; }; readonly XML_PROCESSING_INSTRUCTION: { readonly code: { readonly domain: "parse"; readonly category: "ksef_strict_xml"; readonly code: "XML_PROCESSING_INSTRUCTION"; readonly severity: "error"; }; readonly description: "XML processing instruction (e.g. xml-stylesheet); KSeF rejects such invoices from 2026-10-19 (KSeF API 2.4.0, Weryfikacja faktury)"; readonly commonCauses: readonly ["An integrator adds to attach a visualisation", "Another tool injects a custom processing instruction"]; readonly fixTemplates: readonly []; }; readonly XML_DISCOURAGED_CHARACTER_MORE: { readonly code: { readonly domain: "parse"; readonly category: "ksef_strict_xml"; readonly code: "XML_DISCOURAGED_CHARACTER_MORE"; readonly severity: "error"; }; readonly description: "Summary: further discouraged characters beyond the individually reported ones"; readonly commonCauses: readonly []; readonly fixTemplates: readonly []; }; readonly XML_PROCESSING_INSTRUCTION_MORE: { readonly code: { readonly domain: "parse"; readonly category: "ksef_strict_xml"; readonly code: "XML_PROCESSING_INSTRUCTION_MORE"; readonly severity: "error"; }; readonly description: "Summary: further processing instructions beyond the individually reported ones"; readonly commonCauses: readonly []; readonly fixTemplates: readonly []; }; readonly XML_BOM_PRESENT: { readonly code: { readonly domain: "parse"; readonly category: "ksef_strict_xml"; readonly code: "XML_BOM_PRESENT"; readonly severity: "error"; }; readonly description: "File starts with a UTF-8 BOM; KSeF requires UTF-8 without BOM (Weryfikacja faktury)"; readonly commonCauses: readonly ["File saved as \"UTF-8 with BOM\" (e.g. Notepad, Excel exports)"]; readonly fixTemplates: readonly []; }; readonly XML_ENCODING_NOT_UTF8: { readonly code: { readonly domain: "parse"; readonly category: "ksef_strict_xml"; readonly code: "XML_ENCODING_NOT_UTF8"; readonly severity: "error"; }; readonly description: "XML declaration names an encoding other than UTF-8; KSeF requires UTF-8 (Weryfikacja faktury)"; readonly commonCauses: readonly ["Declaration copied from a legacy template with encoding=\"windows-1250\" or \"ISO-8859-2\""]; readonly fixTemplates: readonly []; }; readonly ENCODING_ERROR: { readonly code: { readonly domain: "parse"; readonly category: "encoding"; readonly code: "ENCODING_ERROR"; readonly severity: "error"; }; readonly description: "Character encoding error"; readonly commonCauses: readonly ["Invalid UTF-8 sequences", "Wrong encoding declaration"]; readonly fixTemplates: readonly []; }; }; export declare const INFRASTRUCTURE_ERRORS: { readonly VALIDATOR_INITIALIZATION_FAILED: { readonly code: { readonly domain: "infrastructure"; readonly category: "system"; readonly code: "VALIDATOR_INITIALIZATION_FAILED"; readonly severity: "error"; }; readonly description: "Failed to initialize validation system"; readonly commonCauses: readonly ["Schema loading failed", "Memory allocation error", "System resource unavailable"]; readonly fixTemplates: readonly []; }; readonly VALIDATION_TIMEOUT: { readonly code: { readonly domain: "infrastructure"; readonly category: "system"; readonly code: "VALIDATION_TIMEOUT"; readonly severity: "error"; }; readonly description: "Validation exceeded time limit"; readonly commonCauses: readonly ["Very large document", "Complex validation rules", "System overload"]; readonly fixTemplates: readonly []; }; readonly EXECUTION_ERROR: { readonly code: { readonly domain: "infrastructure"; readonly category: "system"; readonly code: "EXECUTION_ERROR"; readonly severity: "error"; }; readonly description: "Unexpected error during validation execution"; readonly commonCauses: readonly ["Runtime environment issue", "Unhandled exception in validation logic", "System resource exhaustion"]; readonly fixTemplates: readonly []; }; }; export declare const SEMANTIC_ERRORS: { readonly PODMIOT2_JST_MISSING: { readonly code: { readonly domain: "semantic"; readonly category: "required_field"; readonly code: "PODMIOT2_JST_MISSING"; readonly severity: "error"; }; readonly description: "JST element is mandatory in Podmiot2 (§6.1)"; readonly commonCauses: readonly ["Missing JST element in Podmiot2", "Element not provided"]; readonly fixTemplates: readonly [{ readonly type: "add"; readonly targetXPath: "//*[local-name()='Podmiot2']"; readonly content: "2"; readonly description: "Add JST element with value 2 (not a local government unit)"; readonly confidence: 0.9; readonly dependencies: readonly []; }]; }; readonly PODMIOT2_GV_MISSING: { readonly code: { readonly domain: "semantic"; readonly category: "required_field"; readonly code: "PODMIOT2_GV_MISSING"; readonly severity: "error"; }; readonly description: "GV element is mandatory in Podmiot2 (§6.1)"; readonly commonCauses: readonly ["Missing GV element in Podmiot2", "Element not provided"]; readonly fixTemplates: readonly [{ readonly type: "add"; readonly targetXPath: "//*[local-name()='Podmiot2']"; readonly content: "2"; readonly description: "Add GV element with value 2 (not a VAT group)"; readonly confidence: 0.9; readonly dependencies: readonly []; }]; }; readonly JST_REQUIRES_PODMIOT3: { readonly code: { readonly domain: "semantic"; readonly category: "consistency"; readonly code: "JST_REQUIRES_PODMIOT3"; readonly severity: "error"; }; readonly description: "When Podmiot2/JST = '1', at least one Podmiot3 must exist with Rola = '8' (§6.1, Appendix D #3)"; readonly commonCauses: readonly ["Invoice issued for local government unit but missing Podmiot3 with role 8", "JST incorrectly set to 1 when not actually a local government unit"]; readonly fixTemplates: readonly []; }; readonly GV_REQUIRES_PODMIOT3: { readonly code: { readonly domain: "semantic"; readonly category: "consistency"; readonly code: "GV_REQUIRES_PODMIOT3"; readonly severity: "error"; }; readonly description: "When Podmiot2/GV = '1', at least one Podmiot3 must exist with Rola = '10' (§6.1, Appendix D #3)"; readonly commonCauses: readonly ["Invoice issued for VAT group but missing Podmiot3 with role 10", "GV incorrectly set to 1 when not actually a VAT group"]; readonly fixTemplates: readonly []; }; readonly NIP_IN_WRONG_FIELD: { readonly code: { readonly domain: "semantic"; readonly category: "business_logic"; readonly code: "NIP_IN_WRONG_FIELD"; readonly severity: "warning"; }; readonly description: "Polish NIP detected in NrVatUE field - must be in NIP field for purchaser KSeF access (§2.10, §6.2)"; readonly commonCauses: readonly ["Polish NIP (10 digits) incorrectly placed in NrVatUE field", "Using EU VAT field for Polish tax number"]; readonly fixTemplates: readonly []; }; readonly PODMIOT3_UDZIAL_REQUIRES_ROLE_4: { readonly code: { readonly domain: "semantic"; readonly category: "consistency"; readonly code: "PODMIOT3_UDZIAL_REQUIRES_ROLE_4"; readonly severity: "error"; }; readonly description: "Udzial element on Podmiot3 is only permitted when Rola = '4' (§7.2)"; readonly commonCauses: readonly ["Udzial (share) specified for wrong entity role", "Should only be used for property rights holder (role 4)"]; readonly fixTemplates: readonly []; }; readonly PODMIOT3_ROLE_MISSING: { readonly code: { readonly domain: "semantic"; readonly category: "required_field"; readonly code: "PODMIOT3_ROLE_MISSING"; readonly severity: "error"; }; readonly description: "When Podmiot3 has no Rola, both RolaInna and OpisRoli must be present. When RolaInna = '1', OpisRoli is mandatory (§7.3)"; readonly commonCauses: readonly ["Missing role definition for Podmiot3", "RolaInna = 1 but OpisRoli not provided"]; readonly fixTemplates: readonly []; }; readonly SELF_BILLING_PODMIOT3_CONFLICT: { readonly code: { readonly domain: "semantic"; readonly category: "business_logic"; readonly code: "SELF_BILLING_PODMIOT3_CONFLICT"; readonly severity: "warning"; }; readonly description: "Self-billing (P_17 = '1'): purchaser data belongs in Podmiot2, not Podmiot3 with Rola = '5' (§7.3, §9.6)"; readonly commonCauses: readonly ["Self-billing invoice has invoice issuer role in Podmiot3", "Purchaser incorrectly placed in Podmiot3 instead of Podmiot2"]; readonly fixTemplates: readonly []; }; readonly P15_MISSING: { readonly code: { readonly domain: "semantic"; readonly category: "required_field"; readonly code: "P15_MISSING"; readonly severity: "error"; }; readonly description: "P_15 (total amount due) is mandatory in Fa (§9.4)"; readonly commonCauses: readonly ["Missing P_15 element", "Total amount not calculated"]; readonly fixTemplates: readonly []; }; readonly P6_P6A_MUTUAL_EXCLUSION: { readonly code: { readonly domain: "semantic"; readonly category: "consistency"; readonly code: "P6_P6A_MUTUAL_EXCLUSION"; readonly severity: "error"; }; readonly description: "P_6 (common delivery date) and P_6A (per-line delivery date) are mutually exclusive (§9.2, §10.2, Appendix D #8)"; readonly commonCauses: readonly ["Both P_6 in Fa and P_6A in FaWiersz are present", "Mixed delivery date specification"]; readonly fixTemplates: readonly []; }; readonly RODZAJ_FAKTURY_SECTIONS: { readonly code: { readonly domain: "semantic"; readonly category: "consistency"; readonly code: "RODZAJ_FAKTURY_SECTIONS"; readonly severity: "error"; }; readonly description: "Invoice type determines required sections: KOR/KOR_ZAL/KOR_ROZ → DaneFaKorygowanej; ZAL → Zamowienie; ROZ → FakturaZaliczkowa (§9.5, §9.7, §9.9, §14)"; readonly commonCauses: readonly ["Corrective invoice missing DaneFaKorygowanej section", "Advance invoice missing Zamowienie section", "Final invoice missing FakturaZaliczkowa section"]; readonly fixTemplates: readonly []; }; readonly KURS_WALUTY_Z_PLACEMENT: { readonly code: { readonly domain: "semantic"; readonly category: "business_logic"; readonly code: "KURS_WALUTY_Z_PLACEMENT"; readonly severity: "error"; }; readonly description: "KursWalutyZ at Fa level is ONLY valid for advance invoices (RodzajFaktury = ZAL or KOR_ZAL) (§9.2, §9.5)"; readonly commonCauses: readonly ["Exchange rate placed at wrong level for non-advance invoice", "Should be in FaWiersz/KursWaluty for regular invoices"]; readonly fixTemplates: readonly []; }; readonly FOREIGN_CURRENCY_TAX_PLN: { readonly code: { readonly domain: "semantic"; readonly category: "business_logic"; readonly code: "FOREIGN_CURRENCY_TAX_PLN"; readonly severity: "warning"; }; readonly description: "Foreign currency invoice with tax amounts should include PLN conversions in P_14_*W fields (§9.3)"; readonly commonCauses: readonly ["Missing PLN tax conversion for foreign currency invoice", "P_14_*W fields not provided when KodWaluty ≠ PLN"]; readonly fixTemplates: readonly []; }; readonly ADNOTACJE_P16_MISSING: { readonly code: { readonly domain: "semantic"; readonly category: "required_field"; readonly code: "ADNOTACJE_P16_MISSING"; readonly severity: "error"; }; readonly description: "P_16 is mandatory in Adnotacje (§9.6)"; readonly commonCauses: readonly ["Missing P_16 element in Adnotacje"]; readonly fixTemplates: readonly [{ readonly type: "add"; readonly targetXPath: "//*[local-name()='Adnotacje']"; readonly content: "2"; readonly description: "Add P_16 with value 2 (no significant terms agreed)"; readonly confidence: 0.9; readonly dependencies: readonly []; }]; }; readonly ADNOTACJE_P17_MISSING: { readonly code: { readonly domain: "semantic"; readonly category: "required_field"; readonly code: "ADNOTACJE_P17_MISSING"; readonly severity: "error"; }; readonly description: "P_17 is mandatory in Adnotacje (§9.6)"; readonly commonCauses: readonly ["Missing P_17 element in Adnotacje"]; readonly fixTemplates: readonly [{ readonly type: "add"; readonly targetXPath: "//*[local-name()='Adnotacje']"; readonly content: "2"; readonly description: "Add P_17 with value 2 (not self-billing)"; readonly confidence: 0.9; readonly dependencies: readonly []; }]; }; readonly ADNOTACJE_P18_MISSING: { readonly code: { readonly domain: "semantic"; readonly category: "required_field"; readonly code: "ADNOTACJE_P18_MISSING"; readonly severity: "error"; }; readonly description: "P_18 is mandatory in Adnotacje (§9.6)"; readonly commonCauses: readonly ["Missing P_18 element in Adnotacje"]; readonly fixTemplates: readonly [{ readonly type: "add"; readonly targetXPath: "//*[local-name()='Adnotacje']"; readonly content: "2"; readonly description: "Add P_18 with value 2 (not reverse charge)"; readonly confidence: 0.9; readonly dependencies: readonly []; }]; }; readonly ADNOTACJE_P18A_MISSING: { readonly code: { readonly domain: "semantic"; readonly category: "required_field"; readonly code: "ADNOTACJE_P18A_MISSING"; readonly severity: "error"; }; readonly description: "P_18A is mandatory in Adnotacje (§9.6)"; readonly commonCauses: readonly ["Missing P_18A element in Adnotacje"]; readonly fixTemplates: readonly [{ readonly type: "add"; readonly targetXPath: "//*[local-name()='Adnotacje']"; readonly content: "2"; readonly description: "Add P_18A with value 2 (not split payment mechanism)"; readonly confidence: 0.9; readonly dependencies: readonly []; }]; }; readonly ADNOTACJE_ZWOLNIENIE_MISSING: { readonly code: { readonly domain: "semantic"; readonly category: "required_field"; readonly code: "ADNOTACJE_ZWOLNIENIE_MISSING"; readonly severity: "error"; }; readonly description: "Zwolnienie element is mandatory in Adnotacje (§9.6)"; readonly commonCauses: readonly ["Missing Zwolnienie element in Adnotacje"]; readonly fixTemplates: readonly [{ readonly type: "add"; readonly targetXPath: "//*[local-name()='Adnotacje']"; readonly content: "1"; readonly description: "Add Zwolnienie element indicating no exemptions"; readonly confidence: 0.9; readonly dependencies: readonly []; }]; }; readonly ADNOTACJE_NST_MISSING: { readonly code: { readonly domain: "semantic"; readonly category: "required_field"; readonly code: "ADNOTACJE_NST_MISSING"; readonly severity: "error"; }; readonly description: "NoweSrodkiTransportu element is mandatory in Adnotacje (§9.6)"; readonly commonCauses: readonly ["Missing NoweSrodkiTransportu element in Adnotacje"]; readonly fixTemplates: readonly [{ readonly type: "add"; readonly targetXPath: "//*[local-name()='Adnotacje']"; readonly content: "1"; readonly description: "Add NoweSrodkiTransportu element indicating no new means of transport"; readonly confidence: 0.9; readonly dependencies: readonly []; }]; }; readonly ADNOTACJE_P23_MISSING: { readonly code: { readonly domain: "semantic"; readonly category: "required_field"; readonly code: "ADNOTACJE_P23_MISSING"; readonly severity: "error"; }; readonly description: "P_23 is mandatory in Adnotacje (§9.6)"; readonly commonCauses: readonly ["Missing P_23 element in Adnotacje"]; readonly fixTemplates: readonly [{ readonly type: "add"; readonly targetXPath: "//*[local-name()='Adnotacje']"; readonly content: "2"; readonly description: "Add P_23 with value 2 (no procedural annotations)"; readonly confidence: 0.9; readonly dependencies: readonly []; }]; }; readonly ADNOTACJE_PMARZY_MISSING: { readonly code: { readonly domain: "semantic"; readonly category: "required_field"; readonly code: "ADNOTACJE_PMARZY_MISSING"; readonly severity: "error"; }; readonly description: "PMarzy element is mandatory in Adnotacje (§9.6)"; readonly commonCauses: readonly ["Missing PMarzy element in Adnotacje"]; readonly fixTemplates: readonly [{ readonly type: "add"; readonly targetXPath: "//*[local-name()='Adnotacje']"; readonly content: "1"; readonly description: "Add PMarzy element indicating no margin procedure"; readonly confidence: 0.9; readonly dependencies: readonly []; }]; }; readonly ZWOLNIENIE_LOGIC: { readonly code: { readonly domain: "semantic"; readonly category: "consistency"; readonly code: "ZWOLNIENIE_LOGIC"; readonly severity: "error"; }; readonly description: "Zwolnienie: exactly one of P_19 or P_19N required. If P_19 = '1', exactly one of P_19A/B/C required (§9.6)"; readonly commonCauses: readonly ["Both P_19 and P_19N present or both missing", "P_19 = 1 but exemption basis not specified", "P_19N = 1 but exemption fields present"]; readonly fixTemplates: readonly []; }; readonly NST_LOGIC: { readonly code: { readonly domain: "semantic"; readonly category: "consistency"; readonly code: "NST_LOGIC"; readonly severity: "error"; }; readonly description: "NoweSrodkiTransportu: exactly one of P_22 or P_22N required. If P_22 = '1', P_42_5 and NowySrodekTransportu required (§9.6)"; readonly commonCauses: readonly ["Both P_22 and P_22N present or both missing", "P_22 = 1 but vehicle details not provided", "P_22N = 1 but vehicle fields present"]; readonly fixTemplates: readonly []; }; readonly PMARZY_LOGIC: { readonly code: { readonly domain: "semantic"; readonly category: "consistency"; readonly code: "PMARZY_LOGIC"; readonly severity: "error"; }; readonly description: "PMarzy: exactly one of P_PMarzy or P_PMarzyN required. If P_PMarzy = '1', exactly one procedure type required (§9.6)"; readonly commonCauses: readonly ["Both P_PMarzy and P_PMarzyN present or both missing", "P_PMarzy = 1 but procedure type not specified", "P_PMarzyN = 1 but margin fields present"]; readonly fixTemplates: readonly []; }; readonly P12_ENUMERATION: { readonly code: { readonly domain: "semantic"; readonly category: "business_logic"; readonly code: "P12_ENUMERATION"; readonly severity: "error"; }; readonly description: "P_12 must be one of: 23, 22, 8, 7, 5, 4, 3, 0 KR, 0 WDT, 0 EX, zw, oo, np I, np II (§10.3)"; readonly commonCauses: readonly ["Invalid tax rate code", "Using percentage instead of code", "Typo in rate code"]; readonly fixTemplates: readonly []; }; readonly OO_RATE_FOREIGN_BUYER: { readonly code: { readonly domain: "semantic"; readonly category: "business_logic"; readonly code: "OO_RATE_FOREIGN_BUYER"; readonly severity: "warning"; }; readonly description: "P_12 = 'oo' is for domestic reverse charge only. Use 'np I' or 'np II' for foreign buyers (§10.3, Appendix D #18)"; readonly commonCauses: readonly ["Using domestic reverse charge code for foreign entity", "Should use 'np I' or 'np II' for EU/non-EU buyers"]; readonly fixTemplates: readonly []; }; readonly GTU_FORMAT: { readonly code: { readonly domain: "semantic"; readonly category: "format"; readonly code: "GTU_FORMAT"; readonly severity: "error"; }; readonly description: "GTU value must match pattern GTU_XX (GTU_01 through GTU_13). Common error: 1 instead of GTU_12 (§10.4)"; readonly commonCauses: readonly ["Wrong GTU element format", "Using GTU code as element name instead of value", "Invalid GTU code number"]; readonly fixTemplates: readonly []; }; readonly DECIMAL_PRECISION: { readonly code: { readonly domain: "semantic"; readonly category: "format"; readonly code: "DECIMAL_PRECISION"; readonly severity: "error"; }; readonly description: "Amount field exceeds maximum decimal precision defined in §2.6 of FA(3) specification"; readonly commonCauses: readonly ["Unit price has more than 8 decimal places", "General amount has more than 2 decimal places", "Quantity or exchange rate has more than 6 decimal places", "System generating excessive decimal precision"]; readonly fixTemplates: readonly []; }; readonly KOR_NRKSEF_CONSISTENCY: { readonly code: { readonly domain: "semantic"; readonly category: "consistency"; readonly code: "KOR_NRKSEF_CONSISTENCY"; readonly severity: "error"; }; readonly description: "DaneFaKorygowanej: exactly one of NrKSeF/NrKSeFN = '1'. When NrKSeF = '1', NrKSeFFaKorygowanej required (§9.7)"; readonly commonCauses: readonly ["Both NrKSeF and NrKSeFN set to 1 or neither", "NrKSeF = 1 but KSeF number not provided", "NrKSeFN = 1 but KSeF fields present"]; readonly fixTemplates: readonly []; }; readonly REVERSE_CHARGE_CONSISTENCY: { readonly code: { readonly domain: "semantic"; readonly category: "consistency"; readonly code: "REVERSE_CHARGE_CONSISTENCY"; readonly severity: "warning"; }; readonly description: "Reverse charge: P_13_8/P_13_10 requires P_18 = '1', and at least one FaWiersz with P_12 in (np I, np II, oo) (§9.4, §9.6)"; readonly commonCauses: readonly ["Reverse charge amounts but P_18 not set to 1", "P_18 = 1 but no reverse charge tax rates in line items"]; readonly fixTemplates: readonly []; }; readonly PAYMENT_ZAPLACONO_DATE: { readonly code: { readonly domain: "semantic"; readonly category: "consistency"; readonly code: "PAYMENT_ZAPLACONO_DATE"; readonly severity: "warning"; }; readonly description: "When Platnosc/Zaplacono = '1', DataZaplaty must be present (§12.1)"; readonly commonCauses: readonly ["Payment marked as paid but payment date not provided"]; readonly fixTemplates: readonly []; }; readonly RACHUNEKBANKOWY_NRRB: { readonly code: { readonly domain: "semantic"; readonly category: "required_field"; readonly code: "RACHUNEKBANKOWY_NRRB"; readonly severity: "error"; }; readonly description: "When RachunekBankowy element is filled, NrRB is mandatory (nested obligation) (§2.2, §12.1, Appendix D #4)"; readonly commonCauses: readonly ["Bank account section present but account number not provided"]; readonly fixTemplates: readonly []; }; readonly NRRB_LENGTH: { readonly code: { readonly domain: "semantic"; readonly category: "format"; readonly code: "NRRB_LENGTH"; readonly severity: "warning"; }; readonly description: "NrRB must be 10–34 characters (§12.1)"; readonly commonCauses: readonly ["Bank account number too short or too long", "Invalid IBAN format"]; readonly fixTemplates: readonly []; }; readonly IPKSEF_FORMAT: { readonly code: { readonly domain: "semantic"; readonly category: "format"; readonly code: "IPKSEF_FORMAT"; readonly severity: "warning"; }; readonly description: "IPKSeF must be exactly 13 alphanumeric characters [0-9a-zA-Z] (§12.1)"; readonly commonCauses: readonly ["Invalid IPKSeF format", "Wrong length", "Non-alphanumeric characters"]; readonly fixTemplates: readonly []; }; readonly WALUTA_UMOWNA_PLN: { readonly code: { readonly domain: "semantic"; readonly category: "business_logic"; readonly code: "WALUTA_UMOWNA_PLN"; readonly severity: "error"; }; readonly description: "WalutaUmowna must NEVER be 'PLN' (§13.1, Appendix D #10)"; readonly commonCauses: readonly ["PLN incorrectly used in contract currency field"]; readonly fixTemplates: readonly []; }; readonly KURS_WALUTA_PAIR: { readonly code: { readonly domain: "semantic"; readonly category: "consistency"; readonly code: "KURS_WALUTA_PAIR"; readonly severity: "error"; }; readonly description: "KursUmowny and WalutaUmowna must both be present or both absent (§13.1, Appendix D #11)"; readonly commonCauses: readonly ["Contract exchange rate provided without currency", "Contract currency provided without exchange rate"]; readonly fixTemplates: readonly []; }; readonly TRANSPORT_MINIMUM_DATA: { readonly code: { readonly domain: "semantic"; readonly category: "consistency"; readonly code: "TRANSPORT_MINIMUM_DATA"; readonly severity: "warning"; }; readonly description: "Transport requires: (RodzajTransportu OR TransportInny+OpisInnegoTransportu) AND (OpisLadunku OR LadunekInny+OpisInnegoLadunku) (§13.2, Appendix D #17)"; readonly commonCauses: readonly ["Transport section present but minimum required data missing", "Missing transport type or cargo description"]; readonly fixTemplates: readonly []; }; readonly CURRENCY_RATE_UNVERIFIABLE: { readonly code: { readonly domain: "semantic"; readonly category: "business_logic"; readonly code: "CURRENCY_RATE_UNVERIFIABLE"; readonly severity: "warning"; }; readonly description: "KursWaluty cannot be verified — NBP rate unavailable or outside the valid date window (Art. 31a ustawy o VAT)"; readonly commonCauses: readonly ["NBP API unavailable or rate-limited during validation", "Rate data provided is from a date too far from the invoice date", "Network error during rate lookup"]; readonly fixTemplates: readonly []; }; readonly CURRENCY_RATE_MISMATCH: { readonly code: { readonly domain: "semantic"; readonly category: "business_logic"; readonly code: "CURRENCY_RATE_MISMATCH"; readonly severity: "warning"; }; readonly description: "KursWaluty does not match the NBP Table A mid-rate for the reference date (Art. 31a ustawy o VAT — the business day before the tax obligation arises, or before the issue date when the invoice precedes it)"; readonly commonCauses: readonly ["Manually entered exchange rate differs from the official NBP rate", "Rounding error in exchange rate", "Wrong date used for the exchange rate lookup — the issue date rather than the delivery or settlement-period date", "Taxpayer lawfully elected a different basis that FA(3) does not record: ECB rates (Art. 31a ust. 1) or income-tax conversion rules (Art. 31a ust. 2a)"]; readonly fixTemplates: readonly []; }; readonly AMOUNT_NO_SEPARATORS: { readonly code: { readonly domain: "semantic"; readonly category: "format"; readonly code: "AMOUNT_NO_SEPARATORS"; readonly severity: "error"; }; readonly description: "Amount fields must not contain spaces, commas, or any non-numeric characters except minus and decimal point (§2.5, Appendix D #13)"; readonly commonCauses: readonly ["Thousand separators (spaces or commas) in amount fields", "Non-numeric characters in numeric fields"]; readonly fixTemplates: readonly []; }; readonly TAX_CALCULATION_MISMATCH: { readonly code: { readonly domain: "semantic"; readonly category: "business_logic"; readonly code: "TAX_CALCULATION_MISMATCH"; readonly severity: "error"; }; readonly description: "Tax calculation error: P_14_x must equal P_13_x × (P_12 rate / 100), and P_15 must equal sum of all (P_13_x + P_14_x)"; readonly commonCauses: readonly ["Incorrect tax amount calculation", "Rounding errors in tax calculations", "Total amount does not match sum of base amounts and taxes"]; readonly fixTemplates: readonly []; }; readonly INVALID_BANK_ACCOUNT_FORMAT: { readonly code: { readonly domain: "semantic"; readonly category: "format"; readonly code: "INVALID_BANK_ACCOUNT_FORMAT"; readonly severity: "error"; }; readonly description: "Polish bank account (NrRB) must be 28 characters for IBAN format (PL + 26 digits) or 26 digits for NRB format"; readonly commonCauses: readonly ["Incorrect Polish IBAN format", "Wrong number of digits in bank account", "Missing or malformed IBAN prefix"]; readonly fixTemplates: readonly []; }; readonly DUPLICATE_LINE_NUMBERS: { readonly code: { readonly domain: "semantic"; readonly category: "consistency"; readonly code: "DUPLICATE_LINE_NUMBERS"; readonly severity: "error"; }; readonly description: "Line numbers (NrWierszaFa) must be unique within the invoice (except in corrective invoices where before/after states can share numbers)"; readonly commonCauses: readonly ["Same line number used for multiple invoice items", "Incorrect line numbering sequence"]; readonly fixTemplates: readonly []; }; readonly NEGATIVE_QUANTITY_NOT_ALLOWED: { readonly code: { readonly domain: "semantic"; readonly category: "business_logic"; readonly code: "NEGATIVE_QUANTITY_NOT_ALLOWED"; readonly severity: "error"; }; readonly description: "Negative quantities (P_8B) are only allowed in corrective invoices (RodzajFaktury = KOR, KOR_ZAL, or KOR_ROZ)"; readonly commonCauses: readonly ["Negative quantity in standard VAT invoice", "Incorrect invoice type for negative quantities"]; readonly fixTemplates: readonly []; }; }; export declare const ERROR_CODES: { readonly PODMIOT2_JST_MISSING: { readonly code: { readonly domain: "semantic"; readonly category: "required_field"; readonly code: "PODMIOT2_JST_MISSING"; readonly severity: "error"; }; readonly description: "JST element is mandatory in Podmiot2 (§6.1)"; readonly commonCauses: readonly ["Missing JST element in Podmiot2", "Element not provided"]; readonly fixTemplates: readonly [{ readonly type: "add"; readonly targetXPath: "//*[local-name()='Podmiot2']"; readonly content: "2"; readonly description: "Add JST element with value 2 (not a local government unit)"; readonly confidence: 0.9; readonly dependencies: readonly []; }]; }; readonly PODMIOT2_GV_MISSING: { readonly code: { readonly domain: "semantic"; readonly category: "required_field"; readonly code: "PODMIOT2_GV_MISSING"; readonly severity: "error"; }; readonly description: "GV element is mandatory in Podmiot2 (§6.1)"; readonly commonCauses: readonly ["Missing GV element in Podmiot2", "Element not provided"]; readonly fixTemplates: readonly [{ readonly type: "add"; readonly targetXPath: "//*[local-name()='Podmiot2']"; readonly content: "2"; readonly description: "Add GV element with value 2 (not a VAT group)"; readonly confidence: 0.9; readonly dependencies: readonly []; }]; }; readonly JST_REQUIRES_PODMIOT3: { readonly code: { readonly domain: "semantic"; readonly category: "consistency"; readonly code: "JST_REQUIRES_PODMIOT3"; readonly severity: "error"; }; readonly description: "When Podmiot2/JST = '1', at least one Podmiot3 must exist with Rola = '8' (§6.1, Appendix D #3)"; readonly commonCauses: readonly ["Invoice issued for local government unit but missing Podmiot3 with role 8", "JST incorrectly set to 1 when not actually a local government unit"]; readonly fixTemplates: readonly []; }; readonly GV_REQUIRES_PODMIOT3: { readonly code: { readonly domain: "semantic"; readonly category: "consistency"; readonly code: "GV_REQUIRES_PODMIOT3"; readonly severity: "error"; }; readonly description: "When Podmiot2/GV = '1', at least one Podmiot3 must exist with Rola = '10' (§6.1, Appendix D #3)"; readonly commonCauses: readonly ["Invoice issued for VAT group but missing Podmiot3 with role 10", "GV incorrectly set to 1 when not actually a VAT group"]; readonly fixTemplates: readonly []; }; readonly NIP_IN_WRONG_FIELD: { readonly code: { readonly domain: "semantic"; readonly category: "business_logic"; readonly code: "NIP_IN_WRONG_FIELD"; readonly severity: "warning"; }; readonly description: "Polish NIP detected in NrVatUE field - must be in NIP field for purchaser KSeF access (§2.10, §6.2)"; readonly commonCauses: readonly ["Polish NIP (10 digits) incorrectly placed in NrVatUE field", "Using EU VAT field for Polish tax number"]; readonly fixTemplates: readonly []; }; readonly PODMIOT3_UDZIAL_REQUIRES_ROLE_4: { readonly code: { readonly domain: "semantic"; readonly category: "consistency"; readonly code: "PODMIOT3_UDZIAL_REQUIRES_ROLE_4"; readonly severity: "error"; }; readonly description: "Udzial element on Podmiot3 is only permitted when Rola = '4' (§7.2)"; readonly commonCauses: readonly ["Udzial (share) specified for wrong entity role", "Should only be used for property rights holder (role 4)"]; readonly fixTemplates: readonly []; }; readonly PODMIOT3_ROLE_MISSING: { readonly code: { readonly domain: "semantic"; readonly category: "required_field"; readonly code: "PODMIOT3_ROLE_MISSING"; readonly severity: "error"; }; readonly description: "When Podmiot3 has no Rola, both RolaInna and OpisRoli must be present. When RolaInna = '1', OpisRoli is mandatory (§7.3)"; readonly commonCauses: readonly ["Missing role definition for Podmiot3", "RolaInna = 1 but OpisRoli not provided"]; readonly fixTemplates: readonly []; }; readonly SELF_BILLING_PODMIOT3_CONFLICT: { readonly code: { readonly domain: "semantic"; readonly category: "business_logic"; readonly code: "SELF_BILLING_PODMIOT3_CONFLICT"; readonly severity: "warning"; }; readonly description: "Self-billing (P_17 = '1'): purchaser data belongs in Podmiot2, not Podmiot3 with Rola = '5' (§7.3, §9.6)"; readonly commonCauses: readonly ["Self-billing invoice has invoice issuer role in Podmiot3", "Purchaser incorrectly placed in Podmiot3 instead of Podmiot2"]; readonly fixTemplates: readonly []; }; readonly P15_MISSING: { readonly code: { readonly domain: "semantic"; readonly category: "required_field"; readonly code: "P15_MISSING"; readonly severity: "error"; }; readonly description: "P_15 (total amount due) is mandatory in Fa (§9.4)"; readonly commonCauses: readonly ["Missing P_15 element", "Total amount not calculated"]; readonly fixTemplates: readonly []; }; readonly P6_P6A_MUTUAL_EXCLUSION: { readonly code: { readonly domain: "semantic"; readonly category: "consistency"; readonly code: "P6_P6A_MUTUAL_EXCLUSION"; readonly severity: "error"; }; readonly description: "P_6 (common delivery date) and P_6A (per-line delivery date) are mutually exclusive (§9.2, §10.2, Appendix D #8)"; readonly commonCauses: readonly ["Both P_6 in Fa and P_6A in FaWiersz are present", "Mixed delivery date specification"]; readonly fixTemplates: readonly []; }; readonly RODZAJ_FAKTURY_SECTIONS: { readonly code: { readonly domain: "semantic"; readonly category: "consistency"; readonly code: "RODZAJ_FAKTURY_SECTIONS"; readonly severity: "error"; }; readonly description: "Invoice type determines required sections: KOR/KOR_ZAL/KOR_ROZ → DaneFaKorygowanej; ZAL → Zamowienie; ROZ → FakturaZaliczkowa (§9.5, §9.7, §9.9, §14)"; readonly commonCauses: readonly ["Corrective invoice missing DaneFaKorygowanej section", "Advance invoice missing Zamowienie section", "Final invoice missing FakturaZaliczkowa section"]; readonly fixTemplates: readonly []; }; readonly KURS_WALUTY_Z_PLACEMENT: { readonly code: { readonly domain: "semantic"; readonly category: "business_logic"; readonly code: "KURS_WALUTY_Z_PLACEMENT"; readonly severity: "error"; }; readonly description: "KursWalutyZ at Fa level is ONLY valid for advance invoices (RodzajFaktury = ZAL or KOR_ZAL) (§9.2, §9.5)"; readonly commonCauses: readonly ["Exchange rate placed at wrong level for non-advance invoice", "Should be in FaWiersz/KursWaluty for regular invoices"]; readonly fixTemplates: readonly []; }; readonly FOREIGN_CURRENCY_TAX_PLN: { readonly code: { readonly domain: "semantic"; readonly category: "business_logic"; readonly code: "FOREIGN_CURRENCY_TAX_PLN"; readonly severity: "warning"; }; readonly description: "Foreign currency invoice with tax amounts should include PLN conversions in P_14_*W fields (§9.3)"; readonly commonCauses: readonly ["Missing PLN tax conversion for foreign currency invoice", "P_14_*W fields not provided when KodWaluty ≠ PLN"]; readonly fixTemplates: readonly []; }; readonly ADNOTACJE_P16_MISSING: { readonly code: { readonly domain: "semantic"; readonly category: "required_field"; readonly code: "ADNOTACJE_P16_MISSING"; readonly severity: "error"; }; readonly description: "P_16 is mandatory in Adnotacje (§9.6)"; readonly commonCauses: readonly ["Missing P_16 element in Adnotacje"]; readonly fixTemplates: readonly [{ readonly type: "add"; readonly targetXPath: "//*[local-name()='Adnotacje']"; readonly content: "2"; readonly description: "Add P_16 with value 2 (no significant terms agreed)"; readonly confidence: 0.9; readonly dependencies: readonly []; }]; }; readonly ADNOTACJE_P17_MISSING: { readonly code: { readonly domain: "semantic"; readonly category: "required_field"; readonly code: "ADNOTACJE_P17_MISSING"; readonly severity: "error"; }; readonly description: "P_17 is mandatory in Adnotacje (§9.6)"; readonly commonCauses: readonly ["Missing P_17 element in Adnotacje"]; readonly fixTemplates: readonly [{ readonly type: "add"; readonly targetXPath: "//*[local-name()='Adnotacje']"; readonly content: "2"; readonly description: "Add P_17 with value 2 (not self-billing)"; readonly confidence: 0.9; readonly dependencies: readonly []; }]; }; readonly ADNOTACJE_P18_MISSING: { readonly code: { readonly domain: "semantic"; readonly category: "required_field"; readonly code: "ADNOTACJE_P18_MISSING"; readonly severity: "error"; }; readonly description: "P_18 is mandatory in Adnotacje (§9.6)"; readonly commonCauses: readonly ["Missing P_18 element in Adnotacje"]; readonly fixTemplates: readonly [{ readonly type: "add"; readonly targetXPath: "//*[local-name()='Adnotacje']"; readonly content: "2"; readonly description: "Add P_18 with value 2 (not reverse charge)"; readonly confidence: 0.9; readonly dependencies: readonly []; }]; }; readonly ADNOTACJE_P18A_MISSING: { readonly code: { readonly domain: "semantic"; readonly category: "required_field"; readonly code: "ADNOTACJE_P18A_MISSING"; readonly severity: "error"; }; readonly description: "P_18A is mandatory in Adnotacje (§9.6)"; readonly commonCauses: readonly ["Missing P_18A element in Adnotacje"]; readonly fixTemplates: readonly [{ readonly type: "add"; readonly targetXPath: "//*[local-name()='Adnotacje']"; readonly content: "2"; readonly description: "Add P_18A with value 2 (not split payment mechanism)"; readonly confidence: 0.9; readonly dependencies: readonly []; }]; }; readonly ADNOTACJE_ZWOLNIENIE_MISSING: { readonly code: { readonly domain: "semantic"; readonly category: "required_field"; readonly code: "ADNOTACJE_ZWOLNIENIE_MISSING"; readonly severity: "error"; }; readonly description: "Zwolnienie element is mandatory in Adnotacje (§9.6)"; readonly commonCauses: readonly ["Missing Zwolnienie element in Adnotacje"]; readonly fixTemplates: readonly [{ readonly type: "add"; readonly targetXPath: "//*[local-name()='Adnotacje']"; readonly content: "1"; readonly description: "Add Zwolnienie element indicating no exemptions"; readonly confidence: 0.9; readonly dependencies: readonly []; }]; }; readonly ADNOTACJE_NST_MISSING: { readonly code: { readonly domain: "semantic"; readonly category: "required_field"; readonly code: "ADNOTACJE_NST_MISSING"; readonly severity: "error"; }; readonly description: "NoweSrodkiTransportu element is mandatory in Adnotacje (§9.6)"; readonly commonCauses: readonly ["Missing NoweSrodkiTransportu element in Adnotacje"]; readonly fixTemplates: readonly [{ readonly type: "add"; readonly targetXPath: "//*[local-name()='Adnotacje']"; readonly content: "1"; readonly description: "Add NoweSrodkiTransportu element indicating no new means of transport"; readonly confidence: 0.9; readonly dependencies: readonly []; }]; }; readonly ADNOTACJE_P23_MISSING: { readonly code: { readonly domain: "semantic"; readonly category: "required_field"; readonly code: "ADNOTACJE_P23_MISSING"; readonly severity: "error"; }; readonly description: "P_23 is mandatory in Adnotacje (§9.6)"; readonly commonCauses: readonly ["Missing P_23 element in Adnotacje"]; readonly fixTemplates: readonly [{ readonly type: "add"; readonly targetXPath: "//*[local-name()='Adnotacje']"; readonly content: "2"; readonly description: "Add P_23 with value 2 (no procedural annotations)"; readonly confidence: 0.9; readonly dependencies: readonly []; }]; }; readonly ADNOTACJE_PMARZY_MISSING: { readonly code: { readonly domain: "semantic"; readonly category: "required_field"; readonly code: "ADNOTACJE_PMARZY_MISSING"; readonly severity: "error"; }; readonly description: "PMarzy element is mandatory in Adnotacje (§9.6)"; readonly commonCauses: readonly ["Missing PMarzy element in Adnotacje"]; readonly fixTemplates: readonly [{ readonly type: "add"; readonly targetXPath: "//*[local-name()='Adnotacje']"; readonly content: "1"; readonly description: "Add PMarzy element indicating no margin procedure"; readonly confidence: 0.9; readonly dependencies: readonly []; }]; }; readonly ZWOLNIENIE_LOGIC: { readonly code: { readonly domain: "semantic"; readonly category: "consistency"; readonly code: "ZWOLNIENIE_LOGIC"; readonly severity: "error"; }; readonly description: "Zwolnienie: exactly one of P_19 or P_19N required. If P_19 = '1', exactly one of P_19A/B/C required (§9.6)"; readonly commonCauses: readonly ["Both P_19 and P_19N present or both missing", "P_19 = 1 but exemption basis not specified", "P_19N = 1 but exemption fields present"]; readonly fixTemplates: readonly []; }; readonly NST_LOGIC: { readonly code: { readonly domain: "semantic"; readonly category: "consistency"; readonly code: "NST_LOGIC"; readonly severity: "error"; }; readonly description: "NoweSrodkiTransportu: exactly one of P_22 or P_22N required. If P_22 = '1', P_42_5 and NowySrodekTransportu required (§9.6)"; readonly commonCauses: readonly ["Both P_22 and P_22N present or both missing", "P_22 = 1 but vehicle details not provided", "P_22N = 1 but vehicle fields present"]; readonly fixTemplates: readonly []; }; readonly PMARZY_LOGIC: { readonly code: { readonly domain: "semantic"; readonly category: "consistency"; readonly code: "PMARZY_LOGIC"; readonly severity: "error"; }; readonly description: "PMarzy: exactly one of P_PMarzy or P_PMarzyN required. If P_PMarzy = '1', exactly one procedure type required (§9.6)"; readonly commonCauses: readonly ["Both P_PMarzy and P_PMarzyN present or both missing", "P_PMarzy = 1 but procedure type not specified", "P_PMarzyN = 1 but margin fields present"]; readonly fixTemplates: readonly []; }; readonly P12_ENUMERATION: { readonly code: { readonly domain: "semantic"; readonly category: "business_logic"; readonly code: "P12_ENUMERATION"; readonly severity: "error"; }; readonly description: "P_12 must be one of: 23, 22, 8, 7, 5, 4, 3, 0 KR, 0 WDT, 0 EX, zw, oo, np I, np II (§10.3)"; readonly commonCauses: readonly ["Invalid tax rate code", "Using percentage instead of code", "Typo in rate code"]; readonly fixTemplates: readonly []; }; readonly OO_RATE_FOREIGN_BUYER: { readonly code: { readonly domain: "semantic"; readonly category: "business_logic"; readonly code: "OO_RATE_FOREIGN_BUYER"; readonly severity: "warning"; }; readonly description: "P_12 = 'oo' is for domestic reverse charge only. Use 'np I' or 'np II' for foreign buyers (§10.3, Appendix D #18)"; readonly commonCauses: readonly ["Using domestic reverse charge code for foreign entity", "Should use 'np I' or 'np II' for EU/non-EU buyers"]; readonly fixTemplates: readonly []; }; readonly GTU_FORMAT: { readonly code: { readonly domain: "semantic"; readonly category: "format"; readonly code: "GTU_FORMAT"; readonly severity: "error"; }; readonly description: "GTU value must match pattern GTU_XX (GTU_01 through GTU_13). Common error: 1 instead of GTU_12 (§10.4)"; readonly commonCauses: readonly ["Wrong GTU element format", "Using GTU code as element name instead of value", "Invalid GTU code number"]; readonly fixTemplates: readonly []; }; readonly DECIMAL_PRECISION: { readonly code: { readonly domain: "semantic"; readonly category: "format"; readonly code: "DECIMAL_PRECISION"; readonly severity: "error"; }; readonly description: "Amount field exceeds maximum decimal precision defined in §2.6 of FA(3) specification"; readonly commonCauses: readonly ["Unit price has more than 8 decimal places", "General amount has more than 2 decimal places", "Quantity or exchange rate has more than 6 decimal places", "System generating excessive decimal precision"]; readonly fixTemplates: readonly []; }; readonly KOR_NRKSEF_CONSISTENCY: { readonly code: { readonly domain: "semantic"; readonly category: "consistency"; readonly code: "KOR_NRKSEF_CONSISTENCY"; readonly severity: "error"; }; readonly description: "DaneFaKorygowanej: exactly one of NrKSeF/NrKSeFN = '1'. When NrKSeF = '1', NrKSeFFaKorygowanej required (§9.7)"; readonly commonCauses: readonly ["Both NrKSeF and NrKSeFN set to 1 or neither", "NrKSeF = 1 but KSeF number not provided", "NrKSeFN = 1 but KSeF fields present"]; readonly fixTemplates: readonly []; }; readonly REVERSE_CHARGE_CONSISTENCY: { readonly code: { readonly domain: "semantic"; readonly category: "consistency"; readonly code: "REVERSE_CHARGE_CONSISTENCY"; readonly severity: "warning"; }; readonly description: "Reverse charge: P_13_8/P_13_10 requires P_18 = '1', and at least one FaWiersz with P_12 in (np I, np II, oo) (§9.4, §9.6)"; readonly commonCauses: readonly ["Reverse charge amounts but P_18 not set to 1", "P_18 = 1 but no reverse charge tax rates in line items"]; readonly fixTemplates: readonly []; }; readonly PAYMENT_ZAPLACONO_DATE: { readonly code: { readonly domain: "semantic"; readonly category: "consistency"; readonly code: "PAYMENT_ZAPLACONO_DATE"; readonly severity: "warning"; }; readonly description: "When Platnosc/Zaplacono = '1', DataZaplaty must be present (§12.1)"; readonly commonCauses: readonly ["Payment marked as paid but payment date not provided"]; readonly fixTemplates: readonly []; }; readonly RACHUNEKBANKOWY_NRRB: { readonly code: { readonly domain: "semantic"; readonly category: "required_field"; readonly code: "RACHUNEKBANKOWY_NRRB"; readonly severity: "error"; }; readonly description: "When RachunekBankowy element is filled, NrRB is mandatory (nested obligation) (§2.2, §12.1, Appendix D #4)"; readonly commonCauses: readonly ["Bank account section present but account number not provided"]; readonly fixTemplates: readonly []; }; readonly NRRB_LENGTH: { readonly code: { readonly domain: "semantic"; readonly category: "format"; readonly code: "NRRB_LENGTH"; readonly severity: "warning"; }; readonly description: "NrRB must be 10–34 characters (§12.1)"; readonly commonCauses: readonly ["Bank account number too short or too long", "Invalid IBAN format"]; readonly fixTemplates: readonly []; }; readonly IPKSEF_FORMAT: { readonly code: { readonly domain: "semantic"; readonly category: "format"; readonly code: "IPKSEF_FORMAT"; readonly severity: "warning"; }; readonly description: "IPKSeF must be exactly 13 alphanumeric characters [0-9a-zA-Z] (§12.1)"; readonly commonCauses: readonly ["Invalid IPKSeF format", "Wrong length", "Non-alphanumeric characters"]; readonly fixTemplates: readonly []; }; readonly WALUTA_UMOWNA_PLN: { readonly code: { readonly domain: "semantic"; readonly category: "business_logic"; readonly code: "WALUTA_UMOWNA_PLN"; readonly severity: "error"; }; readonly description: "WalutaUmowna must NEVER be 'PLN' (§13.1, Appendix D #10)"; readonly commonCauses: readonly ["PLN incorrectly used in contract currency field"]; readonly fixTemplates: readonly []; }; readonly KURS_WALUTA_PAIR: { readonly code: { readonly domain: "semantic"; readonly category: "consistency"; readonly code: "KURS_WALUTA_PAIR"; readonly severity: "error"; }; readonly description: "KursUmowny and WalutaUmowna must both be present or both absent (§13.1, Appendix D #11)"; readonly commonCauses: readonly ["Contract exchange rate provided without currency", "Contract currency provided without exchange rate"]; readonly fixTemplates: readonly []; }; readonly TRANSPORT_MINIMUM_DATA: { readonly code: { readonly domain: "semantic"; readonly category: "consistency"; readonly code: "TRANSPORT_MINIMUM_DATA"; readonly severity: "warning"; }; readonly description: "Transport requires: (RodzajTransportu OR TransportInny+OpisInnegoTransportu) AND (OpisLadunku OR LadunekInny+OpisInnegoLadunku) (§13.2, Appendix D #17)"; readonly commonCauses: readonly ["Transport section present but minimum required data missing", "Missing transport type or cargo description"]; readonly fixTemplates: readonly []; }; readonly CURRENCY_RATE_UNVERIFIABLE: { readonly code: { readonly domain: "semantic"; readonly category: "business_logic"; readonly code: "CURRENCY_RATE_UNVERIFIABLE"; readonly severity: "warning"; }; readonly description: "KursWaluty cannot be verified — NBP rate unavailable or outside the valid date window (Art. 31a ustawy o VAT)"; readonly commonCauses: readonly ["NBP API unavailable or rate-limited during validation", "Rate data provided is from a date too far from the invoice date", "Network error during rate lookup"]; readonly fixTemplates: readonly []; }; readonly CURRENCY_RATE_MISMATCH: { readonly code: { readonly domain: "semantic"; readonly category: "business_logic"; readonly code: "CURRENCY_RATE_MISMATCH"; readonly severity: "warning"; }; readonly description: "KursWaluty does not match the NBP Table A mid-rate for the reference date (Art. 31a ustawy o VAT — the business day before the tax obligation arises, or before the issue date when the invoice precedes it)"; readonly commonCauses: readonly ["Manually entered exchange rate differs from the official NBP rate", "Rounding error in exchange rate", "Wrong date used for the exchange rate lookup — the issue date rather than the delivery or settlement-period date", "Taxpayer lawfully elected a different basis that FA(3) does not record: ECB rates (Art. 31a ust. 1) or income-tax conversion rules (Art. 31a ust. 2a)"]; readonly fixTemplates: readonly []; }; readonly AMOUNT_NO_SEPARATORS: { readonly code: { readonly domain: "semantic"; readonly category: "format"; readonly code: "AMOUNT_NO_SEPARATORS"; readonly severity: "error"; }; readonly description: "Amount fields must not contain spaces, commas, or any non-numeric characters except minus and decimal point (§2.5, Appendix D #13)"; readonly commonCauses: readonly ["Thousand separators (spaces or commas) in amount fields", "Non-numeric characters in numeric fields"]; readonly fixTemplates: readonly []; }; readonly TAX_CALCULATION_MISMATCH: { readonly code: { readonly domain: "semantic"; readonly category: "business_logic"; readonly code: "TAX_CALCULATION_MISMATCH"; readonly severity: "error"; }; readonly description: "Tax calculation error: P_14_x must equal P_13_x × (P_12 rate / 100), and P_15 must equal sum of all (P_13_x + P_14_x)"; readonly commonCauses: readonly ["Incorrect tax amount calculation", "Rounding errors in tax calculations", "Total amount does not match sum of base amounts and taxes"]; readonly fixTemplates: readonly []; }; readonly INVALID_BANK_ACCOUNT_FORMAT: { readonly code: { readonly domain: "semantic"; readonly category: "format"; readonly code: "INVALID_BANK_ACCOUNT_FORMAT"; readonly severity: "error"; }; readonly description: "Polish bank account (NrRB) must be 28 characters for IBAN format (PL + 26 digits) or 26 digits for NRB format"; readonly commonCauses: readonly ["Incorrect Polish IBAN format", "Wrong number of digits in bank account", "Missing or malformed IBAN prefix"]; readonly fixTemplates: readonly []; }; readonly DUPLICATE_LINE_NUMBERS: { readonly code: { readonly domain: "semantic"; readonly category: "consistency"; readonly code: "DUPLICATE_LINE_NUMBERS"; readonly severity: "error"; }; readonly description: "Line numbers (NrWierszaFa) must be unique within the invoice (except in corrective invoices where before/after states can share numbers)"; readonly commonCauses: readonly ["Same line number used for multiple invoice items", "Incorrect line numbering sequence"]; readonly fixTemplates: readonly []; }; readonly NEGATIVE_QUANTITY_NOT_ALLOWED: { readonly code: { readonly domain: "semantic"; readonly category: "business_logic"; readonly code: "NEGATIVE_QUANTITY_NOT_ALLOWED"; readonly severity: "error"; }; readonly description: "Negative quantities (P_8B) are only allowed in corrective invoices (RodzajFaktury = KOR, KOR_ZAL, or KOR_ROZ)"; readonly commonCauses: readonly ["Negative quantity in standard VAT invoice", "Incorrect invoice type for negative quantities"]; readonly fixTemplates: readonly []; }; readonly VALIDATOR_INITIALIZATION_FAILED: { readonly code: { readonly domain: "infrastructure"; readonly category: "system"; readonly code: "VALIDATOR_INITIALIZATION_FAILED"; readonly severity: "error"; }; readonly description: "Failed to initialize validation system"; readonly commonCauses: readonly ["Schema loading failed", "Memory allocation error", "System resource unavailable"]; readonly fixTemplates: readonly []; }; readonly VALIDATION_TIMEOUT: { readonly code: { readonly domain: "infrastructure"; readonly category: "system"; readonly code: "VALIDATION_TIMEOUT"; readonly severity: "error"; }; readonly description: "Validation exceeded time limit"; readonly commonCauses: readonly ["Very large document", "Complex validation rules", "System overload"]; readonly fixTemplates: readonly []; }; readonly EXECUTION_ERROR: { readonly code: { readonly domain: "infrastructure"; readonly category: "system"; readonly code: "EXECUTION_ERROR"; readonly severity: "error"; }; readonly description: "Unexpected error during validation execution"; readonly commonCauses: readonly ["Runtime environment issue", "Unhandled exception in validation logic", "System resource exhaustion"]; readonly fixTemplates: readonly []; }; readonly MALFORMED_XML: { readonly code: { readonly domain: "parse"; readonly category: "syntax"; readonly code: "MALFORMED_XML"; readonly severity: "error"; }; readonly description: "XML is not well-formed"; readonly commonCauses: readonly ["Missing closing tags", "Invalid characters", "Mismatched tags", "Invalid XML declaration"]; readonly fixTemplates: readonly []; }; readonly XML_DISCOURAGED_CHARACTER: { readonly code: { readonly domain: "parse"; readonly category: "ksef_strict_xml"; readonly code: "XML_DISCOURAGED_CHARACTER"; readonly severity: "error"; }; readonly description: "Character discouraged by the W3C XML spec ([#x7F-#x84], [#x86-#x9F], [#xFDD0-#xFDEF], [#xNFFFE-#xNFFFF]); KSeF rejects such invoices from 2026-10-19 (KSeF API 2.4.0, Weryfikacja faktury)"; readonly commonCauses: readonly ["C1 control characters (U+0080-U+009F) pasted from Word, PDF or a legacy system", "Noncharacters from a corrupted export or a wrong text conversion"]; readonly fixTemplates: readonly []; }; readonly XML_PROCESSING_INSTRUCTION: { readonly code: { readonly domain: "parse"; readonly category: "ksef_strict_xml"; readonly code: "XML_PROCESSING_INSTRUCTION"; readonly severity: "error"; }; readonly description: "XML processing instruction (e.g. xml-stylesheet); KSeF rejects such invoices from 2026-10-19 (KSeF API 2.4.0, Weryfikacja faktury)"; readonly commonCauses: readonly ["An integrator adds to attach a visualisation", "Another tool injects a custom processing instruction"]; readonly fixTemplates: readonly []; }; readonly XML_DISCOURAGED_CHARACTER_MORE: { readonly code: { readonly domain: "parse"; readonly category: "ksef_strict_xml"; readonly code: "XML_DISCOURAGED_CHARACTER_MORE"; readonly severity: "error"; }; readonly description: "Summary: further discouraged characters beyond the individually reported ones"; readonly commonCauses: readonly []; readonly fixTemplates: readonly []; }; readonly XML_PROCESSING_INSTRUCTION_MORE: { readonly code: { readonly domain: "parse"; readonly category: "ksef_strict_xml"; readonly code: "XML_PROCESSING_INSTRUCTION_MORE"; readonly severity: "error"; }; readonly description: "Summary: further processing instructions beyond the individually reported ones"; readonly commonCauses: readonly []; readonly fixTemplates: readonly []; }; readonly XML_BOM_PRESENT: { readonly code: { readonly domain: "parse"; readonly category: "ksef_strict_xml"; readonly code: "XML_BOM_PRESENT"; readonly severity: "error"; }; readonly description: "File starts with a UTF-8 BOM; KSeF requires UTF-8 without BOM (Weryfikacja faktury)"; readonly commonCauses: readonly ["File saved as \"UTF-8 with BOM\" (e.g. Notepad, Excel exports)"]; readonly fixTemplates: readonly []; }; readonly XML_ENCODING_NOT_UTF8: { readonly code: { readonly domain: "parse"; readonly category: "ksef_strict_xml"; readonly code: "XML_ENCODING_NOT_UTF8"; readonly severity: "error"; }; readonly description: "XML declaration names an encoding other than UTF-8; KSeF requires UTF-8 (Weryfikacja faktury)"; readonly commonCauses: readonly ["Declaration copied from a legacy template with encoding=\"windows-1250\" or \"ISO-8859-2\""]; readonly fixTemplates: readonly []; }; readonly ENCODING_ERROR: { readonly code: { readonly domain: "parse"; readonly category: "encoding"; readonly code: "ENCODING_ERROR"; readonly severity: "error"; }; readonly description: "Character encoding error"; readonly commonCauses: readonly ["Invalid UTF-8 sequences", "Wrong encoding declaration"]; readonly fixTemplates: readonly []; }; readonly SCHEMA_VALIDATION_FAILED: { readonly code: { readonly domain: "xsd"; readonly category: "schema"; readonly code: "SCHEMA_VALIDATION_FAILED"; readonly severity: "error"; }; readonly description: "XML does not conform to FA(3) XSD schema"; readonly commonCauses: readonly ["Invalid element order", "Missing required elements", "Invalid element values", "Wrong namespace"]; readonly fixTemplates: readonly []; }; readonly ELEMENT_NOT_ALLOWED: { readonly code: { readonly domain: "xsd"; readonly category: "schema"; readonly code: "ELEMENT_NOT_ALLOWED"; readonly severity: "error"; }; readonly description: "Element not allowed at this location"; readonly commonCauses: readonly ["Element in wrong parent", "Typo in element name", "Wrong element order"]; readonly fixTemplates: readonly []; }; readonly REQUIRED_ELEMENT_MISSING: { readonly code: { readonly domain: "xsd"; readonly category: "schema"; readonly code: "REQUIRED_ELEMENT_MISSING"; readonly severity: "error"; }; readonly description: "Required element missing according to schema"; readonly commonCauses: readonly ["Mandatory element not provided", "Incomplete structure"]; readonly fixTemplates: readonly []; }; readonly INVALID_ELEMENT_VALUE: { readonly code: { readonly domain: "xsd"; readonly category: "schema"; readonly code: "INVALID_ELEMENT_VALUE"; readonly severity: "error"; }; readonly description: "Element value does not match schema constraints"; readonly commonCauses: readonly ["Value outside allowed range", "Wrong data type", "Pattern mismatch"]; readonly fixTemplates: readonly []; }; }; export type ErrorCode = keyof typeof ERROR_CODES; export declare function getErrorDefinition(code: string): ErrorCodeDefinition | undefined; export declare function getFixSuggestions(code: string): readonly FixSuggestion[]; export declare function isKnownErrorCode(code: string): code is ErrorCode; //# sourceMappingURL=error-codes.d.ts.map