Найголовніше за хвилину

Валідація SAF-T UA включає два рівні: XSD-перевірку структури XML і логічну перевірку узгодженості даних.
Файл із критичними XSD-помилками може бути технічно відхилений ще до аналізу змісту.
Файл, що пройшов XSD, усе одно може містити логічні помилки — вони ведуть до додаткових запитань або повторної підготовки.
Найчастіші проблеми: відсутні ІПН/ЄДРПОУ контрагентів, коди товарів, розбіжності між проводками і первинними документами.
Правильний процес — ітераційна валідація: спершу виправити всі XSD-помилки, потім перевірити логіку даних на тестовому файлі.

Два рівні перевірки

Рівень 1 — XSD-валідація. Перевірка відповідності файлу офіційній XML Schema Definition: перелік тегів, їх порядок, обов’язкові поля, типи даних і дозволені значення. Невідповідність фіксується з вказівкою рядка та елемента.

Рівень 2 — логічна перевірка даних. Файл може мати бездоганну структуру, але містити дані, що суперечать одне одному: контрагент присутній у транзакціях, але відсутній у довіднику; дата документа поза звітним періодом; дебет не збігається з кредитом.

Обидва рівні однаково важливі. Успішний XSD — лише перший крок: без логічної перевірки файл формально валідний, але змістовно проблемний, що створює ризик запитань від ДПС чи повторної підготовки.

Що перевіряє XSD-схема

XSD-схема SAF-T UA — офіційний документ, опублікований ДПС разом із технічною специфікацією. Вона контролює:

обов’язкові елементи — кожен блок (Header, MasterFiles, GeneralLedgerEntries, SourceDocuments) має містити визначений набір тегів;
типи даних — дати в ISO 8601 (YYYY-MM-DD), числа з крапкою без пробілів, коректне кодування рядків;
довжини полів — наприклад, ІПН строго визначеної довжини;
допустимі значення — поля з обмеженим списком (enumeration);
порядок елементів — послідовність тегів у XML значуща.

XSD-схема оновлюється ДПС при зміні специфікації. Перед кожною генерацією чи поданням перевіряйте, що використовуєте актуальну версію з офіційного сайту ДПС.

Що перевіряє логічний рівень

Ключові правила узгодженості, які зазвичай не покриваються XSD, але критичні для якісного файлу:

посилальна цілісність — кожен контрагент із транзакцій описаний у MasterFiles (Suppliers/Customers), кожен рахунок із проводок — у плані рахунків;
балансування — сума дебетових оборотів дорівнює кредитовим за період;
відповідність дат — дати документів і транзакцій у межах періоду з Header;
звірка сум — загальна сума SourceDocument збігається з відповідними проводками;
коди товарів — для товарних операцій потрібні коди за застосовним класифікатором;
коректність ідентифікаторів — ІПН/ЄДРПОУ проходять перевірку довжини і контрольної цифри.

Типові помилки та як їх виправляти

У блоці MasterFiles

Помилка	Причина	Виправлення
Відсутній ІПН або ЄДРПОУ контрагента	Поле не заповнене в обліковій системі	Масове заповнення довідника до генерації
Некоректний формат ІПН	Помилки введення, застарілі дані	Валідація довідника за контрольною цифрою
Контрагент із транзакції відсутній у MasterFiles	Транзакції є, контрагента в довіднику немає	Перехресна звірка довідника з транзакціями
Рахунок відсутній у переданому плані	Використано рахунки поза вивантаженим планом	Вивантажувати повний план рахунків разом із транзакціями

У GeneralLedgerEntries

Помилка	Причина	Виправлення
Дебет ≠ кредит за період	Некоректні проводки або помилки вивантаження	Звірка з оборотно-сальдовою відомістю до генерації
Дата проводки поза періодом	Помилки датування чи фільтра вивантаження	Перевірити фільтр дат; виправити датування
Порожній опис транзакції	Обов’язкові текстові поля не заповнені	Масове заповнення або генерація опису з атрибутів документа
Кома замість крапки в числах	Регіональні налаштування системи	Нормалізація числових форматів при генерації XML

У SourceDocuments

Помилка	Причина	Виправлення
Відсутній код УКТ ЗЕД у русі товару	Код не заповнено в картці товару	Масове заповнення товарного довідника
Сума документа ≠ сумі проводок	Розбіжність між первинкою і бухзаписами	Вирівняти документи і проводки в системі
Немає номера вхідного документа	Поле не заповнене при введенні	Масова правка із залученням архівної первинки
Некоректна валюта	Відсутній чи хибний код ISO	Стандартизувати коди валют (UAH, USD, EUR)

Інструменти валідації

Для XSD підходять стандартні XML-інструменти:

xmllint --schema saft-ua.xsd file.xml --noout — консольна перевірка з номерами рядків (Linux/Mac);
Oxygen XML Editor — GUI з детальним відображенням помилок;
Python lxml / xmlschema — програмна валідація для автоматизації;
вбудована валідація SAF-T Connector — XSD плюс логічна перевірка при кожній генерації, зі звітом, що посилається на джерело даних.

Для логічного рівня стандартних XML-інструментів недостатньо — потрібна кастомна логіка або спеціалізоване рішення, яке звіряє довідники, проводки, документи, дати, суми й податкові атрибути. Три рівні перевірок у SAF-T Connector працюють саме так.

Робочий процес: ітерація до чистого файлу

Підготовка даних. Виправте довідники ще до генерації: ІПН/ЄДРПОУ контрагентів, коди УКТ ЗЕД, план рахунків.
Тестовий файл. Згенеруйте SAF-T за невеликий період (наприклад, місяць).
XSD-валідація. Усуньте всі структурні помилки.
Логічна перевірка. Балансування, посилальна цілісність, дати, суми.
Виправлення джерела. Усі правки — в обліковій системі, не в XML вручну: ручна правка не відтворювана і не масштабується.
Повторна генерація і валідація — ітерації до чистого файлу.
Фінальна генерація за потрібний звітний період.
Подання і збереження копії.

Без готового рішення цей цикл може тривати тижнями. SAF-T Connector автоматизує генерацію й валідацію — помилки виявляються системно, а не вручну; про підготовчий етап читайте у статті про оцінку готовності.

Часті запитання

Де взяти XSD-схему SAF-T UA?

Актуальну версію публікує ДПС разом із технічною специфікацією на офіційному сайті. Схема оновлюється при змінах специфікації — звіряйте версію перед кожною генерацією.

Чи можна виправляти помилки прямо в XML?

Технічно можна — практично не варто. Ручна правка не відтворювана, не масштабується на великих файлах і не усуває першопричину: дані в системі лишаються некоректними. Виправляйте джерело і генеруйте файл заново.

Чим XSD-помилка відрізняється від логічної?

XSD-помилка — структурна: відсутній тег, неправильний тип, зламаний порядок елементів. Логічна — змістовна: контрагент без запису в довіднику, дата поза періодом, дебет ≠ кредит. Перша про технічну форму XML, друга — про якість облікових даних.

Файл великий, валідатор зависає — що робити?

SAF-T великих компаній — це гігабайти XML і мільйони записів; GUI-інструменти можуть не впоратися. Використовуйте потокові (SAX-based) валідатори або програмні бібліотеки зі streaming-режимом. SAF-T Connector оптимізований для великих файлів.

Чи потрібна валідація при кожній генерації?

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

Висновок для CFO

Валідація SAF-T UA — не технічна формальність, а тест якості облікових даних. Файл, що не проходить XSD, — технічна проблема на кілька днів. Файл, що не проходить логічну перевірку, — симптом системних проблем: неповних довідників, розбіжностей між документами і проводками, відсутніх кодів. Правильна відповідь — не ручні правки XML перед кожним поданням, а систематична робота з даними на рівні облікової системи, починаючи з оцінки готовності.