Własny integrator Base i Subiekta zamiast łańcucha wtyczek: kiedy się opłaca

W wielu firmach zamówienie z Base trafia do Subiekta przez dwie albo trzy wtyczki naraz. Jedna przenosi zamówienia, druga pilnuje stanów, trzecia odsyła numer dokumentu. Każda ma swój abonament, swój harmonogram synchronizacji i swój panel. Gdy zamówienie nie dociera do ERP, trzeba sprawdzić trzy miejsca, zanim wiadomo, które ogniwo stanęło.

Własny integrator zastępuje ten łańcuch jednym przepływem. Potrzebujesz go wtedy, gdy chcesz mieć wszystko po swojej stronie: kod, dane, serwer i log zdarzeń, a za całość odpowiada jeden wykonawca w ramach jednej umowy utrzymaniowej. Zamiast kilku wtyczek, kilku abonamentów i kilku dostawców, z których każdy odpowiada tylko za swój kawałek.

Poniżej opisuję, kiedy taki układ ma sens, co integrator musi robić, jak go zbudować, żeby nie tworzył duplikatów, i kiedy się nie opłaca.

Kiedy potrzebujesz własnego integratora

• chcesz mieć całość u siebie. Kod, konfiguracja i dokumentacja są Twoje, integrator działa na Twoim serwerze obok Subiekta, a dane zamówień nie przechodzą przez serwery kilku zewnętrznych dostawców;
• chcesz jedną umowę utrzymaniową od wszystkiego. Jeden wykonawca odpowiada za cały przepływ: zamówienia, kontrahentów, dokumenty, stany i numery dokumentów. Przy awarii dzwonisz w jedno miejsce i nikt nie odsyła Cię do „drugiej wtyczki”;
• masz dość mnożenia wtyczek. Każda nowa potrzeba to kolejne narzędzie, kolejny abonament i kolejny panel do sprawdzania. W jednym integratorze to kolejna reguła;
• chcesz decydować o terminach. Aktualizację Subiekta albo zmianę w API Base obsługuje Twój wykonawca w ramach umowy, a nie kilku dostawców, każdy we własnym tempie.

Łańcuch wtyczek a jeden przepływ

flowchart LR
  subgraph PRZED["Łańcuch wtyczek"]
    direction LR
    B1[Base] --> W1[Wtyczka: zamówienia]
    W1 --> W2[Wtyczka: kontrahenci i dokumenty]
    W2 --> S1[Subiekt]
    S1 --> W3[Wtyczka: stany]
    W3 --> B1
  end
  subgraph PO["Własny integrator"]
    direction LR
    B2[Base] --> Q[Kolejka i log zdarzeń]
    Q --> S2[Subiekt przez Sferę]
    S2 --> Q
    Q --> B2
  end

Problem łańcucha nie polega na tym, że wtyczki są złe. Każda działa w swoim zakresie. Kłopot pojawia się między nimi:

• brak wspólnego stanu. Wtyczka od dokumentów nie wie, że wtyczka od zamówień pobrała zamówienie dwa razy po restarcie;
• różne harmonogramy. Zamówienia co 5 minut, stany co 15 minut, numer dokumentu co godzinę. W tych przerwach powstają rozjazdy, które obsługa poprawia ręcznie;
• brak jednego logu. Pytanie „gdzie zginęło zamówienie” wymaga przejrzenia kilku paneli, a każdy pokazuje tylko swój fragment;
• aktualizacje bez Ciebie. Każdy dostawca wydaje nowe wersje we własnym tempie. Zmiana w jednym ogniwie potrafi zepsuć przekazanie danych do następnego.

Co integrator musi robić

Zakres dla typowego układu „Base + Subiekt GT albo nexo”:

1. Pobrać zamówienia z Base z dziennika zdarzeń, a nie przez odpytywanie całej listy. Dziennik podaje, co się zmieniło od ostatniego odczytu, więc nic nie umyka po restarcie.
2. Rozpoznać albo założyć kontrahenta w Subiekcie: po NIP dla firm, po e-mailu i adresie dla osób prywatnych, bez zakładania duplikatu przy każdym zamówieniu.
3. Zmapować pozycje: SKU z Base na towar w Subiekcie, zestawy rozbite na składniki, koszt wysyłki jako usługa, stawki VAT według kraju dostawy.
4. Wystawić dokument we właściwym momencie (po opłaceniu, przy statusie „do wysyłki”) i właściwego typu: faktura, paragon albo rezerwacja, zależnie od kanału i klienta.
5. Odesłać numer dokumentu do zamówienia w Base, żeby obsługa widziała go bez otwierania ERP.
6. Wysyłać stany z Subiekta do Base jako zmiany, a nie pełne nadpisanie całego katalogu.
7. Zapisać każde zdarzenie z czasem, identyfikatorem zamówienia i wynikiem.

Jak rozmawiać z Subiektem

Zapis do Subiekta GT i nexo robi się przez Sferę, oficjalny interfejs programistyczny InsERT. Sfera działa na komputerze z Windows, na którym jest zainstalowany Subiekt, i wymaga osobnej licencji. Z tego wynikają dwie decyzje projektowe:

• integrator działa obok Subiekta, na tym samym serwerze albo maszynie w tej samej sieci, a do Base łączy się na zewnątrz. Nie trzeba wystawiać Subiekta do internetu;
• odczyty mogą iść prosto z bazy SQL, zapisy wyłącznie przez Sferę. Bezpośredni zapis do tabel Subiekta omija jego logikę: numerację, rezerwacje i rozrachunki.

Jedno zamówienie, jeden dokument

Najważniejsza właściwość integratora: ponowione zdarzenie nie tworzy drugiego dokumentu. Łańcuch wtyczek tego nie gwarantuje, bo żadna z nich nie widzi całości.

stateDiagram-v2
  direction TB
  [*] --> Pobrane: zdarzenie z dziennika Base
  Pobrane --> Zablokowane: brak SKU albo danych
  Zablokowane --> Pobrane: obsługa poprawia
  Pobrane --> Kontrahent: walidacja OK
  Kontrahent --> Dokument: kontrahent znaleziony albo założony
  Dokument --> Zapisane: Sfera zwróciła numer
  Dokument --> Ponowienie: Subiekt niedostępny
  Ponowienie --> Dokument: Subiekt wrócił
  Zapisane --> Odesłane: numer w zamówieniu Base
  Odesłane --> [*]

Mechanizm jest prosty:

• klucz idempotencji to identyfikator zamówienia w Base. Tabela powiązań trzyma parę „zamówienie Base → numer dokumentu w Subiekcie”;
• przed wystawieniem dokumentu integrator sprawdza tabelę. Jeśli para istnieje, przechodzi od razu do odesłania numeru;
• zapis pary i wystawienie dokumentu są jedną operacją po stronie integratora. Gdy Sfera zwróci numer, a zapis w tabeli się nie uda, przy następnej próbie integrator szuka dokumentu w Subiekcie po numerze zamówienia zapisanym w polu dokumentu, zanim wystawi nowy.

Co się psuje i jak integrator to obsługuje

Bezpieczeństwo i dostęp

• Dane logowania do Sfery i token Base są w magazynie sekretów systemu albo w zmiennych środowiskowych serwera, nie w pliku konfiguracyjnym w repozytorium.
• Konto Sfery ma tylko potrzebne uprawnienia: dokumenty sprzedaży, kontrahenci, odczyt stanów.
• Token Base ma zakres ograniczony do zamówień, produktów i stanów.
• Każda zmiana w ERP ma wpis w logu: kto, kiedy, z jakiego zdarzenia. Log przechowujemy tak długo, jak wymaga tego księgowość.

Monitoring

Integrator pokazuje na jednym ekranie: liczbę zamówień w kolejce, zamówienia zablokowane z powodem, czas od ostatniego udanego zapisu do Subiekta i różnicę stanów między Subiektem a Base dla losowej próbki towarów. Alert idzie e-mailem albo SMS-em, gdy którakolwiek z tych wartości przekroczy próg.

Koszt na trzy lata

Po stronie łańcucha wtyczek liczysz abonamenty wszystkich ogniw, czas obsługi na ręczne poprawki w lukach między nimi i koszt błędów: dokumenty do korekty, nadsprzedaż przy rozjechanych stanach. Szczegółowy rachunek z przykładowymi liczbami jest w artykule gotowa wtyczka czy dedykowana integracja.

Po stronie własnego integratora liczysz jednorazowe wdrożenie (u nas od 15 000 zł netto), serwer, na którym działa obok Subiekta, i utrzymanie rozliczane za faktyczną pracę. Kod i dokumentacja zostają u Ciebie, a utrzymanie całego przepływu obejmuje jedna umowa. Nie płacisz abonamentu za każde ogniwo, nie pilnujesz kilku dostawców i nie czekasz na żadnego z nich przy aktualizacji Subiekta.

Pisanie kodu integracji jest dziś wyraźnie tańsze niż kilka lat temu, bo dużą część klienta API, mapowań i testów generuje się z pomocą modeli językowych. Czas wdrożenia idzie na to, czego modele nie zrobią: ustalenie reguł dokumentów, uporządkowanie SKU i testy na prawdziwych zamówieniach.

Kiedy się nie opłaca

• jedna wtyczka obsługuje cały proces i ręczne poprawki zajmują kilka minut dziennie;
• zamówień jest kilkadziesiąt miesięcznie, a reguły dokumentów są standardowe;
• nie zależy Ci na tym, żeby kod i dane były po Twojej stronie, a jeden abonament gotowego narzędzia w zupełności wystarcza;
• nikt w firmie nie chce odpowiadać za serwer, na którym działa integrator, i nie chcesz podpisywać umowy na utrzymanie.

W takim układzie lepiej uporządkować konfigurację obecnych narzędzi. Zaczynamy wtedy od audytu, a nie od budowy.

Checklista przed uruchomieniem

• Każdy SKU z Base ma odpowiednik w Subiekcie, a lista braków jest pusta.
• Ustalony moment i typ dokumentu dla każdego kanału sprzedaży, spisany i zaakceptowany przez księgowość.
• Test na 50-100 prawdziwych zamówieniach z ostatniego miesiąca: zestawy, zwroty, zamówienia B2B z NIP, wysyłka zagraniczna.
• Test ponowienia: to samo zdarzenie wysłane dwa razy daje jeden dokument.
• Test awarii: Subiekt wyłączony na 30 minut, po włączeniu kolejka schodzi do zera bez duplikatów.
• Alert przychodzi na telefon osoby odpowiedzialnej, sprawdzony na próbę.
• Stare wtyczki wyłączone dopiero po tygodniu równoległej pracy, w którym wyniki obu przepływów się zgadzają.
• Plan powrotu: wiadomo, jak w godzinę wrócić do poprzedniego układu, jeśli coś pójdzie źle.

Jeśli zamówienia z Base do Subiekta idą u Ciebie przez kilka narzędzi, opisz ten układ w formularzu. Odpiszemy, czy wystarczy uporządkować obecne wtyczki, czy lepiej przejść na jeden integrator po Twojej stronie z jedną umową utrzymaniową, i ile to kosztuje w ciągu trzech lat.