Subiekt GT + KSeF 2.0: jak spiąć integrację bez blokowania bazy danych i zawieszania kas

1. Dlaczego synchroniczna integracja wiesza Subiekta GT?

Subiekt GT (oraz Navireo i Subiekt Nexo) opiera się na relacyjnej bazie Microsoft SQL Server oraz interfejsie COM Sfery. Standardowy proces wystawienia faktury (FS) z poziomu stanowiska sprzedaży trwa zazwyczaj od 15 do 40 milisekund — transakcja zapisuje rekord w tabeli dok__Dokument, aktualizuje stany magazynowe w tw__Towar i zwalnia locki.

Co się dzieje, gdy do procesu zapisu w Sferze lub triggera AFTER INSERT zostanie podpięte bezpośrednie wywołanie HTTP do API Ministerstwa Finansów?

• Nieprzewidywalny czas odpowiedzi: Ministerialna bramka KSeF w szczycie rozliczeniowym odpowiada w czasie od 800 ms do nawet 15–25 sekund.
• Kaskadowe blokady bazodanowe (Lock Escalation): Dopóki request HTTP wisi, transakcja SQL pozostaje otwarta. Blokada wiersza (Row Lock) szybko eskaluje do blokady strony lub całej tabeli dok__Dokument. Pozostałe stanowiska kasowe w firmie nie mogą w tym czasie zapisać kolejnych dokumentów.
• Błędy 429 i utrata połączenia: Gdy sieć zawiedzie lub KSeF zwróci kod 429 Too Many Requests, niespójna obsługa błędu powoduje rollback całej transakcji lub — co gorsza — wystawienie dokumentu lokalnego bez numeru KSeF i bez śladu audytowego.

2. Wzorzec Outbox Pattern: całkowita izolacja bazy ERP

Prawidłowa inżynieria integracji wymaga zastosowania wzorca Outbox Pattern. Idea jest prosta i niezawodna: proces zapisu dokumentu w Subiekcie GT jest całkowicie odseparowany od wysyłki do KSeF.

W momencie zatwierdzenia faktury, lokalny trigger lub procedura zapisuje lekki wpis do dedykowanej tabeli bufora [dbo].[karp_ksef_outbox] w tej samej milisekundowej transakcji lokalnej. Kasjer natychmiast otrzymuje potwierdzenie, drukuje dokument roboczy lub WZ i obsługuje następnego klienta. Transakcja SQL trwa 12 ms.

3. Worker BullMQ: asynchroniczna orkiestracja i kontrola limitów

Za faktyczną komunikację z Ministerstwem Finansów odpowiada niezależny worker napisany w Node.js, działający w oparciu o kolejki zadań BullMQ. Zapewnia on cztery kluczowe mechanizmy obronne:

1. Kontrola współbieżności (Concurrency = 2): Zgodnie ze specyfikacją MF, przekroczenie dozwolonej liczby równoległych sesji na dany NIP skutkuje natychmiastowym błędem 429. Worker pilnuje limitów bez względu na to, ile faktur wygenerowały kasy w danej minucie.
2. Pre-walidacja FA(2) XSD: Zanim jakikolwiek bajt opuści serwer firmowy, dokument XML jest walidowany lokalnie względem oficjalnego schematu XSD Ministerstwa. Błędny NIP kontrahenta, brak kodu pocztowego lub ujemna stawka są wykrywane w 3 ms — dokument trafia do panelu anomalii z precyzyjną informacją dla operatora, nie marnując puli zapytań KSeF.
3. Wykładniczy backoff (Exponential Backoff): W przypadku chwilowej niedostępności bramki ministerialnej worker ponawia próbę po 5s, 30s, 2 min i 15 min, zamiast bombardować serwer MF i doprowadzać do zablokowania tokena.
4. Zarządzanie sesją i tokenem: Wyzwanie kryptograficzne (challenge) i token sesji interaktywnej są cache'owane w pamięci z twardym odświeżaniem na 5 minut przed wygaśnięciem TTL.

4. Odbiór UPO i dwuetapowa reconciliacja

Wysyłka faktury do KSeF nie oznacza, że dokument został przyjęty. API Ministerstwa Finansów działa asynchronicznie — w odpowiedzi na wysłany XML zwraca elementReferenceNumber oraz status 310 (W trakcie przetwarzania).

Dopiero po zweryfikowaniu podpisów i struktury KSeF nadaje unikalny, 32-znakowy identyfikator oraz wystawia Urzędowe Poświadczenie Odbioru (UPO XML).

Nasz worker odpytuje o status UPO z zachowaniem odstępów czasowych (pooling co 30–60 sekund). Po uzyskaniu statusu 200 (Sukces) wykonuje procedurę zwrotną:

• Pobiera i kryptograficznie weryfikuje plik UPO XML.
• Archiwizuje UPO w bezpiecznym repozytorium plików firmy.
• Uaktualnia w Subiekcie GT pola własne (np. dok_Pole1 = Numer KSeF, dok_Pole2 = Data i godzina rejestracji UPO).
• Generuje kod weryfikacyjny QR zgodny ze specyfikacją MF na potrzeby wydruku PDF dla kontrahenta.

5. Procedura awaryjna (Offline Mode) od 1 lutego 2026

Ustawodawca przewidział sytuacje awaryjne (zarówno po stronie Ministerstwa Finansów, jak i lokalnego łącza internetowego w firmie). W trybie awaryjnym faktury mogą być wystawiane w formacie FA(2) z oznaczeniem trybu offline oraz kodem QR zawierającym skrót kryptograficzny SHA-512.

Architektura Outbox radzi sobie z tym naturalnie: jeśli połączenie z KSeF nie zostanie nawiązane po 3 próbach, dokument automatycznie zyskuje status OFFLINE_EMERGENCY, generowany jest kod QR z hashem, a worker kolejkuje go do wysyłki w oknie statutoryjnym (do końca następnego dnia roboczego).