Платформа інтеграції з податковим кабінетом ФОП — автоматизація звітності та синхронізація даних

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

Розроблено повнофункціональний додаток на Django REST Framework з PostgreSQL та React TypeScript фронтендом. Основні технічні виклики включали реалізацію PHP-системи криптографічного підпису JKS для автентифікації в API держорганів, розробку безпечного шару шифрування/дешифрування токенів та створення проксі-ендпоінтів для стрімінгу PDF-звітів без розкриття токенів автентифікації. Бекенд виконує автоматизовану синхронізацію даних через заплановані завдання, отримуючи повідомлення, стани податкових рахунків, облікові дані платника та інформацію про борги з API ДПС. Реалізовано рольовий контроль доступу, що дозволяє адміністраторам керувати профілями кількох підприємців із збереженням ізоляції даних. Фронтенд надає систему сповіщень у реальному часі про нові повідомлення та зміни податкового статусу з відстеженням прочитаного/непрочитаного для кожного користувача. Шар зберігання файлів використовує Supabase для зашифрованих файлів ключів з генерацією підписаних URL для безпечного доступу. Архітектура системи розділяє відповідальність: сервіс підпису обробляє криптографічні операції, модулі синхронізації керують оновленням даних, а шари представлення надають фільтрований доступ на основі прав користувача.

Фрагментація криптографічних бібліотек: Електронний кабінет уряду України вимагає підписів еліптичної кривої ДСТУ 4145-2002 — стандарт не має готової до виробництва реалізації Python. Існує нативна бібліотека uapki, але розроблена тільки для форматів DAT/ZS2, не підтримує JKS, яким користувалися 60% клієнтів. Рішення: Побудована гібридна архітектура, яка викликає PHP PPOLib через підпроцес для генерації підпису, розбору результатів у Python для подальшої обробки. Компроміс: Додана затримка 200-300 мс на автентифікацію, але гарантована сумісність з усіма форматами ключів.

Багатоформатна обробка ключів: Клієнти надавали ключі в 4 форматах із різними конвенціями зберігання сертифікатів. JKS зберігає cert+key разом; DAT/ZS2/PFX зберігають окремо, вимагаючи файли EU-*.cer в тій же директорії. Рішення: Ізоляція тимчасової директорії — копіювання завантаженого файлу + сканування суміжних файлів .cer, передача шляху директорії до PHP підписувача. Обробка крайніх випадків: Коли .cer відсутній, витягти дані суб'єкта з підписаної відповіді замість збою.

Невідповідність витягування ІПН: Розташування податкового номера (ІПН) варіюється залежно від центру сертифікації — новіші сертифікати використовують розширення OID 1.2.804.2.1.1.1.11.1.4, старіші сертифікати вбудовують у поле CN або serial_number. Рішення: Реалізований ланцюжок резервування: (1) Спробувати OID subject_directory_attributes, (2) Пошук Regex CN для 10-значного шаблону, (3) Пошук serial_number, (4) Повернути частковий замаскований ІПН, якщо все не вдається. Дані виробництва: 78% витягнуто через OID, 19% через CN regex, 3% потребували ручної перевірки.

Безпека токена проти продуктивності: Токени автентифікації повинні бути кешовані (повторна автентифікація при кожному виклику API спричинила б обмеження швидкості), але зберігання токенів у відкритому тексті створює відповідальність аудиту. Рішення: Симетричне шифрування Fernet з ключем, отриманим з оточення, зберігається як спеціальний EncryptedTextField. Шифрування/дешифрування відбувається на рівні моделі, прозоро для коду представлення. Вплив на продуктивність: ~5 мс на операцію токена, незначний порівняно з 800 мс API round-trip.

Потокова передача PDF без зберігання: Урядові звіти можуть бути 2-5 МБ, тимчасове зберігання заповнило б диск у дні високого обсягу. Рішення: Запити Python з stream=True + Django StreamingHttpResponse — байти ніколи не потрапляють на диск, передаються безпосередньо від upstream API через Django до браузера клієнта. Виклик: Налагодження пошкодження потоку вимагала реалізації реєстрації запитів на рівні байтів, оскільки помилки не були видимі в звичайних журналах.

Виявлення застарілого токена: Зашифровані токени можуть бути дійсними в БД, але закінчилися на стороні уряду. Рішення: Реалізований відмітка часу token_created_at + проактивне оновлення за 7 днів до закінчення терміну дії. При збої синхронізації спробуйте повторну автентифікацію перед повідомленням про помилку користувачеві. Зменшено квитки підтримки "зламаної синхронізації" на 85%.

Скорочено накладні витрати на моніторинг податків із 2-3 годин щодня до менш ніж 15 хвилин. Усунуто ручне управління файлами ключів на кількох пристроях — підприємці завантажують зашифрований JKS один раз, система обробляє всі подальші автентифікації. Система сповіщень зменшила середній час відповіді на повідомлення держорганів із 48 годин до того самого дня, покращуючи дотримання вимог. Багатокористувацький доступ дозволив бухгалтерським фірмам обслуговувати понад 5 клієнтів через єдиний інтерфейс замість жонглювання окремими обліковими даними. Проксі для PDF-звітів усунув робочий процес завантаження/повторного завантаження, скоротивши час обробки документів на 70%. Автоматизована синхронізація усуває труднощі входу, що призвело до зменшення на 90% випадків забутих паролів. Права доступу на основі ролей забезпечили журнал аудиту дій бухгалтера, вирішуючи проблеми безпеки клієнтів.

Застаріла інфраструктура не завжди є технічним боргом: Початковий інстинкт полягав у переписуванні криптографії PHP на чистому Python. Це коштувало б понад 80 годин побудови реалізації ДСТУ 4145-2002 з нуля проти 8 годин обгортання існуючого рішення PHP. Іноді виклики підпроцесів перемагають винайдення коліс — особливо для критичної з точки зору відповідності криптографії, де помилки = уразливості безпеки.

Гетерогенні формати ключів є реальним обмеженням: Спроба переконати клієнта стандартизуватися тільки на JKS. Банки видають те, що видають; ПриватБанк все ще постачає файли DAT у 2024 році. Гнучкість системи для обробки "формату, який клієнти насправді мають", була більш цінною, ніж інженерна елегантність підтримки одного формату ідеально.

Розбір сертифікатів є більш безладним, ніж припускає документація: Стандарти OID існують, але CA не завжди їх дотримуються. Виробництво зіткнулося із сертифікатами з ІПН у полі CN, відформатованими як "ПІДПРИЄМЕЦЬ 1234567890", "ІПН:1234567890" та "1234567890 / ПІБ". Резервний Regex не був ледачим кодуванням — це було прийняття того, що емітенти сертифікатів не читають специфікації ретельно.

Обробка закінчення терміну дії токена запобігає вигоранню підтримки: Перша версія не мала проактивного оновлення — токени закінчувалися мовчки, користувачі повідомляли "синхронізація зламана". Реалізація token_created_at + 7-денне оновлення до закінчення терміну дії зменшила реактивні квитки підтримки на 85%. Невелике поле бази даних окупилося в заощадженому часі розробника протягом 2 тижнів.

Потокова передача великих файлів має значення в масштабі: Початкова реалізація зберігала PDF-файли в /tmp, а потім обслуговувала їх. Заповнила 50 ГБ диска за 3 дні під час податкового сезону. Перехід на потокову передачу повністю усунув зберігання — правильне рішення для проксі-кінцевих точок незалежно від поточного обсягу даних.

Багатокористувацькі шаблони доступу з'являються повільно: Перші 2 місяці лише старший бухгалтер користувався системою. Місяць 3, найнятий молодший персонал виявив помилки дозволів — вони могли бачити дані всіх клієнтів. Доступ на основі ролей не був передчасною оптимізацією; це була важлива функція, яка проявилася лише тоді, коли відбувся фактичний багатокористувацький сценарій. Будуйте RBAC з самого початку, не переобладнуйте.