Najbardziej prymitywnym, a zarazem najczęściej spotykanym sposobem na integrację zewnętrznych systemów z systemami ERP jest tzw. polling. To sytuacja, w której Twój system SaaS, dedykowana aplikacja mobilna lub sklep internetowy co 5 minut (lub, co gorsza, co kilkadziesiąt sekund) wysyła do serwera bazodanowego zapytania typu: „Czy pojawił się nowy produkt? A teraz? A czy zmieniła się cena towaru X?”.
Taka naiwna architektura generuje gigantyczny, całkowicie bezużyteczny ruch sieciowy, drastycznie marnuje zasoby procesora na serwerze SQL klienta, a na koniec i tak pozostawia system z irytującym opóźnieniem w danych. W dobie natychmiastowych procesów biznesowych to rozwiązanie niedopuszczalne.
Budując nowoczesną, skalowalną integrację i wykorzystując API dla Subiekt Nexo, musisz porzucić architekturę odpytywania i przejść na model sterowany zdarzeniami (Event-Driven Architecture). Zamiast bezustannie marnować cykle procesora na zapytania o stan, Twój zewnętrzny system chmurowy powinien zostać natychmiast, asynchronicznie powiadomiony dokładnie w tym momencie, kiedy w lokalnej bazie InsERT wydarzy się określona akcja biznesowa.
Tunelowanie i komunikacja dwukierunkowa w Subiekt Bridge
Pierwszą barierą architektoniczną, z jaką zderza się deweloper chcący wdrożyć tradycyjne Webhooki w systemach ERP, jest topologia sieci klientów końcowych. Ponad 90% lokalnych instalacji Subiekta (zarówno w wersji Nexo PRO, jak i GT) działa w sieciach wewnętrznych za NAT-em, bez publicznego, statycznego adresu IP i bez wdrożonych certyfikatów SSL. Oznacza to, że Twój serwer chmurowy nie może po prostu wysłać żądania HTTP POST do lokalnego komputera w biurze klienta, bo ten jest fizycznie niewidoczny dla otwartego Internetu.
Subiekt Bridge rozwiązuje ten problem fundamentalnie poprzez zastosowanie odwróconej architektury połączeń, opartej na zaawansowanym tunelowaniu strumieniowym (wykorzystującym technologię zbliżoną do gRPC oraz długożyjących połączeń WebSockets/SignalR).
Podczas startu systemu, lokalny Agent Bridge inicjuje bezpieczne, szyfrowane nagłówkami HMAC połączenie wychodzące do chmurowego Gatewaya Subiekt Bridge. Kanał ten pozostaje stale otwarty i działa w trybie Full-Duplex. Kiedy w Subiekcie zachodzi jakakolwiek zmiana, Agent błyskawicznie przesyła paczkę danych „w górę” przez istniejący już tunel. Dla Twojego systemu chmurowego oznacza to, że odbierasz zdarzenia tak, jakby lokalny Subiekt znajdował się w tej samej sieci prywatnej.
Mapowanie zdarzeń ERP na zunifikowane kontrakty JSON
Dzięki bezpośredniemu nasłuchiwaniu niskopoziomowych mechanizmów bazy danych oraz ścisłej integracji z kontekstem wykonawczym Sfery, Subiekt Bridge przechwytuje kluczowe zdarzenia biznesowe. Zamiast zmuszać programistę do parsowania logów czy triggerów, middleware mapuje te zdarzenia na czysty, czytelny i zunifikowany kontrakt JSON, zachowujący spójną konwencję camelCase (np. documentId, customerNip).
[Modyfikacja obiektu w Subiekcie] ──> [Bridge Agent przechwytuje event] ──> [Push JSON przez tunel] ──> [Twój system SaaS]
Dzięki takiemu podejściu, Twoja aplikacja webowa lub platforma e-commerce może w czasie rzeczywistym (Real-time) reagować na krytyczne akcje systemowe:
Asortyment.CenaZmieniona– Kiedy handlowiec w stacjonarnym programie desktopowym zmodyfikuje cenę hurtową lub przypisze produkt do nowego cennika, event natychmiast pushuje nową wartość do chmury. Twój sklep internetowy aktualizuje cenę na froncie w ułamku sekundy, eliminując ryzyko, że klient kupi towar po starej, nieaktualnej cenie.Dokument.WystawionyWZ– Moment, w którym magazynier kończy pakowanie i zatwierdza Wydanie Zewnętrzne w Subiekcie, generuje automatyczny event. Twój SaaS natychmiast wie, że zamówienie fizycznie opuściło magazyn, dzięki czemu może automatycznie wysłać do klienta wiadomość e-mail z linkiem do śledzenia paczki lub powiadomienie SMS.Kontrahent.Dodany– Każda nowa kartoteka założona w biurze obsługi klienta jest automatycznie przesyłana do chmury, zapewniając idealną synchronizację z zewnętrznymi systemami CRM lub systemami helpdesk.
Trzy złote zasady obsługi zdarzeń w integracjach z systemami InsERT
Przejście na architekturę sterowaną zdarzeniami wymaga od programisty zmiany sposobu myślenia o przetwarzaniu danych. Aby integracja była stabilna, odporna na awarie sieciowe i nie zatykała bazy danych, w swoim kodzie musisz zaimplementować trzy kluczowe wzorce projektowe:
1. Bezwzględna Idempotentność Endpointów
W systemach rozproszonych i przy połączeniach hybrydowych istnieje zjawisko tzw. at-least-once delivery (dostarczenie przynajmniej raz). Z powodu mikro-przerw w łączności lub rekonfiguracji tunelu sieciowego, ten sam event (np. informacja o wpłacie czy zmianie stanu) może zostać przesłany przez Subiekt Bridge dwukrotnie.
Twój endpoint odbierający te dane musi być idempotentny. Oznacza to, że przed przetworzeniem zdarzenia Twój kod powinien sprawdzić unikalny identyfikator operacji lub pole rowVersion/TimeStamp i upewnić się, czy ta konkretna modyfikacja nie została już wcześniej zaaplikowana w Twojej chmurze.
2. Przetwarzanie Asynchroniczne (Pattern: Fire-and-Forget)
To jeden z najczęstszych błędów deweloperskich. Gdy Twój serwer otrzyma webhooka/event z Subiekt Bridge (np. o wystawieniu nowego zamówienia ZK), Twój kontroler HTTP nie może w tym samym wątku zacząć wykonywać ciężkich operacji, takich jak generowanie faktur PDF, wysyłanie maili przez zewnętrzne API, czy synchronizacja obrazków.
Prawidłowy przepływ polega na natychmiastowym zapisaniu surowego payloadu JSON do szybkiej kolejki w tle (np. RabbitMQ, Redis, Amazon SQS) i natychmiastowym zwróceniu do Bridge statusu HTTP 200 OK. Ciężka logika biznesowa musi być procesowana asynchronicznie przez dedykowane procesy robocze (Background Workers). Dzięki temu kanał komunikacyjny z lokalnym Agentem pozostaje wolny i drożny.
3. Implementacja Wzorca Circuit Breaker
Serwery lokalne u klientów bywają wyłączane (np. podczas prac konserwacyjnych w weekendy lub awarii zasilania w biurze). Jeśli Twój system SaaS zacznie masowo wysyłać zapytania modyfikujące do niedostępnego Agenta, doprowadzisz do wyczyszczenia puli połączeń (Connection Pool) i awarii własnej aplikacji.
Zaimplementuj mechanizm Circuit Breaker (Bezpiecznik). Jeśli API wykryje serię nieudanych prób kontaktu z lokalną stacją Subiekta, automatycznie „rozłącza obwód”, kolejkuje żądania lokalnie w chmurze i ponawia próby w trybie wykładniczym (Exponential Backoff), chroniąc stabilność całego ekosystemu.