Subiekt nexo nie ma REST API. 7 pułapek integracji, które wyjdą po umowie

Spotkanie u klienta, sala z rzutnikiem, na stole plik zamówień z Allegro wydrukowanych do przepisania. Właściciel mówi: „Przecież każdy system ma dziś API. Podłączycie to w tydzień”. Informatyk kiwa głową. Pytam, którą wersję Subiekta nexo mają i czy jest w niej Sfera. Po drugiej stronie stołu robi się cicho.

Ta cisza to nie czyjaś wina. Subiekt nexo jest solidnym programem handlowo-magazynowym, tylko nie jest usługą webową. Nie ma adresu, pod który wyślesz zapytanie HTTP i dostaniesz z powrotem fakturę. Ma za to Sferę i od niej zaczyna się każda uczciwa rozmowa o integracji. Poniżej siedem rzeczy, które w umowach na integrację Subiekta nexo wychodzą za późno, i to, jak rozbrajamy je w naszych wdrożeniach.

Czym jest Sfera i dlaczego zmienia całą architekturę

Sfera to interfejs programistyczny InsERT dla linii nexo. W praktyce to zestaw bibliotek .NET, które ładujesz do własnego programu i przez które pracujesz na obiektach Subiekta: dokumentach, towarach, kontrahentach, cennikach. Twój kod otwiera sesję, podobnie jak użytkownik logujący się do programu, i wykonuje operacje po stronie Subiekta, z jego walidacją i jego numeracją. Sfera jest dostępna w wersji nexo PRO. Jeśli masz zwykłe nexo, to pierwsza rzecz do sprawdzenia w dokumentacji InsERT albo u partnera, który sprzedał Ci licencję.

To zmienia architekturę bardziej, niż się wydaje. Zwykłą integrację z Allegro czy WooCommerce stawia się na serwerze w chmurze: przychodzi webhook, kod coś liczy, wysyła dalej. Ze Sferą tak się nie da. Biblioteki muszą działać na maszynie z Windowsem, na której jest zainstalowany Subiekt nexo PRO i która widzi jego bazę danych. Integracja musi więc mieć „nogę” postawioną obok Subiekta: usługę Windows, która nasłuchuje, kolejkuje i zapisuje. Chmura może obsłużyć resztę, ale ostatni metr zawsze jest lokalny.

W naszych wdrożeniach wygląda to zwykle tak: część odbierająca zdarzenia z marketplace'u i sklepu działa jako usługa, którą można postawić gdziekolwiek, a część rozmawiająca ze Sferą stoi na serwerze klienta, tam gdzie Subiekt. Między nimi jest kolejka i dziennik operacji. O nim za chwilę, bo to on rozbraja dwie z siedmiu pułapek.

Siedem pułapek, które wychodzą po podpisaniu umowy

Kolejność nie jest przypadkowa. Pierwsze trzy dotyczą środowiska i licencji, kolejne trzy danych i zdarzeń, ostatnia tego, co zostaje w firmie po zakończeniu projektu. Każdą opisuję tak samo: co się dzieje, jak boli i jak to rozwiązujemy.

Pułapka 1: nie ma REST API, jest Sfera, wersja PRO i Windows

Co się dzieje. Integrator wycenia projekt jak zwykłe połączenie dwóch API. Po podpisaniu umowy okazuje się, że trzeba dokupić wersję PRO, wskazać maszynę z Windowsem obok Subiekta i ustalić, kto ją utrzymuje. Termin się przesuwa, budżet rośnie, a nikt nie czuje się winny.

Jak to rozwiązujemy. O wersję Subiekta i Sferę pytamy na pierwszej rozmowie, przed wyceną. W audycie opisujemy, gdzie stanie usługa ze Sferą, kto ma do niej dostęp i jak jest monitorowana. Dopiero na tej podstawie podajemy cenę i termin. Jeśli firma ma zwykłe nexo i nie planuje PRO, mówimy to wprost i liczymy razem, czy przejście w ogóle się opłaca.

Pułapka 2: sesja Sfery to stanowisko

Co się dzieje. Integracja loguje się do Subiekta jak użytkownik. W naszych wdrożeniach traktujemy ją jak dodatkowe stanowisko i tak planujemy zakup licencji. Jeśli nikt tego nie policzy, w poniedziałek rano ktoś z biura nie może się zalogować, bo integracja „zajęła miejsce” w nocy i nie zwolniła sesji.

Jak to rozwiązujemy. Usługa trzyma jedną sesję, otwiera ją tylko na czas pracy i zamyka po każdej paczce zamówień. Liczbę stanowisk ustalasz przed wdrożeniem, nie po. Jak dokładnie Twoja licencja liczy sesje Sfery, potwierdź u InsERT lub partnera, bo warunki potrafią się różnić między pakietami i wersjami.

Pułapka 3: aktualizacja Subiekta a wersja bibliotek Sfery

Co się dzieje. Biblioteki Sfery są powiązane z wersją programu. Księgowa klika „aktualizuj” w piątek po południu, Subiekt wstaje w nowej wersji, a usługa integracji przestaje się łączyć, bo została zbudowana pod poprzednią. Zamówienia z weekendu czekają w kolejce, a w poniedziałek nikt nie wie dlaczego.

Jak to rozwiązujemy. Aktualizacja Subiekta jest w kalendarzu, nie w przypadku. Sprawdzamy zgodność bibliotek na kopii bazy, przebudowujemy usługę i dopiero wtedy aktualizujemy produkcję. W umowie wsparcia jest zapisane, kto to robi i w jakim czasie. Bez wsparcia dostajesz instrukcję krok po kroku i repozytorium, z którego Twój informatyk zbuduje nową wersję.

Pułapka 4: paragon czy faktura, ZK czy FS, OSS i waluty

Co się dzieje. „Wrzucić zamówienie do Subiekta” to zdanie, które w umowie nic nie znaczy. Zamówienie od konsumenta na Allegro to inny dokument niż zamówienie od firmy z NIP-em. Jedno kończy się paragonem, drugie fakturą, a czasem fakturą do paragonu. Sprzedaż do konsumenta w innym kraju UE może iść w procedurze OSS ze stawką VAT kraju odbiorcy. Amazon płaci w euro, Subiekt księguje w złotych. Każdy z tych przypadków to osobna ścieżka, a integrator, który ich nie spisał, odkryje je razem z księgową na koniec miesiąca.

Jak to rozwiązujemy. Przed napisaniem linijki kodu spisujemy mapę dokumentów. Które zamówienia trafiają jako ZK i kiedy zamieniają się w FS, kiedy powstaje paragon, jak wygląda faktura do paragonu, z jakiego dnia bierzemy kurs waluty i skąd stawkę VAT dla sprzedaży w UE. Ta mapa jest w dokumencie z audytu i akceptuje ją księgowość, nie my.

Pułapka 5: stany magazynowe, rezerwacje i zapytania w godzinach pracy

Co się dzieje. Sklep pokazuje stan z Subiekta, ale nie uwzględnia rezerwacji z niezrealizowanych ZK, więc sprzedaje towar, który już ktoś kupił. Albo firma ma kilka magazynów, a integracja sumuje wszystkie, w tym ten z reklamacjami. Albo odświeżanie stanów co minutę odpytuje całą bazę i o dziesiątej rano Subiekt zaczyna zwalniać na każdym stanowisku.

Jak to rozwiązujemy. Liczymy stan dostępny, czyli stan magazynowy minus rezerwacje, i ustalamy z klientem, które magazyny liczą się do sprzedaży w danym kanale. Zmiany stanów wysyłamy przyrostowo, tylko dla towarów, które faktycznie się zmieniły, a cięższe operacje planujemy poza godzinami pracy biura. Zanim cokolwiek pójdzie na produkcję, mierzymy obciążenie na kopii bazy.

Pułapka 6: to samo zamówienie dwa razy

Co się dzieje. Marketplace wysyła zdarzenie o nowym zamówieniu, integracja zapisuje ZK, a po chwili to samo zdarzenie przychodzi jeszcze raz. Bo sieć mrugnęła, bo zmienił się status, bo ktoś kliknął „synchronizuj”. Efekt: dwa dokumenty na jedno zamówienie, dwie rezerwacje, dwie faktury i jedna bardzo zła księgowa.

Jak to rozwiązujemy. Każde zdarzenie dostaje klucz idempotencji zbudowany z identyfikatora zamówienia i kanału. Zanim cokolwiek trafi do Sfery, sprawdzamy w dzienniku operacji, czy ten klucz już przeszedł. Zdarzenia stoją w kolejce, więc kiedy Subiekt jest niedostępny, nic nie ginie, tylko czeka. Dziennik jest czytelny dla człowieka, żeby w poniedziałek rano dało się odpowiedzieć na pytanie „co się stało z zamówieniem numer taki i taki”.

Pułapka 7: czyj to kod, gdy skończy się abonament

Co się dzieje. Integracja działa, faktura za abonament przychodzi co miesiąc, wszyscy zadowoleni. Po dwóch latach firma chce zmienić dostawcę albo dopisać jedną regułę i okazuje się, że kod jest na serwerze wykonawcy, konfiguracja w jego panelu, a dokumentacji nie ma. Jedyna droga to pisać od nowa.

Jak to rozwiązujemy. Kod i konfiguracja należą do firmy, która za nie zapłaciła. Repozytorium jest u klienta albo w miejscu, do którego ma pełny dostęp. Dokumentacja opisuje architekturę, mapę dokumentów i procedurę aktualizacji. Wsparcie jest opcją, nie warunkiem działania. Dokładny zakres przeniesienia praw zapisujemy w umowie, tak jak opisujemy to w FAQ.

Dziennik operacji: jak wygląda integracja od środka

Najlepszy test integracji to jej log. Jeśli po nocnym przebiegu potrafisz w minutę powiedzieć, ile zamówień weszło, ile pominięto i dlaczego, system jest pod kontrolą. Tak wygląda przykładowy fragment dziennika z naszej usługi. Liczby są ilustracją, nie statystyką.

[21:04:11] start przebiegu #1842 (allegro:konto-1, allegro:konto-2, woocommerce)
[21:04:12] pobrano 37 zamówień (allegro:konto-2)
[21:04:12] pobrano 12 zamówień (allegro:konto-1)
[21:04:13] pobrano 5 zamówień (woocommerce)
[21:04:13] pominięto 2 duplikaty (idempotency-key)
[21:04:14] sesja Sfery otwarta (nexo PRO, stanowisko: integrator)
[21:04:15] kontrahent K-000731 istnieje, pominięto tworzenie
[21:04:16] ZK/2026/09/0928 utworzone (allegro:konto-2, 4 pozycje, rezerwacja)
[21:04:17] kontrahent utworzony: K-004412 (NIP zweryfikowany)
[21:04:19] FS/2026/09/0412 utworzona (allegro:konto-2, EUR -> PLN, kurs z dnia)
[21:04:20] PA/2026/09/2201 utworzony (woocommerce)
[21:04:26] stany: 118 towarów zmienionych, wysłano do 3 kanałów
[21:04:28] błąd: brak stawki VAT dla kraju odbiorcy
[21:04:28] zamówienie A2-55910 odłożono do kolejki
[21:04:29] sesja Sfery zamknięta
[21:04:29] koniec przebiegu #1842: 52 zamówienia, 2 duplikaty, 1 do wyjaśnienia

Trzy rzeczy do zauważenia. Sesja Sfery żyje kilkanaście sekund, nie całą noc. Duplikaty są policzone, nie zamiecione pod dywan. Zamówienie, którego integracja nie umie zaksięgować, nie znika i nie tworzy błędnego dokumentu, tylko trafia do kolejki z opisem, który zrozumie księgowa.

Sfera nexo, Sfera GT czy integrator abonamentowy

Właściciel pyta zwykle: „a nie prościej wziąć gotowy integrator?”. Czasem tak. Poniżej zestawienie trzech dróg, którymi zamówienia mogą trafiać do Subiekta. Szczegóły licencyjne Sfery, zarówno dla nexo, jak i dla GT, potwierdź w dokumentacji InsERT, bo to ich produkt i ich warunki.

Kiedy gotowy integrator wystarczy

Nie każda firma potrzebuje własnego kodu. Jeśli sprzedajesz na jednym koncie Allegro, wszystkie zamówienia kończą się paragonem albo prostą fakturą, masz jeden magazyn i nie planujesz sprzedaży za granicę, gotowy integrator abonamentowy zrobi robotę. Płacisz co miesiąc, dostawca dba o zgodność z Subiektem, a Ty nie utrzymujesz żadnego serwera.

Dedykowana integracja zaczyna się opłacać, gdy reguły przestają mieścić się w konfiguratorze: kilka kont i marketplace'ów, B2B obok B2C, OSS, kilka magazynów, własna logika cen albo rezerwacji. Wtedy każdy miesiąc w gotowym narzędziu to obejścia, ręczne poprawki i tłumaczenie księgowej, dlaczego dokument wygląda inaczej, niż powinien. Ile takie obejścia kosztują w godzinach, policzyliśmy w osobnym wpisie.

Checklista: 9 pytań do integratora przed podpisaniem umowy

Wyślij to mailem przed spotkaniem. Dobra firma odpowie w kilku zdaniach na każde pytanie. Słaba zacznie od „to zależy” i na tym skończy.

1. 01Jaką wersję Subiekta nexo zakładacie w wycenie i czy Sfera jest w niej dostępna? Kto to sprawdził?
2. 02Gdzie fizycznie stanie część integracji rozmawiająca ze Sferą i kto utrzymuje tę maszynę?
3. 03Ile stanowisk albo sesji zajmuje integracja i czy uwzględniliście to w liczbie licencji?
4. 04Co się dzieje po aktualizacji Subiekta: kto sprawdza zgodność bibliotek, w jakim czasie i za ile?
5. 05Jak wygląda mapa dokumentów: które zamówienia idą jako ZK, które jako FS, kiedy paragon, kiedy faktura do paragonu, jak liczycie OSS i waluty?
6. 06Jak liczycie stan dostępny: czy odejmujecie rezerwacje i które magazyny wchodzą do sprzedaży w danym kanale?
7. 07Co się stanie, gdy to samo zamówienie przyjdzie dwa razy? Pokażcie dziennik operacji z testów.
8. 08Gdzie jest repozytorium kodu i konfiguracja, kto ma do nich dostęp i co dostaję, jeśli zakończymy współpracę?
9. 09Czy przed produkcją uruchamiacie integrację na kopii mojej bazy i kto ogląda wynik razem z księgową?

Co zrobiliśmy z tą wiedzą

Większość z tych pułapek znamy z własnych wdrożeń, nie z teorii. Dla sprzedawcy na pięciu rynkach Amazon EU zbudowaliśmy aplikację desktopową w C# .NET, która przez Amazon SP-API i Sferę tworzy w Subiekcie nexo PRO fakturę dla każdego zamówienia, z podziałem per kraj i klasyfikacją transakcji. Aplikacja działa na tej samej maszynie co Subiekt, zapamiętuje identyfikator każdego zamówienia z Amazona, więc drugi raz nie założy dokumentu, i przeszła Amazon security review. Od startu do produkcji minęły 3 tygodnie. Dla hurtowni AGD z czterema cennikami i 1293 produktami połączyliśmy aplikację na tablet, portal B2B i Subiekt nexo w jeden obieg danych, etapami po 2-3 tygodnie. Hub integracji w .NET 8 stoi obok Subiekta i rozmawia z nim przez Sferę, a zamówienie wysłane drugi raz po utracie zasięgu rozpoznaje jako duplikat, więc w Subiekcie zostaje jeden dokument.

rynków Amazon EU w jednym Subiekcie nexo PRO

5

faktur VAT bez ręcznej pracy

100%

miesięcznie oddane hurtowni B2B

180h

W obu przypadkach kod jest własnością klienta i nie ma abonamentu za pośrednika. Aktualizacje Subiekta są zaplanowane, nie przypadkowe.