Integracja sklepu z Subiekt GT - Sfera, API i praktyka

W skrócie

• 1. API: Sfera Subiekta - dedykowane SDK COM/.NET, działa tylko z Windows. Brak natywnego REST.
• 2. Synchronizacja: wszystko przez Sferę. Realtime - trudny, batch - domyślny.
• 3. Cenniki kontraktowe: są (cenniki indywidualne, rabaty grupowe), ale model uboższy niż w Comarch XL.
• 4. Limity wydajnościowe: GT trzyma dane w pliku, nie pełnej bazie danych. Przy 20k+ SKU i kilkudziesięciu kontrahentach jednocześnie - zaczyna lagować.
• 5. Migracja GT → nexo: wcześniej czy później; dobrze projektować integrację z myślą o tym.

Czym jest Subiekt GT - i dlaczego ma sufity

Subiekt GT to ERP od InsERT-u, najpopularniejszy w polskim segmencie MŚP. Działa od ~2003 roku, ostatnia wersja 1.74 (2025). InsERT równolegle rozwija nexo (linia nowsza, oparta na SQL Server) i sygnalizuje, że GT jest stopniowo wygaszane.

Co GT robi dobrze:

• Pełna funkcjonalność ERP dla firmy 10-50 osób: faktury, magazyn, kasa, środki trwałe
• Bardzo dobra obsługa polskiej księgowości i specyficznych przepisów
• Niska cena (jednorazowa licencja ~3 tys. zł), niski koszt utrzymania
• Sfera - dedykowane SDK do integracji

Czego nie zrobi:

• Realnego API REST. Sfera to COM/.NET - działa pod Windows, integracja z systemem Linux-owym sklepu wymaga warstwy pośredniej
• Skalowania powyżej kilkudziesięciu tysięcy SKU - pliki danych GT mają fizyczne ograniczenia
• Pracy współbieżnej dużej liczby użytkowników (powyżej ~30 jednoczesnych staje się problemem)
• Pełnego modelu cenników B2B porównywalnego z Comarch XL czy SAP

Sfera Subiekta - jak działa integracja

Sfera to oficjalne SDK od InsERT-u. Pozwala na pełną integrację z GT, w tym:

• Pobieranie listy towarów, kontrahentów, dokumentów
• Tworzenie dokumentów (zamówień, faktur)
• Wystawianie dokumentów handlowych
• Operacje magazynowe

Ograniczenia techniczne:

• COM/.NET - Sfera działa tylko pod Windows
• Wymaga licencji na każde stanowisko, na którym uruchamiana
• Jednoczesnych sesji Sfery jest niewiele (zazwyczaj 2-5)
• Komunikacja synchroniczna - nie ma webhooków, są tylko polly

Praktyczne wnioski:

• Sklep (najczęściej Linux + PHP) nie może rozmawiać ze Sferą bezpośrednio
• Musisz mieć serwer Windows-owy (lub VM) z usługą-mostem
• Most konwertuje wywołania REST/JSON od sklepu na Sferę i z powrotem

Architektura wdrożenia

[Sklep Magento / Shopware]
        |
        | REST
        v
[Middleware / Most (Windows VM)]
        |
        | Sfera (COM/.NET)
        v
[Subiekt GT (Windows)]

Średnio: VM z 4 vCPU + 8 GB RAM + SSD wystarcza do średniego sklepu z GT. Most piszemy najczęściej w C# (.NET) - to natywne środowisko Sfery. Wystawia REST API dla sklepu, w środku ma kolejkę i logi.

Alternatywa: produkty komercyjne typu „Subiekt GT WebAPI" (kilku dostawców na rynku, ~1-3 tys. zł licencja). Działają, ale dla nietrywialnych integracji szybko trafiasz na ograniczenia.

Co synchronizujemy i jak

Towary:

• GT → sklep, batch w nocy + delta co 30 min
• Pola: symbol, nazwa, opis, jednostka, stawka VAT, ceny katalogowe, EAN
• Atrybuty filtrowalne ubogie - najczęściej dorabia się w sklepie lub PIM

Kontrahenci:

• GT → sklep, on-demand (przy rejestracji klienta w sklepie sprawdzamy w GT po NIP)
• Kontrahent jako master tylko w GT - sklep nie tworzy, tylko aktywuje

Ceny i cenniki:

• GT ma cenniki indywidualne (per kontrahent) + grupy + rabaty
• Sfera daje metodę „policz cenę kontrahenta dla towaru" - wykorzystujemy
• Cache 10-15 min, klucz (kontrahent_id, sku)

Stany magazynowe:

• GT → sklep, delta co 5-10 min (pełna synchro 50k SKU za długo)
• Pull on-demand dla konkretnego towaru, gdy klient go ogląda
• Cache 30s

Zamówienia:

• Sklep → GT przez Sferę: tworzenie ZK (zamówienie od klienta) lub od razu FS (faktura sprzedaży, zależnie od polityki)
• Idempotencja po numer_referencyjny_klienta (dodatkowe pole w GT)

Statusy i dokumenty:

• GT → sklep przez polling co 5-10 min
• Status zamówienia, numer WZ, numer faktury, PDF faktury (generowany w GT, pobierany przez Sferę)

Cenniki w GT - co realnie można

GT ma w cennikach:

• Cenniki indywidualne - per kontrahent, można stawkę albo procent
• Cenniki grupowe - przypisane do grup kontrahentów
• Rabaty stałe - globalne / na grupę
• Promocje - czasowe (od/do)

Czego nie ma natywnie:

• Progów ilościowych (od 100 szt. cena X, od 500 szt. cena Y) - przy GT to zwykle obchodzimy w sklepie
• Cenników na poziomie grupy towarowej dla konkretnego kontrahenta
• Workflow akceptacji cen

W praktyce: jeśli twój model cenowy B2B wymaga progów ilościowych albo rabatów per kategoria per kontrahent - GT to zacznie męczyć w pierwszym roku. Wtedy część logiki cenowej trafia do sklepu, co rozjeżdża się z fakturami.

To moment, w którym mówię klientom: rozważ nexo lub XL.

Wydajność i sufity

Z czterech wdrożeń, sufity GT zaczynały być realne przy:

• ~15k SKU + ~200 kontrahentów aktywnie kupujących
• ~30 użytkowników wewnętrznych w GT jednocześnie
• ~500 zamówień dziennie ze sklepu

Powyżej tych liczb pojawiają się:

• Wolne odpowiedzi Sfery (4-8 s na zapytanie zamiast 0.5 s)
• Konflikty zapisu (kilka procesów próbuje jednocześnie zapisać dokument)
• Częstsze blokady plików danych

Co da się zrobić:

• Rozdzielić integrację na osobne konta Sfery (osobne dla synchronizacji vs. zamówień)
• Cache cen i stanów agresywniej
• Batche w nocy zamiast w godzinach pracy działu sprzedaży

Czego nie da się zrobić:

• Przeskoczyć ograniczeń plikowych GT - to architektura

Migracja GT → nexo PRO

Wcześniej czy później większość rosnących firm na GT przejdzie na nexo (głównie nexo PRO, wariant rozszerzony). To osobny ERP - inne API (REST nexo Web API), inna baza (SQL Server), inny model danych.

Wnioski z mojej praktyki:

1. Projektuj integrację Sfery z założeniem, że za 2-3 lata będzie podmiana na nexo. Warstwa middleware (most) ma to ułatwiać: kontrakt REST dla sklepu zostaje, zmienia się tylko backend mostu.
2. Mapowania danych (kategorie, atrybuty, słowniki) trzymaj w middleware, nie w sklepie. Migracja GT → nexo to wtedy refactor jednego komponentu, nie projekt na pół roku.
3. Migracja samego ERP (GT → nexo, dane historyczne) jest projektem klienta z InsERT-em. Twój sklep ma być na to przygotowany, ale nie ty go robisz.

Najczęstsze problemy

1. Brak webhooków = polling. Każda zmiana w GT wymaga, żeby most spytał. Polling co 5 min = 5 min opóźnienia widoczne dla klienta. Cykl jest do akceptacji w B2B, w B2C bywa za wolno.

2. Licencje Sfery. Każda jednoczesna sesja Sfery wymaga licencji stanowiskowej. Sklep wykorzystujący Sferę intensywnie potrzebuje 3-5 licencji. To rzecz, którą klient kupuje od swojego dostawcy InsERT-u, nie my.

3. Drobne zmiany w GT psują integrację. Aktualizacja GT zmienia subtelne zachowania Sfery. Testy integracyjne przy każdej aktualizacji to obowiązek.

4. Encoding. GT trzyma Windows-1250. Sfera zwraca to różnie zależnie od wersji. Encoding everywhere - must-have.

5. Brak transakcyjności na poziomie integracji. Jeśli sklep wysyła zamówienie i Sfera zwraca timeout - nie wiesz czy dokument powstał. Idempotencja przez numer referencyjny ratuje skórę.

Koszt i czas

Czas wdrożenia integracji:

• MVP (produkty + ceny + stany): 6-8 tygodni
• Pełna integracja (z zamówieniami, dokumentami): 12-16 tygodni
• Stabilizacja: 4-6 tygodni

Koszt:

• Wdrożenie: 60-140 tys. zł (zależnie od scope)
• Licencje Sfery (po stronie klienta): 1-3 tys. zł / stanowisko
• Most na VM Windows: 200-600 zł / mies. (VM + Windows Server licencja)
• Utrzymanie: 8-20 tys. zł rocznie

Trochę taniej niż XL, znacznie taniej niż SAP. Ale „taniej" znika, gdy w drugim roku robisz migrację na nexo (kolejne 50-150 tys. zł).

FAQ

Czy integracja GT ↔ Magento działa na PHP bez serwera Windows? Nie wprost. Sfera wymaga Windows. Możesz mieć serwer Linux dla samego sklepu, ale moduł integracji (most) musi siedzieć na Windowsie.

Czy InsERT planuje REST API dla GT? Plany nigdy nie były ogłoszone oficjalnie. InsERT pcha nexo, dla którego REST już istnieje. GT prawdopodobnie zostanie z Sferą do końca życia.

Czy mogę pominąć most i pisać wprost C# z Sfery do API Magento? Technicznie tak, ale to antywzorzec. Most wprowadza warstwę abstrakcji (REST), która przeżyje migrację na nexo. Bezpośrednia integracja wymusi przepisanie wszystkiego.

Czy GT obsługuje wielowalutowość dla cenników B2B? W ograniczonym zakresie. Cenniki w PLN to standard, walutowe wymagają dodatkowych modułów + workflow w księgowości.

Czy mogę używać BaseLinkera między GT a sklepem? Tak, do prostych przepływów (synchronizacja stanów, zamówienia z marketplace'ów). Dla pełnego B2B z cennikami kontraktowymi - niewystarczające. BaseLinker w sklepie B2B.

Co dalej

• Większe ERP-y: Comarch ERP XL, enova365, SAP
• Architektura integracji: Middleware vs. bezpośrednio
• Platforma sklepu: Magento dla B2B
• Pełny przegląd integracji: pillar /integracje