eDeklaracje Local Tool — локальная система для генерации и массовой отправки IFT-1R в bramkę MF

Growth Insider спроектировал и разработал локальную систему для IT-компании с более чем 10 000 исполнителей, которой нужно было подготовить и отправить годовые налоговые отчёты IFT-1R в польскую налоговую администрацию.

Проект решал не обычную задачу “отправить XML”. Клиенту нужно было превратить большой массив выплат и данных по исполнителям в корректные годовые отчёты, сформировать XML-документы IFT-1R, пройти техническую проверку, отправить документы через bramkę Ministerstwa Finansów и получить подтверждения UPO.

Готовые инструменты не закрывали этот процесс в нужном масштабе. Ручная отправка через стандартные интерфейсы заняла бы месяцы. Growth Insider создал систему, которая сократила процесс до двух дней и сэкономила около 20 000 zł на платных отправках и ручной обработке.

Executive summary

IT-компания работала с большой сетью исполнителей — более 10 000 человек, которые получали вознаграждения на основании договоров. За несколько лет накопился большой объём данных по выплатам, который нужно было преобразовать в годовую налоговую отчётность IFT-1R и отправить в польскую налоговую систему.

У компании была база данных и история выплат, но не было внутреннего инструмента, который автоматически превращал эти данные в корректные отчёты, формировал XML, проверял структуру, отправлял документы и собирал UPO.

Стандартные польские системы не закрывали нужный сценарий. Отправка через обычные интерфейсы требовала бы обработки каждого отчёта отдельно. При объёме 10 000+ исполнителей это означало месяцы ручной работы, высокий риск ошибок и значительные расходы.

Growth Insider разработал локальную систему, которая автоматизировала весь процесс: от подготовки IFT-1R на основании данных о выплатах до массовой отправки XML-документов и контроля подтверждений UPO.

Бизнес-контекст

Клиент — IT-компания, которая несколько лет работала с большой базой исполнителей. За этот период в системе накопились выплаты, договорные данные и персональная информация, необходимая для формирования годовых отчётов IFT-1R.

Проблема возникла на стыке бухгалтерии, налоговой отчётности, данных и операционного масштаба.

У компании были исходные данные, но не было процесса, который:

• собирал выплаты по каждому исполнителю;
• формировал годовую картину по каждому человеку;
• превращал данные в отчёт IFT-1R;
• генерировал корректные XML-файлы;
• проверял обязательные поля;
• валидировал структуру XML;
• отправлял документы в bramkę MF;
• отслеживал статусы;
• получал UPO;
• показывал ошибки;
• позволял повторить неудачные отправки;
• давал финальный отчёт по результату.

Главная проблема заключалась не в одном техническом действии, а во всём процессе: данные → отчёты → XML → отправка → статусы → UPO → контроль результата.

Почему стандартные решения не подошли

Клиент рассмотрел стандартные варианты, но они не закрыли нужный сценарий.

Некоторые польские системы для бухгалтерии и кадровой работы не поддерживали массовую отправку нужных IFT-1R в требуемом формате и масштабе. Отдельные решения позволяли работать с налоговой отчётностью, но не давали нужной автоматизации для 10 000+ исполнителей.

Стандартный путь через систему PIT означал отправку по каждому человеку отдельно. Для базы такого размера это создавало три проблемы:

1. Слишком много ручной работы. Каждый отчёт требовал отдельного действия, проверки и контроля.
2. Слишком большой риск ошибок. При тысячах документов ручной процесс неизбежно создавал ошибки: пропущенные файлы, неправильные статусы, дубли, забытые подтверждения.
3. Слишком высокая стоимость. Платные инструменты оценивались по количеству отправок. При стоимости около 2–3 zł за один IFT-1R итоговая сумма для 10 000+ документов становилась значительной.

Поэтому клиенту нужна была не настройка готовой программы, а собственная локальная система под конкретный налогово-операционный процесс.

Главная задача

Growth Insider получил задачу спроектировать и разработать систему, которая автоматизировала весь цикл работы с IFT-1R:

1. Принять данные по выплатам исполнителям.
2. Сформировать годовые отчёты по каждому специалисту.
3. Сгенерировать XML-документы IFT-1R.
4. Проверить обязательные поля и структуру.
5. Подготовить подписанные XML к отправке.
6. Отправить документы пакетами через bramkę MF.
7. Получить статусы обработки.
8. Получить и сохранить UPO.
9. Показать ошибки и неудачные элементы.
10. Дать оператору контроль над повторной отправкой.
11. Сформировать отчёты по результатам обработки.

Подход Growth Insider

Мы подошли к проекту как к построению закрытого операционного инструмента, а не как к написанию одноразового скрипта.

Процесс был разделён на два больших контура:

1. Контур генерации IFT-1R

Этот контур отвечал за превращение исходных данных в налоговые XML-документы.

Система брала данные из базы, где находились сведения по исполнителям и выплатам, проверяла обязательные поля, нормализовала значения, подставляла данные плательщика, формировала структуру IFT-1R и сохраняла XML-файлы для дальнейшей обработки.

2. Контур отправки e-Deklaracje

Этот контур отвечал за массовую отправку подписанных XML-документов в bramkę MF, получение статусов, polling, UPO, retry, отчёты и контроль выполнения.

Вместе эти два контура закрыли полный путь: Данные о выплатах → IFT-1R XML → batch-отправка → статус MF → UPO → отчёт по результату

Что было реализовано

В проект вошли два взаимосвязанных инструмента: генератор IFT-1R и локальная система массовой отправки.

Генератор IFT-1R

Был реализован инструмент, который формировал XML-файлы IFT-1R из данных в базе.

Он обрабатывал данные исполнителей, выплаты, идентификаторы, адресные поля, даты рождения, страны, суммы, налоговые поля и данные плательщика. Система валидировала обязательные поля и пропускала записи с критичными ошибками, чтобы оператор видел, какие данные требовали исправления.

В генераторе были реализованы:

• подключение к базе данных;
• чтение исходной таблицы;
• проверка обязательных полей;
• нормализация дат;
• обработка стран и мест рождения;
• расчёт и округление сумм;
• генерация XML IFT-1R;
• структура документа по нужному namespace;
• заполнение данных плательщика;
• заполнение данных получателя;
• заполнение детальных налоговых позиций;
• XSD-валидация;
• запись XML в выходную папку;
• статистика по созданным и пропущенным файлам.

eDeklaracje Local Tool

Была реализована локальная система для пакетной отправки подписанных XML-документов.

Система состояла из backend, web UI и batch engine. Backend работал локально, UI открывался в браузере на компьютере оператора, а batch engine управлял очередью отправки, статусами и повторными попытками.

В системе были реализованы:

• локальный интерфейс оператора;
• backend для управления заданиями;
• выбор TEST/PROD-среды MF;
• preflight check перед запуском;
• проверка входной и выходной папки;
• рекурсивный поиск XML-файлов;
• кодирование XML в base64;
• отправка через SOAP sendDocument;
• получение UPO через SOAP requestUPO;
• контроль статусов MF;
• Start / Pause / Resume / Stop;
• retry для сетевых ошибок;
• принудительная повторная отправка FAILED;
• manifest по обработанным файлам;
• lock для защиты от параллельного запуска;
• logs;
• экспорт отчётов в CSV/JSON;
• сохранение корректных UPO;
• технический отчёт по процессу.

Архитектура решения

Система была построена как локальное приложение, которое запускалось на компьютере оператора.

Архитектура включала:

• Frontend: web UI для оператора;
• Backend: локальный API-сервер;
• Batch engine: очередь обработки файлов;
• Input folder: папка с подписанными XML;
• Output folder: папка результатов;
• MF integration: SOAP-интеграция с bramką Ministerstwa Finansów;
• Manifest: состояние задания и каждого файла;
• UPO storage: сохранённые подтверждения;
• Logs: технические события и ошибки;
• Reports: экспорт результата в CSV/JSON.

Такой формат был выбран потому, что процесс требовал локального контроля, работы с файлами, безопасного доступа к данным и понятного интерфейса для оператора.

Как работал процесс

Шаг 1. Подготовка данных

Компания предоставила исходные данные по исполнителям и выплатам. Эти данные были приведены к структуре, из которой система сформировала годовые отчёты IFT-1R.

На этом этапе были обработаны:

• идентификаторы исполнителей;
• имя и фамилия;
• дата рождения;
• страна;
• адресные данные;
• суммы выплат;
• данные плательщика;
• налоговые поля;
• период отчётности.

Шаг 2. Генерация XML IFT-1R

Система сформировала отдельный XML-документ IFT-1R для каждого исполнителя.

При генерации проверялись обязательные поля. Если запись была неполной или некорректной, система не создавала неправильный XML, а добавляла причину пропуска в статистику.

Это снизило риск отправки документов с критичными ошибками.

Шаг 3. Подготовка подписанных XML

После генерации документы проходили этап подготовки к отправке. Система eDeklaracje Local Tool работала с подписанными XML-файлами, так как сам инструмент отправки не выполнял электронную подпись.

Это разделило ответственность: генерация и подготовка документов отдельно, отправка и контроль статусов отдельно.

Шаг 4. Preflight check

Перед запуском batch-процесса оператор выполнял preflight check.

Система проверяла:

• доступность входной папки;
• доступность выходной папки;
• корректность путей;
• отсутствие конфликта между input и output;
• наличие XML-файлов;
• свободное место;
• состояние lock;
• готовность к старту.

Если находились критические проблемы, старт блокировался.

Шаг 5. Batch-отправка в bramkę MF

После запуска система обрабатывала файлы пакетно.

Для каждого документа выполнялись:

1. кодирование XML в base64;
2. отправка SOAP-запросом sendDocument;
3. получение refId;
4. запись результата отправки;
5. переход к polling статуса.

Шаг 6. Получение статусов и UPO

После отправки система запрашивала статус через requestUPO.

Система не считала процесс успешным только по факту получения refId или технического ответа. Успех фиксировался только после получения корректного UPO.

UPO проверялось по структуре, подписи, номеру referencyjnemu, Przyjeto=true, дате wpływu, коду urzędu и коду formularza.

Шаг 7. Retry и повторная обработка

Если возникала техническая ошибка, система использовала retry.

Отдельно были реализованы действия для оператора:

• повторить сетевые ошибки;
• принудительно повторить FAILED;
• поставить процесс на паузу;
• продолжить обработку;
• остановить job;
• возобновить работу на основе manifest.

Это было важно при большой партии документов, где сбой одного файла не должен был останавливать весь процесс.

Шаг 8. Финальный отчёт

После завершения обработки оператор получал понятную картину:

• сколько файлов было найдено;
• сколько отправлено;
• сколько получило UPO;
• какие элементы завершились ошибкой;
• какие ошибки были техническими;
• какие ошибки требовали исправления данных;
• какие UPO были сохранены;
• какие файлы требовали повторной отправки.

Что получил бизнес

1. Автоматизацию процесса, который вручную занял бы месяцы

При объёме более 10 000 исполнителей ручная отправка каждого IFT-1R заняла бы несколько месяцев.

Разработанная система сократила процесс до двух дней.

2. Экономию около 20 000 zł

Платные решения оценивались по количеству документов. При стоимости около 2–3 zł за один IFT-1R итоговая стоимость для 10 000+ документов составила бы значительную сумму.

Кастомная система позволила сэкономить около 20 000 zł и оставить инструмент под контролем клиента.

3. Контроль над каждым документом

Оператор видел статус каждого файла: pending, sending, processing, done, failed.

Это убрало хаос из процесса, где раньше каждый документ требовал ручного контроля.

4. Повторную обработку ошибок

Система позволила отделить технические ошибки от ошибок данных и повторно обработать неудачные элементы.

Это было критично для массовой отправки, где часть документов возвращала ошибки из-за качества данных, сети или статусов MF.

5. Получение и сохранение UPO

Система сохраняла только корректные UPO. Это дало клиенту формальное подтверждение приёма документов налоговой администрацией.

6. Локальный контроль

Решение работало локально и не требовало передачи всего процесса во внешнюю платформу. Клиент сохранил контроль над данными, файлами, отчётами и результатами.

7. Повторяемый процесс на следующие периоды

Система была создана не как одноразовый ручной обход, а как воспроизводимый процесс для будущих отчётных периодов.

Почему это не был обычный скрипт

На первый взгляд задача выглядела как “сгенерировать XML и отправить файлы”. На практике это был полноценный операционный процесс с налоговой ответственностью, большим объёмом данных и множеством точек отказа.

Обычный скрипт не закрывал бы:

• preflight перед запуском;
• контроль input/output;
• manifest;
• lock;
• статусы по каждому файлу;
• retry;
• паузу и возобновление;
• polling UPO;
• проверку валидности UPO;
• отчёты;
• обработку ошибок;
• безопасное повторение;
• разделение технических и бизнес-ошибок.

Поэтому Growth Insider разработал локальную систему, а не одноразовый файл для запуска из консоли.

Операционная сложность проекта

Проект был сложным из-за сочетания нескольких факторов.

Большой объём данных

База включала более 10 000 исполнителей. При таком масштабе даже небольшая доля ошибок превращается в сотни проблемных записей.

Налоговая точность

IFT-1R — это формальный налоговый документ. Ошибка в данных, структуре XML, суммах, периоде или идентификаторе создавала риск отказа.

Интеграция с bramką MF

Отправка выполнялась через центральную bramkę Ministerstwa Finansów. Система работала с SOAP-методами sendDocument и requestUPO, статусами обработки и UPO.

Ошибки данных

Часть проблем была связана не с системой, а с качеством исходных данных: пустые поля, некорректные даты, отсутствующие идентификаторы, неполные адреса.

Операционный контроль

Оператору нужен был интерфейс, а не чёрный ящик. Он должен был видеть, где процесс идёт нормально, где возникла ошибка и какие действия нужно выполнить дальше.

Что было особенно важно в UX

Интерфейс был спроектирован вокруг работы оператора, который отвечал за большой batch-процесс.

Оператору были нужны не “красивые экраны”, а контроль:

• выбрать среду TEST или PROD;
• указать input folder;
• указать output folder;
• выполнить preflight;
• запустить обработку;
• поставить на паузу;
• возобновить;
• остановить;
• увидеть прогресс;
• увидеть DONE и FAILED;
• повторить сетевые ошибки;
• принудительно повторить FAILED;
• выгрузить отчёт;
• проверить UPO.

UX был построен вокруг безопасного выполнения большого процесса, где ошибка оператора стоила времени и могла привести к пропуску документов.

Почему UPO было главным критерием успеха

В проекте успех не фиксировался по факту отправки XML.

Система считала документ успешно обработанным только после получения и проверки UPO.

Это было принципиально важно, потому что:

• refId подтверждал только регистрацию отправки;
• промежуточные статусы не означали финального приёма;
• status=200 без корректного UPO не завершал процесс;
• только валидное UPO подтверждало приём документа администрацией.

Такой подход защитил клиента от ложного ощущения, что документы были приняты, если процесс фактически не завершился корректным подтверждением.

Результат проекта

Growth Insider разработал локальную систему, которая закрыла полный цикл массовой подготовки и отправки IFT-1R.

Клиент получил:

• генерацию IFT-1R XML из данных по выплатам;
• предварительную проверку обязательных данных;
• XSD-валидацию XML;
• локальный интерфейс оператора;
• backend для управления заданиями;
• пакетную отправку подписанных XML;
• интеграцию с bramką MF;
• получение статусов;
• получение и сохранение UPO;
• retry для ошибок;
• pause/resume/stop;
• manifest и lock;
• отчётность;
• контроль результатов;
• экономию около 20 000 zł;
• сокращение процесса с нескольких месяцев до двух дней.

Что этот кейс показывает о Growth Insider

Этот проект показывает, что Growth Insider умеет строить не только сайты, SEO и маркетинговые страницы, а сложные внутренние системы для бизнес-критичных процессов.

В этом кейсе были объединены:

• налоговая логика;
• работа с большим массивом данных;
• генерация XML;
• XSD-валидация;
• локальное приложение;
• web UI;
• backend;
• batch processing;
• SOAP-интеграция;
• retry;
• polling;
• UPO validation;
• отчётность;
• операционный контроль.

Для потенциального клиента это важный сигнал: Growth Insider умеет проектировать системы, которые не просто “работают”, а закрывают реальный бизнес-процесс от начала до результата.

Почему это проект уровня custom business system

eDeklaracje Local Tool нельзя оценивать как маленькую утилиту.

Это проект класса custom business system, потому что он объединил несколько уровней:

1. Бизнес-уровень: понимание налогового процесса, ограничений готовых инструментов и стоимости ручной обработки.
2. Данные: обработка базы исполнителей, выплат, адресов, идентификаторов и налоговых параметров.
3. Документы: генерация IFT-1R XML и проверка структуры.
4. Интеграция: отправка в bramkę Ministerstwa Finansów через SOAP.
5. Операции: управление batch-процессом, пауза, возобновление, retry, manifest, lock.
6. Контроль результата: получение и валидация UPO как фактического подтверждения приёма.
7. Экономика: сокращение ручной работы с месяцев до двух дней и экономия около 20 000 zł.

Где такой подход был особенно ценен

Такой формат решения был особенно ценен для процессов, где есть:

• тысячи документов;
• повторяющаяся налоговая или административная операция;
• строгий формат XML;
• необходимость отправки через внешнюю государственную систему;
• обязательное подтверждение приёма;
• высокий риск ручных ошибок;
• ограниченность готовых инструментов;
• чувствительные данные;
• необходимость локального контроля;
• потребность в отчёте по каждому элементу.

Ключевой вывод

eDeklaracje Local Tool превратил хаотичный, ручной и дорогостоящий процесс массовой отправки IFT-1R в управляемую локальную систему.

Клиент получил не просто способ отправить XML, а полноценный рабочий контур:

данные → отчёты IFT-1R → XML → отправка → статусы → UPO → отчёт → контроль ошибок

За 2–3 недели была создана система, которая позволила обработать масштаб 10 000+ исполнителей, сократить работу с нескольких месяцев до двух дней и сэкономить около 20 000 zł.