Platforma Integracji Gabinetu Podatkowego FOP — Automatyzacja raportowania i synchronizacji danych rządowych

Klient wymagał systemu eliminującego ręczne monitorowanie gabinetu podatkowego dla przedsiębiorców zarządzających wieloma podmiotami gospodarczymi. Główne problemy obejmowały: powtarzalne procedury logowania z kluczami kryptograficznymi, ręczne sprawdzanie nowych komunikatów rządowych, brak scentralizowanego widoku sald rachunków podatkowych dla wszystkich podmiotów oraz czasochłonne pobieranie raportów PDF. Rozwiązanie musiało obsługiwać wielopoziomowy dostęp z uprawnieniami opartymi na rolach dla księgowych obsługujących wielu klientów.

Zbudowano aplikację pełnego cyklu wykorzystującą Django REST Framework z bazą PostgreSQL i frontendem React TypeScript. Główne wyzwania techniczne obejmowały implementację systemu kryptograficznego podpisu JKS opartego na PHP dla uwierzytelniania w rządowym API, opracowanie bezpiecznej warstwy szyfrowania/deszyfrowania tokenów oraz stworzenie endpointów proxy do przesyłania strumieniowego raportów PDF bez ujawniania tokenów uwierzytelniających. Backend obsługuje automatyczną synchronizację danych poprzez zaplanowane zadania, pobierając wiadomości, statusy rachunków podatkowych, dane karty płatnika i informacje o długach z API Państwowej Służby Podatkowej. Zaimplementowano kontrolę dostępu opartą na rolach, umożliwiającą administratorom zarządzanie wieloma profilami przedsiębiorców przy zachowaniu izolacji danych. Frontend zapewnia system powiadomień w czasie rzeczywistym o nowych wiadomościach i zmianach statusu podatkowego, ze śledzeniem przeczytane/nieprzeczytane dla każdego użytkownika. Warstwa przechowywania plików wykorzystuje Supabase dla zaszyfrowanych plików kluczy z generowaniem podpisanych URL dla bezpiecznego dostępu. Architektura systemu separuje odpowiedzialności: serwis podpisu obsługuje operacje kryptograficzne, moduły synchronizacji zarządzają aktualizacjami danych, a warstwy widoków zapewniają filtrowany dostęp na podstawie uprawnień użytkownika.

Fragmentacja bibliotek kryptograficznych: Ukraiński rządowy e-gabinet wymaga podpisów krzywej eliptycznej DSTU 4145-2002 — standard nie ma gotowej do produkcji implementacji w Pythonie. Istnieje natywna biblioteka uapki, ale zaprojektowana tylko dla formatów DAT/ZS2, brak obsługi JKS, którego używało 60% klientów. Rozwiązanie: Zbudowana hybrydowa architektura wywołująca PHP PPOLib poprzez podproces do generowania podpisu, parsowania wyników w Pythonie do dalszego przetwarzania. Kompromis: Dodano 200-300ms opóźnienia na uwierzytelnienie, ale zagwarantowano kompatybilność ze wszystkimi formatami kluczy.

Wieloformatowa obsługa kluczy: Klienci dostarczali klucze w 4 formatach z różnymi konwencjami przechowywania certyfikatów. JKS przechowuje cert+key razem; DAT/ZS2/PFX przechowują oddzielnie, wymagając plików EU-*.cer w tym samym katalogu. Rozwiązanie: Izolacja katalogu tymczasowego — skopiuj przesłany plik + skanuj sąsiednie pliki .cer, przekaż ścieżkę katalogu do podpisującego PHP. Obsługa przypadków brzegowych: Gdy brakuje .cer, wyodrębnij dane podmiotu z podpisanej odpowiedzi zamiast zawieść.

Niespójność wyodrębniania IPN: Lokalizacja numeru podatkowego (IPN) różni się w zależności od urzędu certyfikacji — nowsze certyfikaty używają rozszerzenia OID 1.2.804.2.1.1.1.11.1.4, starsze certyfikaty osadzają w polu CN lub serial_number. Rozwiązanie: Zaimplementowano łańcuch zapasowy: (1) Spróbuj OID subject_directory_attributes, (2) Przeszukaj Regex CN pod kątem 10-cyfrowego wzorca, (3) Przeszukaj serial_number, (4) Zwróć częściowy zamaskowany IPN, jeśli wszystko zawiedzie. Dane produkcyjne: 78% wyodrębnione przez OID, 19% przez CN regex, 3% wymagało ręcznej weryfikacji.

Bezpieczeństwo tokena vs. wydajność: Tokeny uwierzytelniające muszą być cachowane (ponowne uwierzytelnianie przy każdym wywołaniu API spowodowałoby limity szybkości), ale przechowywanie tokenów w postaci jawnej tworzy odpowiedzialność audytową. Rozwiązanie: Szyfrowanie symetryczne Fernet z kluczem pochodnym środowiska, przechowywane jako niestandardowy EncryptedTextField. Szyfrowanie/deszyfrowanie następuje na warstwie modelu, przezroczyste dla kodu widoku. Wpływ na wydajność: ~5ms na operację tokena, znikomy w porównaniu do 800ms API round-trip.

Strumieniowanie PDF bez przechowywania: Rządowe raporty mogą mieć 2-5MB, tymczasowe przechowywanie wypełniłoby dysk w dni dużego natężenia. Rozwiązanie: Python requests z stream=True + Django StreamingHttpResponse — bajty nigdy nie trafiają na dysk, przesyłane bezpośrednio z upstream API przez Django do przeglądarki klienta. Wyzwanie: Debugowanie uszkodzenia strumienia wymagało implementacji logowania żądań na poziomie bajtu, ponieważ błędy nie były widoczne w normalnych logach.

Wykrywanie przestarzałego tokena: Zaszyfrowane tokeny mogą być ważne w DB, ale wygasłe po stronie rządowej. Rozwiązanie: Zaimplementowano znacznik czasu token_created_at + proaktywne odświeżanie 7 dni przed wygaśnięciem. Przy niepowodzeniu synchronizacji spróbuj ponownego uwierzytelnienia przed zgłoszeniem błędu użytkownikowi. Zmniejszono zgłoszenia wsparcia "zepsutej synchronizacji" o 85%.

Zmniejszono nakład pracy na monitorowanie podatków z 2-3 godzin dziennie do poniżej 15 minut. Wyeliminowano ręczne zarządzanie plikami kluczy na wielu urządzeniach — przedsiębiorcy przesyłają zaszyfrowany JKS raz, system obsługuje wszystkie kolejne uwierzytelnienia. System powiadomień skrócił średni czas odpowiedzi na komunikaty rządowe z 48 godzin do tego samego dnia, poprawiając zgodność. Dostęp wieloużytkownikowy umożliwił firmom księgowym obsługę ponad 5 klientów przez jeden interfejs zamiast żonglowania oddzielnymi danymi uwierzytelniającymi. Proxy raportów PDF usunęło workflow pobierania/ponownego przesyłania, skracając czas przetwarzania dokumentów o 70%. Automatyczna synchronizacja eliminuje problemy z logowaniem, co skutkuje 90% redukcją scenariuszy zapomnianych haseł. Uprawnienia oparte na rolach zapewniły dziennik audytu działań księgowych, rozwiązując obawy klientów dotyczące bezpieczeństwa.

Przestarzała infrastruktura nie zawsze jest długiem technicznym: Początkowy instynkt polegał na przepisaniu kryptografii PHP w czystym Pythonie. Kosztowałoby to ponad 80 godzin budowania implementacji DSTU 4145-2002 od zera vs. 8 godzin owijania istniejącego rozwiązania PHP. Czasami wywołania podprocesów biją wynajdywanie kół na nowo — zwłaszcza dla krytycznej zgodności kryptografii, gdzie błędy = luki bezpieczeństwa.

Heterogeniczne formaty kluczy są rzeczywistym ograniczeniem: Próba przekonania klienta do standaryzacji tylko na JKS. Banki wydają to, co wydają; PrivatBank wciąż dostarcza pliki DAT w 2024 roku. Elastyczność systemu do obsługi "formatu, który klienci faktycznie mają", była cenniejsza niż inżynieryjna elegancja obsługi jednego formatu doskonale.

Parsowanie certyfikatów jest bardziej chaotyczne, niż sugeruje dokumentacja: Standardy OID istnieją, ale CA nie zawsze ich przestrzegają. Produkcja napotkała certyfikaty z IPN w polu CN sformatowane jako "ПІДПРИЄМЕЦЬ 1234567890", "ІПН:1234567890" i "1234567890 / ПІБ". Zapasowy Regex nie był leniwym kodowaniem — to było przyjęcie, że emitenci certyfikatów nie czytają specyfikacji dokładnie.

Obsługa wygaśnięcia tokena zapobiega wypaleniu wsparcia: Pierwsza wersja nie miała proaktywnego odświeżania — tokeny wygasały w ciszy, użytkownicy zgłaszali "zepsutą synchronizację". Implementacja token_created_at + 7-dniowe odświeżanie przed wygaśnięciem zmniejszyło reaktywne zgłoszenia wsparcia o 85%. Małe pole bazy danych zwróciło się w zaoszczędzonym czasie programisty w ciągu 2 tygodni.

Strumieniowanie dużych plików ma znaczenie w skali: Początkowa implementacja zapisywała pliki PDF w /tmp, a następnie je serwowała. Wypełniła 50GB dysku w 3 dni podczas sezonu podatkowego. Przejście na strumieniowanie całkowicie wyeliminowało przechowywanie — właściwe rozwiązanie dla punktów końcowych proxy niezależnie od obecnej objętości danych.

Wzorce dostępu wieloużytkownikowego ujawniają się powoli: Pierwsze 2 miesiące tylko starszy księgowy używał systemu. Miesiąc 3, zatrudniony młodszy personel ujawnił błędy uprawnień — mogli widzieć dane wszystkich klientów. Dostęp oparty na rolach nie był przedwczesną optymalizacją; był istotną funkcją, która ujawniła się tylko wtedy, gdy wystąpił rzeczywisty scenariusz wieloużytkownikowy. Buduj RBAC od początku, nie modernizuj.