Sfera dla Subiekta GT: przewodnik programisty po integracji

Po co ten przewodnik

Wczoraj opisałem pięć różnych rzeczy, które w Comarch Optima nazywa się „API". Subiekt GT to druga połowa tej pary i ma problem dokładnie odwrotny. Przy Optimie pytanie brzmi, na który interfejs właśnie patrzysz. Przy Subiekcie GT jest jeden, każdy znajduje go w dziesięć minut, a potem zespoły spędzają trzy tygodnie na odkrywaniu, czym on właściwie jest.

Nazywa się Sfera. I nie jest API w tym znaczeniu, w jakim używasz tego słowa w 2026 roku.

To subiektowy odpowiednik mojego przewodnika po enova365 WebAPI oraz porównania Subiekta, Optimy i enova365 od strony integracji. Każde twierdzenie techniczne poniżej pochodzi z dokumentacji InsERT-u, z opublikowanego cennika albo z kodu open source, który możesz sam przeczytać. Nic nie jest zmyślone, bo w tym kawałku rynku wymyślona nazwa obiektu kosztuje kogoś cały dzień.

Czym Sfera właściwie jest

Opis InsERT-u jest precyzyjny i trzeba go czytać dosłownie: Sfera „umożliwia napisanie rozszerzeń, korzystających z wewnętrznych mechanizmów Subiekta GT", zbudowana w oparciu o technologie COM i OLE Automation.

Rozłóż to na części, a jeszcze zanim napiszesz linijkę kodu, spadną na Ciebie trzy konsekwencje:

Działa na Windows, obok zainstalowanego Subiekta. Nie w Twoim kontenerze, nie w Twoim centrum danych, nie z linuksowej maszyny, na której stoi już Twoja aplikacja. W tym projekcie jest host Windows. Ktoś musi go mieć, łatać i za niego płacić — i z mojego doświadczenia to ta jedna pozycja, która nigdy nie trafia do pierwszej wyceny.

Przechodzi przez własną logikę Subiekta. To jest powód, żeby wybrać Sferę zamiast bazy, i to powód prawdziwy. Dokumenty tworzone przez Sferę dostają numer, cenę, ruch magazynowy i walidację dokładnie tak, jakby ktoś wyklikał je ręcznie. To, co wpiszesz wprost do tabel, nie dostaje niczego.

To dodatek, który się kupuje. Sfera nie jest częścią Subiekta GT. To osobna licencja, a ta licencja ma kształt, który zaskakuje. O tym za chwilę.

Sfera istnieje dla pięciu programów linii — Subiekt GT, Rewizor GT, Gestor GT, Gratyfikant GT i sam InsERT GT. To ma większe znaczenie, niż brzmi.

Połączenie ma dwie tożsamości

Model obiektowy mieści się w akapicie. Tworzysz obiekt COM o identyfikatorze InsERT.GT, ustawiasz na nim właściwości i wołasz Uruchom.

Właściwości to Serwer, Baza, Uzytkownik, UzytkownikHaslo, Operator, OperatorHaslo, Autentykacja i Produkt. Przeczytaj tę listę jeszcze raz, bo zawiera najważniejszy architektonicznie fakt o Sferze i łatwo go przeoczyć:

Są dwa komplety poświadczeń. Uzytkownik i UzytkownikHaslo to login do Microsoft SQL Servera. Operator i OperatorHaslo to operator Subiekta — czyli konto człowieka wewnątrz ERP. Twoja integracja uwierzytelnia się dwa razy, na dwóch warstwach, z dwoma różnymi modelami uprawnień.

Pisałem niedawno cały tekst o tym, co naprawdę znaczy „tylko do odczytu" przy koncie serwisowym, i to jest najczystszy przykład tego problemu, jaki widziałem w polskich ERP-ach. Kiedy ktoś na spotkaniu mówi, że konto integracji jest read-only, zapytaj, które z dwóch ma na myśli. Login SQL nie dziedziczy żadnych ograniczeń operatora. Ograniczenia operatora nie obowiązują na loginie SQL. Oba nazywa się w jednym zdaniu „kontem integracji".

Produkt wybiera program z linii, do którego się podłączasz — Subiekt GT to 1, Rachmistrz 2, Rewizor 3, Gratyfikant 4, mikroGratyfikant 5, Gestor 6. A Uruchom(tryb_dostosowania, tryb_uruchomienia) zwraca obiekt aplikacji, na którym faktycznie pracujesz.

Drugi argument Uruchom to Twoja architektura

Tryb uruchomienia to mała liczba całkowita i decyduje o Twoim systemie bardziej niż cokolwiek innego, co napiszesz w tym tygodniu:

• 0 — uruchom aplikację, o ile nie znajdzie się działająca, do której można się podłączyć.
• 1 — to samo, ale podłącz się tylko wtedy, gdy działająca instancja nie jest w stanie zablokowanym (Subiekt blokuje się m.in. podczas startu, sprawdzania licencji i zmiany użytkownika przez Ctrl+F2).
• 2 — zawsze uruchom nową instancję.
• 4 — podłącz się albo uruchom bez interfejsu użytkownika. Aplikacja działa w tle.

Tryb 4 to ten, którego chce integracja. Zaskakująco dużo pierwszych podejść go nie używa — i tak powstaje okno Subiekta otwierające się na serwerze, na który nikt nie patrzy. Tryb 2 to ten, który kosztuje: nowa instancja na każde zadanie to nowe logowanie na każde zadanie, a logowanie zajmuje stanowisko licencyjne dokładnie tak samo jak człowiek.

Uwagi o stanie zablokowanym z trybu 1 też nie pomijaj. Start, sprawdzanie licencji i zmiana operatora to stany, w których Subiekt istnieje jako proces, ale nie jest gotowy. Integracja, która zakłada „proces istnieje, czyli da się podłączyć", będzie się wykładać z doskoku — a przez pierwsze dwa dni wygląda to na problem sieciowy.

Sfera jest wyceniana per program i per stanowisko

Z cennika detalicznego InsERT-u obowiązującego od 2 stycznia 2026 r. — sprawdź aktualny, zanim wycenisz, ale struktura się nie zmienia:

Pozycja	Netto PLN
Sfera dla Subiekta GT (dodatek do Subiekta, którego już masz)	1 045
— rozszerzenie na kolejne stanowisko	655
Subiekt GT Sfera (pakiet)	2 090
Sfera dla Rewizora GT	1 975
Sfera dla Gratyfikanta GT	1 915
Sfera dla Gestora GT	875

Rozmowę zmieniają trzy ostatnie wiersze. Sferę kupuje się per program. Integracja wystawiająca dokumenty sprzedaży potrzebuje Sfery dla Subiekta GT. W momencie, w którym zakres rośnie o „i jeszcze zaksięgujmy to", wchodzi Rewizor GT i druga licencja Sfery — prawie dwa razy droższa od pierwszej.

Podnieś to na pierwszym spotkaniu, nie przy fakturze. „Obsłużymy też stronę księgową" brzmi jak drobne rozszerzenie zakresu. Licencyjnie to ten większy zakup.

Piętnaście dni darmowej pewności

InsERT udostępnia wersję próbną Sfery. Włącza się ją ikoną Sfery na pasku narzędzi programu i działa 15 dni, po czym Sfera wygasa, a wszystko, co na niej zbudowano, przestaje działać do czasu zakupu i aktywacji licencji.

Prawie nikt z tego nie korzysta. A to najcenniejsze piętnaście dni dostępne w projekcie na Subiekcie — nie po to, żeby zbudować integrację, tylko żeby odpowiedzieć na jedno pytanie: czy dokumenty, na których stoi ten projekt, faktycznie dają się wystawić na bazie tego klienta, przy tej konfiguracji? Stany magazynowe, cenniki, jednostki, pola wymagane, które ktoś dodał w 2019 roku, i obowiązujące uprawnienia operatora. To wszystko sprawdzasz w jedno popołudnie z licencją próbną. Albo w piątym tygodniu bez niej.

Wygaśnięcie to też nazwana awaria. Proof of concept zbudowany na wersji próbnej, pokazany na demo i zostawiony działający, kiedy dogadują się warunki handlowe, umiera szesnastego dnia — u klienta, w warunkach produkcyjnych, i nikt się tego nie spodziewa.

Gdzie jest dokumentacja

Publicznej dokumentacji Sfery w internecie nie ma. Ludzie tracą na jej szukanie realny czas.

Dokumentacja jest w instalacji. W programie: Pomoc → InfoSfera, potem F1 do modułu pomocy. Na dysku to plik CHM w katalogu InsERT-u — a sama ścieżka mówi Ci coś, co musisz wiedzieć:

C:\Program Files (x86)\InsERT\InsERT GT\Pomoc\gta.chm

(x86). Trzydzieści dwa bity.

Dlatego najczęstsza awaria pierwszego dnia to projekt .NET zbudowany jako AnyCPU na maszynie 64-bitowej, rzucający „Klasa niezarejestrowana" na obiekcie COM, który jest zarejestrowany całkiem poprawnie — tylko nie dla procesu 64-bitowego. Ustaw x86 i błąd znika. Pięciominutowa poprawka, która regularnie kosztuje pół dnia, bo komunikat wskazuje na rejestrację, a przyczyną jest bitowość.

Awarie, pod które trzeba projektować

Znika serwer RPC. Sfera trzyma żywe połączenie z działającym subiekt.exe. Jeśli ten proces się skończy — użytkownik zamknie program, aktualizacja go zrestartuje, maszyna wstanie w nocy — Twój uchwyt do obiektu jest martwy i sam się nie naprawi. Integracja musi to wykryć i połączyć się ponownie. Jeśli tego nie robi, objawem jest usługa, która działała sześć tygodni i po cichu przestała. Ten sam kształt awarii, który opisywałem przy nieoglądanych zadaniach z harmonogramu w enova365.

Stanowisko licencyjne na koniec miesiąca. Opisane wyżej. Zapytaj, ile stanowisk ma instalacja, zanim zaprojektujesz pętlę odpytywania, a nie po.

Zapis wprost do SQL. Z bazy czytaj swobodnie — raportowanie z tabel Subiekta to normalna praktyka i działa. Zapisuj, a ominąłeś logikę biznesową, która była jedynym powodem, żeby w ogóle sięgać po Sferę, wyprodukowałeś dokumenty, w które Subiekt nie do końca wierzy, i wyszedłeś poza teren, na którym wsparcie InsERT-u może Ci pomóc.

Dryf wersji. Subiekt GT wciąż jest rozwijany — wersja 1.89 niesie bieżącą falę zmian wokół KSeF, w tym nowe pola referencji KSeF na rozrachunkach. Dobra wiadomość o platformie i stałe zobowiązanie dla Ciebie: ERP, który się zmienia, to integracja, którą trzeba regularnie przetestować od nowa. Licencja Sfery i tak wymaga aktywowanej bieżącej wersji programu.

Co zbudowałbym najpierw

Postaw cienką usługę HTTP na hoście Windows, na którym stoi Subiekt, i niech to będzie jedyny komponent w Twoim systemie, który wie o istnieniu Sfery. Twoja aplikacja rozmawia z tą usługą po JSON. Shim pochłania COM, ograniczenie bitowości, logikę ponownego łączenia i przywiązanie do wersji. Wszystko powyżej staje się jednym małym, wymiennym elementem zamiast właściwością całej architektury.

Potem zacznij od odczytów. Stany magazynowe i dane kontrahentów, wystawione tylko do odczytu, z heartbeatem, żeby martwe połączenie było widoczne w kilka minut, a nie przy następnej reklamacji. Tydzień pracy. Daje prawo do rozmowy o wystawianiu dokumentów i przenosi pytania o licencje i uprawnienia z teorii na konkret.

Jeśli ważysz to wszystko wobec projektu przyjmowania zamówień, związek jest bezpośredni: powyższe to hydraulika pod portalem B2B zintegrowanym z ERP, a portal jest miejscem, w którym ta praca się zwraca. Ten sam mechanizm napędza agentów AI dla firm, którzy czytają i uzupełniają dane wprost w systemie.

Zastanawiasz się, czy integracja z Subiektem GT ma sens akurat u Was? Odezwij się — godzina z Waszą instalacją i realnym obiegiem dokumentów powie więcej niż jakakolwiek wycena napisana z listy funkcji.