Помилки валідації FA(3) у KSeF - як виправити помилки

KSeF (Krajowy System e-Faktur, польська національна система електронних фактур) відхиляє документ непомітно: у відповіді сесії з'являється тризначний код і короткий напис польською. Проблема в тому, що цей напис майже ніколи не вказує на поле, яке насправді не пройшло перевірку.

Наслідки цілком податкові. Згідно зі ст. 106na ч. 1 закону про VAT, структуровану фактуру вважають виставленою в день її надсилання до KSeF. Якщо перша спроба завершилася відмовою, а виправлений файл потрапив до системи вже наступного місяця, змінюється звітний період.

Ця стаття зіставляє коди відповіді KSeF із тим, що саме у файлі FA(3) їх викликає.

Які коди KSeF повертає для окремої фактури

Статус фактури в сесії описано в офіційній специфікації API KSeF 2.0. Ось кінцеві коди.

Код Значення Чи це проблема змісту фактури 200 Успіх, присвоєно номер KSeF Ні 405 Обробку скасовано через помилку сесії Ні 410 Неправильний обсяг повноважень Ні, це повноваження 415 Неможливо надіслати фактуру із додатком Частково 430 Помилка перевірки файлу фактури Так 435 Помилка розшифрування файлу Ні, транспортний рівень 440 Дублікат фактури Так 450 Помилка семантики документа фактури Так 500 Невідома помилка Звернення до Міністерства фінансів 550 Операцію скасовано системою Повторити надсилання

Ключова різниця: 430 стосується файлу та схеми, 450 стосується бізнес-правил усередині документа, а 440 це конфлікт із тим, що вже є в базі Міністерства фінансів.

10 помилок, які дають більшість відмов

1. Дублікат номера фактури (код 440)

KSeF виявляє дублікати глобально. Критерієм є комбінація трьох значень: NIP продавця (Podmiot1:NIP), вид фактури (RodzajFaktury) і номер фактури (P_2). Унікальність зберігається протягом 10 повних років від кінця року виставлення.

Найтиповіший сценарій: інтеграція не дочекалася відповіді, вважала надсилання невдалим і повторила його з тим самим номером, хоча фактура вже була в системі. Другий варіант стосується фірм із філіями, які виставляють документи від одного NIP без узгодженої нумерації.

2. Кодування та структура файлу XML (код 430)

Технічні вимоги жорсткі. Файл має бути в UTF-8 без знака BOM (байти 0xEF 0xBB 0xBF), не може містити інструкцій обробки XML, а якщо містить пролог, то цей пролог не може оголошувати інше кодування, ніж UTF-8. Заборонені також нерекомендовані символи Unicode із діапазонів на кшталт [#x7F-#x84] чи [#xFDD0-#xFDEF].

BOM це класика під час генерування XML у Windows. Керуючі символи з'являються, коли назву товару скопіювали з таблиці або зі складської системи.

3. NIP не відповідає шаблону або контрольній сумі

Тип TNrNIP у схемі FA(3) вимагає шаблон [1-9]((\d[1-9])|([1-9]\d))\d{7}. Це десять цифр без дефісів, без пробілів і без префікса PL. Значення PL5252344078 відпадає одразу на рівні XSD.

Окремо KSeF перевіряє контрольну суму NIP для Podmiot1, Podmiot2, Podmiot3 та PodmiotUpowazniony. Ця перевірка працює лише на продакшені, і це часта пастка: файл проходить на тестовому середовищі й падає на бойовому.

4. Дата виставлення з майбутнього

Дата в полі P_1 не може бути пізнішою за дату прийняття документа системою KSeF. Достатньо, щоб ваша система формувала P_1 у локальному часі, а шлюз порівнював його з UTC, і фактури, виставлені пізно ввечері 31 січня, підуть із датою 1 лютого.

5. Неправильний заголовок документа

Блок Naglowek має фіксовані значення. Атрибут kodSystemowy має бути точно FA (3), з пробілом перед дужкою. wersjaSchemy це 1-0E, а WariantFormularza це 3. Крім того, DataWytworzeniaFa не може бути ранішою за 2025-09-01T00:00:00Z.

Остання умова ламає старі тестові набори та фікстури, перенесені з FA(2).

<Naglowek>
  <KodFormularza kodSystemowy="FA (3)" wersjaSchemy="1-0E">FA</KodFormularza>
  <WariantFormularza>3</WariantFormularza>
  <DataWytworzeniaFa>2026-08-29T10:15:00Z</DataWytworzeniaFa>
</Naglowek>

6. Суми у форматі, якого схема не приймає

Тип TKwotowy має шаблон -?([1-9]\d{0,15}|0)(\.\d{1,2})?. На практиці це чотири заборони: кома як десятковий роздільник, роздільник тисяч, більше двох знаків після коми та провідні нулі.

Значення в XML Результат 1230.50 Правильно 1230,50 Відхилено 1 230.50 Відхилено 1230.500 Відхилено 01230.50 Відхилено

Три знаки після коми це симптом систем, які рахують ціну за одиницю з більшою точністю і переносять її просто в поля вартості. Ціна за одиницю має власний тип із більшою точністю, значення продажу не мають.

7. Перевищена довжина текстових полів

Базовий символьний тип у схемі має ліміт 240 символів і є однорядковим. Назва суб'єкта вміщує 512 символів, вулиця 65, номер будинку 9, номер приміщення 10, поштовий індекс 8, місто 56.

Найчастіше ламається назва товару, склеєна з описом, і адреса, у якій увесь адресний рядок потрапив у поле вулиці.

8. Немає повноважень у контексті надсилання (код 410)

Надсилання фактури вимагає повноважень на її виставлення в контексті конкретного суб'єкта. Код 410 з'являється, коли бухгалтерське бюро (biuro rachunkowe) не має наданого повноваження для NIP клієнта, коли закінчилася довіреність або коли при самофактуруванні покупець не має права виставляти документ від імені продавця.

Це не помилка файлу. Правити XML тут не допоможе.

9. Фактура з додатком в інтерактивній сесії (код 415)

Надсилання фактур із додатками дозволене лише в пакетному режимі та потребує попереднього повідомлення про цю опцію в сервісі e-Urząd Skarbowy (польський електронний податковий кабінет). Єдиний виняток це технічна корекція офлайнової фактури, яку можна надіслати в інтерактивній сесії.

10. Помилка семантики документа (код 450)

Код 450 стосується правил, які сама схема не вловить. Типові випадки: коригувальна фактура без повного блоку DaneFaKorygowanej, посилання на номер KSeF фактури, якої в системі немає, а також неузгоджені умовні блоки, коли позначку процедури поставлено, а поля, які цей вибір робить обов'язковими, залишилися порожніми.

Варто пам'ятати: KSeF не перевіряє фактуру по суті. Він не скаже, чи ставка VAT відповідає товару. Він перевіряє повноту та узгодженість структури.

Що робити, коли фактура повернулася з помилкою

Відхилена фактура не має номера KSeF, отже не є структурованою фактурою і не підлягає корекції. Ви виправляєте файл і надсилаєте його повторно під тим самим номером.

Окремий шлях стосується фактур, виставлених в офлайн-режимі. Якщо така фактура вже потрапила до контрагента з QR-кодами, а KSeF відхилив її з технічної причини, Міністерство фінансів передбачило технічну корекцію. Ви надсилаєте виправлений файл із тим самим змістом, вказуючи в полі hashOfCorrectedInvoice хеш SHA-256 первинного, відхиленого документа. Система пов'язує обидва документи, завдяки чому старий QR-код перенаправляє клієнта на виправлену фактуру.

Технічна корекція має два обмеження: вона не служить для зміни змісту фактури і не вирішує проблем із повноваженнями.

Чекліст перед надсиланням

Файл збережено в UTF-8 без BOM, без інструкцій обробки XML.
Заголовок: kodSystemowy="FA (3)", wersjaSchemy="1-0E", WariantFormularza=3, DataWytworzeniaFa не раніше 2025-09-01.
Усі NIP як 10 цифр без дефісів і префікса, з правильною контрольною сумою.
P_1 не є датою з майбутнього щодо моменту надсилання.
Суми з крапкою, максимум два знаки після коми, без провідних нулів.
Номер P_2 не використаний раніше для цього NIP і цього виду фактури.
Розмір файлу менший за 1 000 000 байтів, а з додатками менший за 3 000 000 байтів.
Повноваження на виставлення в контексті цього NIP активні й не прострочені.
Валідацію файлу за офіційним XSD виконано локально, до надсилання.

Підсумок

Більшість відмов у KSeF виникає не через незнання законів, а через дрібні розбіжності формату: BOM, кома замість крапки, дефіс у NIP, повторне надсилання після таймауту. Локальна валідація за схемою FA(3) вилучає їх ще до того, як документ покине вашу систему.

Biurko валідує згенерований XML за офіційним XSD перед пакетним надсиланням і в офлайн-режимі, перекладає коди помилок KSeF на повідомлення, що вказують на конкретне поле, і зберігає повну історію комунікації з Міністерством фінансів при кожній фактурі. Дублікати система розпізнає і прив'язує до первинного номера KSeF замість того, щоб показувати хибну помилку.

Інтерфейс Biurko доступний польською, англійською та українською. Створіть безкоштовний акаунт на biurko.io і подивіться, як виглядає надсилання до KSeF, коли помилку видно до відправки, а не після неї.

FAQ

Що означає код 440 у KSeF? Дублікат фактури. Система вже має документ із такою самою комбінацією NIP продавця, виду фактури та номера. Унікальність перевіряється глобально і зберігається 10 повних років від кінця року виставлення. Перевірте, чи попереднє надсилання насправді не завершилося успіхом.

Чи можна скоригувати фактуру, відхилену KSeF? Ні. Відхилена фактура не отримала номера KSeF, отже вона не є структурованою фактурою і не підлягає корекції. Ви виправляєте файл і надсилаєте повторно. Виняток становлять офлайнові фактури, для яких передбачено технічну корекцію.

Чому файл пройшов на тестовому середовищі, а на продакшені його відхилили? Найчастіше через контрольну суму NIP. KSeF перевіряє її лише на продакшені. На тесті вигаданий NIP, що відповідає шаблону, проходить, а на бойовому той самий файл відхиляється.

Чим відрізняється код 430 від 450? Код 430 це помилка перевірки файлу: кодування, структура XML, невідповідність схемі. Код 450 це помилка семантики, тобто бізнес-правил усередині структурно правильного документа, наприклад корекції без повних даних коригованої фактури.

Чи перевіряє KSeF правильність ставок VAT? Ні. Система перевіряє відповідність схемі, унікальність, дати, NIP і повноваження. За змістовну правильність ставок, сум і даних контрагента відповідає виставник. Прийняття фактури системою KSeF не виправляє змістовної помилки.

KSeF відхилив фактуру? 10 помилок валідації FA(3)