Коротко: валідація SAF-T UA
- Валідація SAF-T UA зазвичай включає два рівні: XSD-перевірку структури XML-файлу і логічну перевірку узгодженості даних.
- Файл із критичними XSD-помилками може бути технічно відхилений ще до аналізу змісту.
- Файл, що пройшов XSD, усе одно може містити логічні помилки у даних — такі помилки можуть призвести до додаткових запитань або необхідності повторної підготовки файлу.
- Найчастіші проблеми: відсутні ІПН/ЄДРПОУ контрагентів, коди товарів, розбіжності між проводками і первинними документами.
- Правильний процес — ітераційна валідація до першого коректно сформованого файлу або сценарію подання: спочатку виправити всі XSD-помилки, потім перевірити логіку даних на тестовому файлі.
Два рівні перевірки
Перед поданням або тестовою передачею SAF-T-файл доцільно перевіряти на двох рівнях:
Рівень 1: XSD-валідація — перевірка відповідності файлу офіційній XML Schema Definition. XSD описує допустиму структуру: перелік тегів, їх порядок, обов'язкові поля, типи даних і дозволені значення. Якщо файл не відповідає схемі — помилка фіксується з вказівкою рядка і елементу.
Рівень 2: Логічна перевірка даних — перевірка узгодженості даних. Файл може мати правильну XML-структуру, але містити дані, які суперечать одне одному, не узгоджуються з довідниками або можуть викликати питання під час аналізу ДПС. Наприклад: контрагент присутній у транзакціях, але відсутній у довіднику контрагентів; дата документу виходить за межі звітного періоду; дебет не збігається з кредитом у проводках.
На практиці обидва рівні потрібні для якісної підготовки SAF-T UA. Успішне проходження XSD — лише перший крок. Без логічної перевірки файл може пройти технічну XSD-валідацію, але містити змістовні помилки, які створять ризик додаткових запитань або повторної підготовки.
XSD-схема: що вона перевіряє
XSD-схема SAF-T UA — офіційний документ, що визначає допустиму структуру XML-файлу. Опублікована ДПС разом з технічною специфікацією SAF-T UA.
XSD перевіряє:
- Наявність обов'язкових елементів — кожен блок (Header, MasterFiles, GeneralLedgerEntries, SourceDocuments) повинен містити певний набір тегів. Відсутній обов'язковий тег — помилка XSD.
- Типи даних — дати мають бути у форматі ISO 8601 (YYYY-MM-DD), числа — без пробілів і з крапкою як роздільником, рядки — у правильному кодуванні.
- Довжини полів — наприклад, ІПН не може містити більше або менше символів, ніж передбачено схемою.
- Допустимі значення — деякі поля мають обмежений список допустимих значень (enumeration); значення за межами списку — помилка XSD.
- Порядок елементів — у XML порядок тегів часто є значущим; XSD перевіряє, що елементи йдуть у правильній послідовності.
XSD-схема оновлюється ДПС при зміні специфікації SAF-T UA. Перед кожною генерацією або поданням переконайтесь, що ви використовуєте актуальну версію схеми з офіційного сайту ДПС.
Логічна перевірка даних
Логічні перевірки — це правила узгодженості даних, які не завжди описуються XSD-схемою, але критично важливі для коректного SAF-T-файлу і можуть перевірятися під час аналізу даних.
Ключові логічні перевірки SAF-T UA зазвичай включають:
- Посилкова цілісність — кожен контрагент, що фігурує в транзакціях, повинен бути описаний у довіднику контрагентів (MasterFiles/Suppliers або MasterFiles/Customers). Кожен рахунок з GeneralLedgerEntries — у плані рахунків.
- Балансування проводок — сума дебетових оборотів повинна дорівнювати сумі кредитових оборотів за звітний період.
- Відповідність дат звітному періоду — дати документів і транзакцій повинні відповідати періоду, зазначеному в Header.
- Відповідність суми документа і проводок — загальна сума SourceDocument повинна збігатись із відповідними проводками в GeneralLedgerEntries.
- Коди товарів — для товарних операцій можуть вимагатися коди відповідно до застосовного класифікатора або внутрішнього довідника, залежно від структури SAF-T UA та типу даних.
- Коректні ІПН/ЄДРПОУ — ідентифікатори контрагентів мають бути числово коректними (контрольна цифра, довжина).
Топ типових помилок і як їх виправити
На основі практики підготовки SAF-T-файлів для реальних підприємств виокремлюємо найчастіші групи помилок.
Помилки у блоці MasterFiles
| Помилка | Причина | Виправлення |
|---|---|---|
| Відсутній ІПН або ЄДРПОУ контрагента | В обліковій системі не заповнене поле ідентифікатора | Масове заповнення довідника перед генерацією файлу |
| Некоректний формат ІПН (не 10 або не 12 цифр) | Помилки введення або застарілі дані | Валідація довідника за контрольною цифрою |
| Контрагент у транзакції відсутній у MasterFiles | Транзакції є, але контрагент не доданий у довідник | Перехресна перевірка довідника і транзакцій перед генерацією |
| Рахунок плану рахунків відсутній у MasterFiles | Використовуються рахунки, яких немає в переданому плані | Вивантажити повний план рахунків разом з транзакціями |
Помилки у GeneralLedgerEntries
| Помилка | Причина | Виправлення |
|---|---|---|
| Дебет ≠ Кредит за звітний період | Некоректні проводки в обліковій системі або помилки при вивантаженні | Перевірити оборотно-сальдову відомість перед генерацією |
| Дата проводки поза звітним періодом | Помилки датування або некоректний фільтр при вивантаженні | Перевірити фільтр дат при генерації; виправити помилкові датування |
| Порожнє поле опису транзакції | Обов'язкові текстові поля не заповнені в системі | Масове заповнення або генерація стандартного опису з атрибутів документа |
| Некоректний формат числа (кома замість крапки) | Регіональні налаштування системи впливають на формат виводу | Нормалізація числових форматів при генерації XML |
Помилки у SourceDocuments
| Помилка | Причина | Виправлення |
|---|---|---|
| Відсутній код УКТ ЗЕД у переміщенні товару | Код не заповнений у картці товару в системі | Масове заповнення довідника товарів; автоматична підстановка за назвою |
| Сума документа не збігається з проводками | Розбіжність між первинним документом і бухгалтерськими записами | Перевірити і вирівняти первинні документи і проводки в обліковій системі |
| Відсутній номер вхідного документа постачальника | Поле не заповнене при введенні документа | Масова правка або заповнення з архівних первинних документів |
| Некоректна валюта транзакції | Відсутній або невірний код ISO валюти | Перевірити і стандартизувати коди валют (UAH, USD, EUR тощо) |
Інструменти для валідації
Для XSD-валідації підходять стандартні XML-інструменти:
- xmllint (Linux/Mac) — консольний інструмент:
xmllint --schema saft-ua.xsd your-file.xml --noout. Виводить помилки з номерами рядків. - Oxygen XML Editor — GUI-інструмент з детальним відображенням помилок XSD.
- Python lxml / xmlschema — програмна валідація: зручно для автоматизації і попередньої перевірки при генерації.
- Вбудована валідація у SAF-T Connector — автоматична XSD-перевірка і логічна перевірка даних при кожній генерації, звіт помилок з посиланнями на джерело даних.
Для логічної перевірки стандартних XML-інструментів недостатньо — потрібна кастомна логіка або спеціалізоване рішення, яке перевіряє узгодженість довідників, проводок, документів, дат, сум і податкових атрибутів.
Робочий процес: ітерація до чистого файлу
Оптимальний процес підготовки першого SAF-T-файлу виглядає так:
- Підготовка даних. Перевірте і виправте довідники ще до генерації: ІПН/ЄДРПОУ всіх контрагентів, коди УКТ ЗЕД для товарів, коректність плану рахунків.
- Генерація тестового файлу. Сформуйте SAF-T за невеликий тестовий період (наприклад, один місяць) для першої перевірки.
- XSD-валідація. Перевірте тестовий файл за XSD-схемою. Виправте всі структурні помилки.
- Логічна перевірка даних. Перевірте узгодженість: балансування проводок, посилкова цілісність, відповідність дат і сум.
- Виправлення джерела. Усі виправлення вносяться в облікову систему — не у XML-файл вручну. Правка XML вручну не масштабується і не відтворювана.
- Повторна генерація і валідація. Ітерація до чистого файлу без помилок.
- Генерація фінального файлу за потрібний звітний період.
- Подача або передача файлу у сценарії, для якого він готується, та збереження копії.
Для компаній без готового рішення цей процес може тривати тижні. SAF-T Connector від LUCAS автоматизує генерацію і валідацію — помилки виявляються і усуваються системно, а не вручну. Детальніше про підготовку до SAF-T — у статті «Readiness assessment і план впровадження».
Часті запитання
Що таке XSD-схема SAF-T UA і де її взяти?
XSD (XML Schema Definition) — офіційна схема структури SAF-T-файлу, опублікована ДПС разом з технічною специфікацією. Актуальну версію завантажуйте з офіційного сайту Державної податкової служби України. При зміні специфікації схема оновлюється — перевіряйте версію перед кожною генерацією або поданням.
Чи можна виправляти помилки безпосередньо у XML-файлі?
Технічно можна, але не рекомендується. Правка XML вручну не відтворювана, не масштабується при великих файлах і не вирішує першопричину: дані в обліковій системі залишаються некоректними. Правильний підхід — виправляти джерело і повторно генерувати файл.
Чим відрізняється XSD-помилка від логічної помилки даних?
XSD-помилка — це помилка структури: відсутній тег, неправильний тип даних, некоректна послідовність елементів. Логічна помилка даних — це змістовна невідповідність: контрагент є в транзакції, але відсутній у довіднику; дата виходить за межі періоду; дебет не збігається з кредитом. Перша група стосується технічної структури XML, друга — якості та узгодженості облікових даних.
Чи приймає ДПС файл із попередженнями (без помилок)?
Якщо файл проходить XSD-валідацію і не містить критичних логічних помилок, ризик технічного відхилення або подальших запитань суттєво нижчий. Конкретна поведінка системи залежить від актуальної реалізації ДПС і документації до відповідної версії SAF-T UA.
Що робити, якщо файл великий і XSD-валідатор зависає?
Великі SAF-T-файли (мільйони записів) можуть бути гігабайтами XML. Стандартні GUI-інструменти можуть не справлятись. Використовуйте потокові валідатори (SAX-based) або програмні бібліотеки (lxml з streaming). SAF-T Connector від LUCAS оптимізований для роботи з великими файлами.
Чи потрібна валідація при кожній генерації?
Так. Дані в обліковій системі постійно змінюються: додаються нові контрагенти, вносяться коригування. Те, що минулий файл пройшов валідацію, не гарантує чистоти наступного. Автоматична валідація при кожній генерації — стандартна практика. Особливо це важливо перед тестовим або фактичним поданням файлу, а також після змін у довідниках, обліковій політиці, ERP або правилах маппінгу.
Як LUCAS допомагає
LUCAS перевіряє SAF-T UA не лише на рівні XML-структури, а й на рівні якості облікових даних: довідників, проводок, первинних документів, дат, сум, податкових атрибутів і зв'язків між блоками файлу.
SAF-T Connector від LUCAS формує файл, виконує XSD-валідацію та логічну перевірку даних, а також показує помилки у форматі, зрозумілому бухгалтеру, податковому спеціалісту і IT-команді. Це дозволяє виправляти першопричину в обліковій системі, а не редагувати XML вручну.
Висновок для CFO
Валідація SAF-T UA — це не технічна формальність, а реальний тест якості ваших облікових даних. Файл, що не проходить XSD, — технічна проблема, яку можна виправити за лічені дні. Файл, що не проходить логічну перевірку даних, — симптом системних проблем: неповні довідники, розбіжності між документами і проводками, відсутні або некоректні коди класифікаторів.
Правильна відповідь на цей виклик — не ручне виправлення XML перед кожним поданням, а систематична підготовка даних на рівні облікової системи. Починайте з readiness assessment — він покаже, де саме у ваших даних є прогалини і що потрібно виправити до першого коректно сформованого файлу.