Integracja sklepu z Subiekt Nexo PRO - REST API i Sfera

Subiekt Nexo PRO vs GT

GT i Nexo to z punktu widzenia integracji dwa różne światy. GT integrowało się przez Sferę COM - co praktycznie znaczyło hosting integracji na Windowsie, dziwne błędy DCOM w nocy i całkowicie odrębny zestaw umiejętności, których senior PHP-owiec uczył się od zera. Nexo dostało REST API z OAuth-em, w czym każdy backend developer się znajdzie po trzech godzinach z dokumentacją.

Konkretne różnice, które mają znaczenie przy projektowaniu integracji:

Aspekt	Subiekt GT	Subiekt Nexo PRO
API	Sfera COM (tylko Windows)	REST API + Sfera dla Nexo
Baza	SQL Server Express, limit 10 GB	SQL Server Standard
Wielodostęp	Ograniczony, blokady transakcyjne	Pełny, transakcyjny
Multi-magazyn	Słaby, wymaga obejść	Natywny
Cenniki indywidualne	Możliwe, ale ciężko utrzymać	Wbudowany mechanizm
Webhooks	Brak	Plan zdarzeń (zapowiadane)
Hosting	Tylko on-premise	On-premise lub chmura InsERT

Praktyczna konsekwencja jest taka, że REST API Nexo jest dużo czystsze do integrowania, ale wymaga ogarnięcia rzeczy, które w Sferze COM były ukryte: OAuth z odświeżaniem tokenu, paginacja po stronie klienta, idempotencja zapisów (bo retry po timeoucie HTTP to standard). Programista, który pisał integracje pod GT, w pierwszym tygodniu z Nexo będzie szukał tego, co "dawało się załatwić jednym Sfera.Wykonaj()". Drugiego tygodnia podziękuje za zmianę.

Integracja sklepu z Subiekt GT - dla porównania starszego stacku.

REST API Nexo

Autoryzacja idzie przez OAuth 2.0 z grant_type client_credentials. Token jest ważny 24 godziny, odświeżasz go po prostu ponownym wywołaniem tego samego endpointu:

POST /api/oauth2/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=X&client_secret=Y&scope=api

Endpointy, których realnie używasz w integracji sklepowej, mieszczą się w sześciu kategoriach. GET /api/towary to katalog produktów z cenami katalogowymi - pierwszy import sklepu i podstawa do PIM-a. GET /api/cenniki/{id}/pozycje zwraca cennik indywidualny przypięty do kontrahenta - to serce integracji B2B, bez tego nie ma cen kontraktowych. GET /api/stany-magazynowe daje stany per magazyn, z filtrem modifiedAfter do różnicowej synchronizacji. GET /api/kontrahenci ciągnie karty kontrahentów wraz z polami własnymi. POST /api/zamowienia zakłada zamówienie ze sklepu w Nexo. GET /api/faktury pobiera wystawione faktury z PDF-ami.

Limity, o których warto pamiętać. Domyślnie 60 requestów na minutę per client_id - dla pełnej synchronizacji 50 tys. SKU to oznacza okno kilkudziesięciu minut, jeśli ciągniesz seryjnie. Paginacja maksymalnie 100 rekordów na stronę. Filtry idą przez OData ($filter, $top, $skip, $orderby) - to mocna strona Nexo, mniej trzeba ciągnąć "na ślepo" całych zbiorów. InsERT udostępnia sandbox Nexo PRO na 90 dni dla developerów - wystarczy do napisania i przetestowania pełnej integracji bez kupowania licencji produkcyjnej.

Mapowanie produktów, cenników, kontrahentów

Mapowanie produktów wygląda trywialnie na papierze - SKU sklepu na Symbol w Nexo, EAN na KodKreskowy, kategoria sklepowa na Grupa plus Podgrupa. Diabeł siedzi w polach własnych. Nexo daje maksymalnie 20 pól tekstowych i 10 liczbowych na kartotece towaru. Sklep z bogatym PIM-em (Akeneo z 80 atrybutami per produkt) tego nie zmieści. Robię to tak: w Nexo zostaje handlowe minimum - cena, jednostka, VAT, jeden albo dwa atrybuty potrzebne fakturze - a pełen zbiór trzyma PIM, który zasila katalog sklepu osobno.

Druga pułapka: Nexo ma płaską strukturę kategorii (Grupa + Podgrupa, dwa poziomy). Sklep często ma drzewo trzech-czterech poziomów. Nie próbuj mapować 1:1. W Nexo zostaje płaska klasyfikacja księgowa, w sklepie i PIM-ie żyje rozbudowana taksonomia.

Cenniki to drugi obszar, w którym łatwo wpaść w błąd. Nexo obsługuje cennik katalogowy ("Detaliczny" jako wspólny) plus cenniki indywidualne przypinane do kontrahentów. Rabaty ilościowe robisz progowo w pozycji cennika, rabaty procentowe globalne - polem "Rabat" na karcie kontrahenta. To, czego Nexo nie umie, to dynamiczne formuły cenowe - typu "cena = koszt × 1.18 + opłata środowiskowa zależna od kategorii". Jeśli twój sklep liczy ceny formułami, zostaw tę logikę w sklepie, a do Nexo wysyłaj gotowe wartości. Próba wepchnięcia formuł w Nexo kończy się generowaniem setek pozycji cennika i rozsypaniem księgowości.

Cenniki kontraktowe per kontrahent - jak zaprojektować cenniki, żeby się skalowały.

Kontrahentów identyfikuję po NIP-ie, gdy tylko to możliwe - jest unikalny i odporny na zmianę nazwy firmy. Symbol używam dopiero, gdy NIP nie istnieje (klient zagraniczny, klient detaliczny w trybie B2B). Pola własne kontrahenta wykorzystuję do mapowania na segmenty klienta w sklepie - klasa A/B/C, kanał sprzedażowy, opiekun handlowy. Limit kredytowy trzymam jako pole na karcie i czytam przy każdym zakładaniu zamówienia - jeśli klient przekroczył, zamówienie wisi w statusie "do akceptacji handlowca".

Synchronizacja stanów

Stany w Nexo zmieniają się szybciej, niż możesz je polować webhookiem (zwłaszcza że Nexo webhooków jeszcze nie ma, a "plan zdarzeń" jest w mapie drogowej już drugi rok). Aktywny magazyn potrafi mieć kilkanaście tysięcy ruchów dziennie, jeśli dział handlowy fakturuje za stanowiska kasowe. Z trzech strategii, które sprawdzałem, dwie są realne, a jedna na razie wirtualna.

Najprostsza to pull co X minut. Co pięć minut leci GET /api/stany-magazynowe?modifiedAfter=znacznik_ostatniego_pulla, sklep aktualizuje swój widok. Plusem jest prostota i odporność - jeśli sklep padł na godzinę, po wstaniu jednym requestem nadrobi. Minusem okno opóźnienia: między pullem a sprzedażą realną w Nexo masz potencjalnie 5 minut, w których sklep pokazuje stan stary. Dla B2B z towarem masowym to akceptowalne. Dla unikatów (jedna sztuka na magazynie) - nie.

Druga strategia, której używam najczęściej, to pull różnicowy plus własny cache stanów rezerwowych. Sklep trzyma swój licznik = (stan z Nexo) - (rezerwacje aktywne w sklepie). Każde nowe zamówienie w sklepie zabiera ze stanu lokalnego natychmiast, nie czekając na propagację do Nexo. Wymaga to dodatkowej tabeli rezerwacji i procesu zwolnienia rezerwacji po anulowaniu zamówienia, ale eliminuje sprzedaż "ostatniej sztuki dwóm klientom". Stany rezerwowe trzymam w Redisie, pull z Nexo co 3-5 minut, alert gdy desynchronizacja przekroczy 1% pozycji - to typowy znak, że ktoś robi ruchy magazynowe poza ścieżką sklepową.

Trzecia to webhook plus pull jako safety net, ale to scenariusz na "kiedy InsERT dopuści webhooki produkcyjnie". Na dziś nie jest dostępna. Jak będzie - architektura: push na zdarzenie magazynowe, plus pełne porównanie różnicowe co godzinę na wypadek zgubionego eventu.

Zamówienia, faktury, korekty

Przepływ idzie tak, że zamówienie startuje w sklepie ze statusem "złożone", trafia do Nexo POST-em, a stamtąd wracają zmiany statusu (potwierdzone, w realizacji, wysłane), numer faktury z PDF-em i ewentualne korekty (zwrot, reklamacja). Sklep nie wystawia faktur - to robi Nexo - sklep tylko pokazuje klientowi historię i serwuje PDF z własnego storage'u, żeby nie ciągnąć przy każdym wejściu.

POST na /api/zamowienia wygląda przewidywalnie:

{
  "kontrahent": "NIP:1234567890",
  "magazyn": "GLOWNY",
  "pozycje": [
    {
      "towar": "ART-001",
      "ilosc": 10,
      "cena": 145.50,
      "rabat": 0
    }
  ],
  "uwagi": "Numer zamówienia w sklepie: ZA-2026-12345",
  "metoda_dostawy": "kurier",
  "metoda_platnosci": "przelew_termin_14"
}

Jest jedna rzecz, której nigdy nie pomijam: idempotencja. Sklep robi POST, Nexo nie odpowiada w ciągu 30 sekund (timeout HTTP), sklep retryuje - i nagle masz dwa zamówienia w ERP. Dodaję external_id z numerem zamówienia ze sklepu i sprawdzam po stronie sklepu, czy zamówienie o tym numerze już istnieje w Nexo, zanim odpalę POST drugi raz. Bez tego co kilka tygodni telefon z księgowości: "klient mówi, że zamówił raz, a faktury są dwie".

Faktury idą drugim kanałem. Po wystawieniu w Nexo cron sklepu (lub w przyszłości webhook) wyciąga listę nowych dokumentów od ostatniego pobrania, ściąga PDF-y, zapisuje w storage sklepu i powiadamia klienta. PDF cache'owany lokalnie ratuje sklep, gdy Nexo na chwilę nie odpowiada - klient i tak zobaczy fakturę w historii.

Korekty są analogiczne, ale wymagają obsługi po stronie sklepu - po stworzeniu korekty w Nexo trzeba zaktualizować widok historii zamówień, podpiąć dokument korekty i wysłać klientowi powiadomienie. To często pomijane na pierwszym wdrożeniu i wraca jako reklamacja "gdzie moja korekta?".

Migracja istniejącej integracji GT na Nexo

Sklep działający dziś na Subiekt GT przez Sferę COM ma do przerobienia 3-4 tygodnie pracy seniora, jeśli warstwa integracji jest rozsądnie rozdzielona. Jeśli integracja jest sklejona z logiką biznesową - czyli kod w sklepie wprost wywołuje obiekty Sfery zamiast korzystać z abstrakcji - to może być 6-8 tygodni i okazja do generalnego sprzątania.

Plan, który wykonuję najczęściej. W pierwszym tygodniu sandbox Nexo plus mapowanie schematów - co się różni w polach kartoteki, jak przemapować pola własne z GT (gdzie często były luźno nazwane) do Nexo. To zwykle wciąga handlowca, bo trzeba zdecydować, które pola własne kontrahenta jeszcze nam potrzebne, a które były zaśmieceniem z 2014 roku.

W drugim tygodniu rewrite warstwy adaptera. Sfera COM idzie do kosza, w jej miejsce wjeżdża klient REST plus obsługa OAuth. Tu się okazuje, czy adapter był adapterem, czy stertą wywołań. Jeśli adapterem - logika biznesowa zostaje, adapter się podmienia, idziemy dalej. Jeśli nie - przepisujemy obie warstwy i deklarujemy 6 tygodni zamiast 3.

W trzecim tygodniu testy regresyjne. Przejdź pełen cykl zamówienia - od dodania do koszyka, przez POST do Nexo, zmianę statusu, wystawienie faktury, ewentualną korektę po zwrocie. Sprawdź cenniki indywidualne dla 10-20 kluczowych klientów. Sprawdź wieloproduktowe zamówienia (sklepy padają najczęściej na pozycji 87 z 200).

W czwartym tygodniu cutover. InsERT ma narzędzie migracji danych z GT do Nexo, ale to nie jest "kliknij i gotowe" - wymaga przygotowania mapowań i okna technicznego, w którym sklep przechodzi na maintenance. Po przełączeniu zostaje hypercare dwa tygodnie - codzienny przegląd logów, codzienne sprawdzenie liczby zamówień przesłanych do Nexo vs wystawionych w sklepie.

Trzy problemy, które wracają u prawie każdego: pola własne kontrahenta z GT, które nie mapują się typem do Nexo (data w GT była stringiem, w Nexo jest typowaną kolumną), cenniki GT tworzone dawno temu procedurami SQL bezpośrednio na bazie - w Nexo nie ma do nich dostępu, trzeba odbudować z API, oraz historyczne zamówienia z GT, które zostają w archiwum tylko do odczytu, bo nie ma sensu ich migrować na Nexo.

Plan cutover migracji - to samo podejście dla migracji platformy sklepu.

FAQ

Czy Sfera w Nexo działa tak samo jak w GT? To jest inna Sfera. Nexo ma własną - "Sfera dla Nexo" - i to wciąż API w technologii Microsoftu, ale architektura siedzi już na .NET, nie na COM. Do integracji ze sklepem internetowym i tak rekomenduję REST API, a Sferę dla Nexo zostawiam na operacje księgowe i raporty, które przez REST byłyby nieefektywne.

Ile czasu zajmuje wdrożenie integracji Nexo z Magento? Dla sklepu z 30 tys. SKU i cennikami indywidualnymi: 6-8 tygodni od kick-offa do produkcji, z czego dwa tygodnie to hypercare po wdrożeniu. Mniejszy sklep B2C bez cenników kontraktowych - 3-4 tygodnie. Większy sklep z multi-magazynem i logiką partii towaru - 10-12 tygodni.

Czy Nexo radzi sobie z katalogiem 50k SKU? Tak, ale wymaga SQL Servera w wersji Standard (nie Express), dedykowanego serwera z 16 GB RAM i SSD-kami. Express ma limit 10 GB bazy i zacznie odmawiać współpracy przy 40 tys. SKU z pełną historią transakcji. InsERT rekomenduje rozdzielenie serwera aplikacji od serwera bazy powyżej 30 tys. SKU - słuchałbym.

Czy migracja z GT na Nexo zachowa numerację dokumentów? Możesz albo zachować numerację, albo zacząć od nowa - decyzja księgowości, nie integracji. InsERT podczas migracji pozwala zdefiniować pierwsze numery dokumentów w Nexo. Po stronie sklepu obsłuż obie numeracje w historii zamówień, żeby klient szukający faktury z 2023 roku wciąż ją znalazł pod starym numerem.

Czy Nexo w chmurze InsERT obsłuży moją integrację? Tak, ale licz się z opóźnieniami sieciowymi. Każdy request ze sklepu leci do data center InsERT-u i wraca - typowo 100-200 ms dodatkowego latency. Dla integracji bazującej na pollingu to nieistotne. Dla sprawdzenia stanu w trakcie kliknięcia "dodaj do koszyka" - on-premise daje pewniejszy SLA, bo masz pełną kontrolę nad siecią.

Co dalej

• Integracje e-commerce B2B: Integracje e-commerce B2B
• Subiekt GT - dla porównania: Integracja sklepu z Subiekt GT
• Middleware vs bezpośrednio: Middleware vs integracje bezpośrednie