Integracja sklepu z Subiekt GT - Sfera, API i praktyka

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. Szczegóły po tamtej stronie opisałem w integracji z Subiekt nexo.

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ł).

Co dalej

• Następny krok z GT: Integracja z Subiekt nexo
• 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

Najczęstsze pytania