Валідація та обробка XML у KSeF – як платформа інтерпретує рахунок

Вступ

У Національній системі е-рахунків (KSeF) рахунок — це не візуальний документ (напр. PDF), а структурований XML-документ, який повинен відповідати офіційній схемі, опублікованій Міністерством фінансів.

Репозиторій CIRFMF/ksef-docs містить технічну документацію API та процесів інтеграції KSeF 2.0 і є головним джерелом знань для інтеграторів ERP-систем та додатків для виставлення рахунків.

У момент відправки XML-документа до KSeF починається багатоетапний процес валідації та парсингу документа, який визначає, чи буде рахунок прийнятий до системи.

Архітектура обробки XML-рахунку в KSeF

Процес обробки рахунку можна поділити на кілька основних етапів: відправка документа до API KSeF, технічна валідація XML-документа, бізнес-валідація даних, ідентифікація дублікатів, збереження рахунку в системі та присвоєння номера KSeF.

Кожен з цих етапів відповідає за перевірку іншого типу вимог.

1. Технічна валідація XML (XSD)

Першим етапом є валідація структури XML відносно схеми XSD. Рахунок повинен бути у форматі XML, закодований в UTF-8 та відповідати поточній схемі рахунку FA(3).

Схема XSD визначає: структуру документа, дозволені елементи та атрибути, типи даних (напр. дата, сума, ідентифікатор), обов'язкові та необов'язкові поля та обмеження значень.

Приклади помилок, що виявляються на цьому етапі: відсутність обов'язкових полів (напр. номера рахунку P_2), неправильний формат дати, невідповідність простору імен XML, неправильний тип даних.

Якщо XML не відповідає схемі XSD, документ відхиляється ще до бізнес-аналізу.

2. Парсинг XML-документа

Після проходження структурної валідації система KSeF починає парсинг документа. Парсинг полягає у зчитуванні структури XML, перетворенні елементів XML на внутрішні моделі даних системи та перевірці зв'язків між елементами.

У цьому процесі елементи XML, такі як Podmiot1 (продавець), Podmiot2 (покупець), Fa (дані заголовка рахунку) та FaWiersz (позиція рахунку), відображаються на об'єкти в системі KSeF.

На цьому етапі система будує модель рахунку в базі даних KSeF.

3. Бізнес-валідація документа

Після побудови моделі даних відбувається бізнес-валідація. Перевіряються: правильність дат, зв'язки між полями, узгодженість сум нетто та ПДВ, відповідність податкових ідентифікаторів.

Приклад правила: дата виставлення рахунку не може бути пізнішою за момент прийняття документа до KSeF.

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

4. Перевірка дублікатів

KSeF також проводить перевірку унікальності рахунку. Система перевіряє комбінацію: NIP продавця, тип рахунку та номер рахунку.

Якщо в системі вже існує рахунок з таким набором даних, документ відхиляється як дублікат. Період перевірки дублікатів охоплює до 10 років назад.

5. Технічний контроль та системні ліміти

Перед збереженням рахунку також перевіряються технічні ліміти. Приклади обмежень: максимальний розмір XML — приблизно 1 МБ, до 3 МБ для документів з вкладеннями, пакетна відправка в ZIP-архівах до 100 МБ.

Цей контроль спрямований на забезпечення стабільності інфраструктури системи.

6. Шифрування та безпека

Після відправки документа його вміст захищається криптографічно. Використовуються: шифрування AES-256-CBC для даних рахунку та RSAES-OAEP для ключа шифрування.

Додатково валідується електронний підпис документа. Варто зазначити, що валідація структури XML (XSD) та валідація криптографічного підпису — це два незалежні процеси.

7. Присвоєння номера KSeF

Якщо документ пройде всі етапи верифікації: рахунок зберігається в системі, система присвоює йому унікальний ідентифікатор KSeF, а документ стає офіційно виставленим рахунком.

Лише з цього моменту документ вважається виставленим у юридичному сенсі.

Перевірте свій XML перед відправкою — безкоштовний валідатор

Перед відправкою рахунку до KSeF варто переконатися, що XML-файл коректний. Ми надаємо безкоштовний валідатор XML KSeF, який перевіряє відповідність документа схемі XSD, правильність структури, NIP-ів, дат та сум — без реєстрації та без відправки даних на зовнішні сервери.

Спробуйте наш безкоштовний валідатор XML та усуньте помилки до того, як вони потраплять до системи KSeF.

Підсумок

Валідація XML-рахунку в KSeF — це багатоетапний процес, який включає як технічний, так і бізнес-контроль.

Ключові елементи процесу: валідація структури XML відносно схеми XSD, парсинг документа та маппінг даних, валідація бізнес-правил, перевірка дублікатів, перевірка технічних лімітів, верифікація безпеки та підпису, збереження рахунку та присвоєння номера KSeF.

Такий підхід гарантує, що кожен рахунок, збережений у системі KSeF, є узгодженим, структурно правильним та відповідає податковому законодавству.