Integracja sklepu z Comarch ERP XL i Optima - praktyczny przewodnik

W skrócie

• 1. API: dla XL ≥ 2020 - REST przez Comarch Web Service Manager. Dla starszych - klasyczny SOAP/XL API. REST jest pożądany, ale w polskiej rzeczywistości większość instalacji wciąż siedzi na SOAP-ie.
• 2. Cenniki kontraktowe to obszar gdzie XL wygrywa - ma rozbudowane definicje rabatów, progów, promocji. Trzeba jednak wiedzieć którego API używać do ich pobierania (PriceCalculation vs. PriceList).
• 3. Stany magazynowe w realtime - zapomnij. SOAP-owe XL przy synchronizacji 50k indeksów potrafi mieć timeout 4 minut. Pull on-demand dla konkretnego SKU + pełna synchronizacja batch co 15 min - to działa.
• 4. Idempotencja zamówień jest twoim obowiązkiem, nie XL-a. Zamówienie wysłane drugi raz wejdzie drugi raz.
• 5. Najczęstsze problemy: timeout na większych zapytaniach, brak limitu sesji w XL (sklep wisi na czekającej sesji), zmiana schematów po aktualizacji XL (XL 2022 → 2023 zmienia kilka pól bez ostrzeżenia).

Wersje XL i co z czego korzystać

Comarch ERP XL nie jest jednym produktem. W polu zobaczysz:

• XL 2018-2020. Aktywny u połowy klientów. Tylko SOAP/COM API. Niestabilny przy dużych wolumenach. Aktualizacja do nowszej wersji to projekt na 3-6 miesięcy po stronie klienta - sklep nie kontroluje terminu.
• XL 2021-2023. REST w fazie wprowadzania, równolegle SOAP. REST nie pokrywa wszystkich obszarów (cenniki tak, niektóre raporty nie).
• XL 2024-2025. REST dojrzały, większość operacji dostępna. Wciąż SOAP do legacy.

Wniosek praktyczny: zanim wycenisz integrację - sprawdź wersję XL u klienta, sprawdź czy ma aktualne licencje (Comarch sprzedaje "moduły API" osobno!), sprawdź czy mają instalację WebService Manager (osobna aplikacja).

Comarch ERP Optima to inna platforma niż XL - mniejsza, dla MŚP. Ma własne API (web service + Comarch Cloud). Tutaj skupiam się na XL.

Architektura wdrożenia - wzorzec, który działa

Z pięciu wdrożeń, ten wzorzec sprawdza się powtarzalnie:

[Sklep Magento/Shopware]
        |
        | REST (sklep wystawia API)
        v
[Middleware - Symfony lub Node.js]
        |
        +--- SOAP/REST do XL (przez WebService Manager)
        +--- baza Redis (kolejki, cache, locki)
        +--- baza MySQL/PostgreSQL (mapowania, logi)

Dlaczego middleware:

1. XL bywa offline na 2-4 godziny w nocy (backup, reindeks). Middleware kolejkuje, sklep dalej działa.
2. Transformacje danych (XL ma swoje słowniki, sklep - swoje) idą w middleware, nie zaśmiecają sklepu.
3. Logi i metryki integracji w jednym miejscu.
4. Drugi sklep (np. wersja DACH na innej platformie) podpinasz pod tę samą warstwę.

Bezpośrednie połączenie sklep ↔ XL (bez middleware) widziałem w 2 projektach. Oba - z bólem, ale działały do około 8k SKU. Powyżej - ten model się sypie.

Pełna analiza: Middleware vs. integracje bezpośrednie.

Synchronizacja produktów i atrybutów

XL trzyma produkt w tabeli CDN.TwrKarty plus ~12 powiązanych tabel (cechy, partie, kompletacje, jednostki, kody EAN). Sklep potrzebuje wyciągu z tego: nazwa, opis, podstawowe atrybuty filtrowalne, EAN, jednostka.

Wzorzec sprawdzony:

• Pierwsza synchronizacja (initial sync): batch, w nocy, przez Towar/Lista w paczkach po 500. Pełna synchronizacja 50k SKU zajmuje ~3 godziny. Robisz to raz.
• Synchronizacja inkrementalna: XL ma znacznik DataMod (data modyfikacji). Sklep pyta o produkty zmienione od last_sync. Co 30 minut, paczki po 100.
• Pełna re-synchronizacja: raz na 7 dni, w nocy, jako bezpiecznik (zdarzają się sytuacje gdzie DataMod nie zostanie zaktualizowana).

Antywzorzec, który widziałem: pełna synchronizacja co godzinę. Skutek: XL przeciążony, ERP-owcy w klientówce mają lagi, klient po dwóch tygodniach każe nas wyrzucić.

Atrybuty filtrowalne to oddzielny problem. XL ma „cechy", ale rzadko są one wystarczające do filtrowania w sklepie. Praktyka: 60% atrybutów z XL, 40% z PIM-u (Akeneo) lub ręcznie w sklepie. PIM Akeneo w sklepie B2B.

Cenniki kontraktowe - gdzie XL wygrywa

XL ma jeden z lepszych modeli cenowych na rynku polskim. Definiuje:

• Cennik bazowy (per produkt, per waluta)
• Cenniki indywidualne (per kontrahent)
• Cenniki grupowe (per grupa kontrahentów)
• Promocje (czasowe, ilościowe, na grupę produktów)
• Progi ilościowe (od 100 szt. cena X, od 500 cena Y)

Wszystko to oblicza się w jednym wywołaniu - PriceCalculation w API. Sklep nie musi powielać tej logiki - wystarczy zapytać XL "ile zapłaci klient X za produkt Y w ilości Z" i zacache'ować odpowiedź.

Cache cen kontraktowych:

• TTL 5-15 minut
• Klucz cache'a: (kontrahent_id, sku, ilosc)
• Invalidacja: webhook z XL przy zmianie cennika (jeśli XL go ma) lub cron co 15 min

Bez cache'a - XL umrze w godzinie szczytu. Sklep B2B w peak'u (pn-wt rano) potrafi puszczać 20 req/s tylko na zapytania o ceny. XL przyjmie 5-10.

Stany magazynowe

Trzy strategie, w kolejności od najgorszej do najlepszej:

Strategia A - pełna synchronizacja batch. XL wysyła do sklepu listę: [SKU, stan, magazyn]. Co 15 minut, dla wszystkich SKU. Działa do ~10k indeksów. Powyżej - timeout.

Strategia B - delta + pull on-demand. XL wysyła delty co 5 minut (zmienione stany od ostatniego pinga). Sklep dodatkowo robi pull on-demand dla konkretnego SKU, gdy klient go ogląda. Cache 30 sekund. Działa do ~80k SKU.

Strategia C - webhook + pull on-demand. XL puszcza webhook do middleware przy zmianie stanu konkretnego towaru. Middleware aktualizuje cache. Klient widzi stan świeży w ~5 sekundach. To wymaga XL z modułem zdarzeniowym - nie wszystkie wersje to mają.

W realnych wdrożeniach najczęściej B + element C dla top-100 sprzedawanych produktów (te najczęściej pytane idą webhookiem).

Zamówienia - sklep → XL

Tu się najczęściej psuje. Wzorzec:

1. Klient składa zamówienie w sklepie.
2. Sklep zapisuje zamówienie u siebie z external_id = null i status = pending_sync.
3. Sklep publikuje zdarzenie OrderCreated do kolejki.
4. Middleware odbiera, transformuje, wysyła do XL (Dokument/Zapisz lub odpowiednik REST).
5. XL zwraca numer dokumentu. Middleware zapisuje go w sklepie jako external_id.
6. Status zamówienia zmienia się na synced.

Idempotencja: sklep generuje unikalny external_reference (np. WEB-2026-000123). Przy retry middleware sprawdza, czy XL już ma dokument o tym referencjce. Jeśli tak - nie tworzy duplikatu. To wymaga, żeby XL miał indeks na polu referencyjnym (trzeba go założyć przy wdrożeniu).

Co XL waliduje przy zamówieniu i co może odpalić:

• Limit kredytowy kontrahenta przekroczony - błąd, zamówienie nie wchodzi
• Stan magazynowy zmienił się między koszykiem a zatwierdzeniem - częściowa realizacja lub błąd (zależnie od polityki)
• Cennik wygasł między koszykiem a zatwierdzeniem - błąd
• Kontrahent nie ma uprawnień do konkretnego towaru - błąd

Każdy z tych błędów musi być w przemyślany sposób przekazany do sklepu, klient musi dostać sensowny komunikat.

Statusy zamówień i faktury

Sync zwrotny XL → sklep. Etapy:

• Zatwierdzony w XL → sklep pokazuje "W realizacji"
• WZ wystawiona → sklep pokazuje "Spakowane, czeka na kuriera"
• Faktura wystawiona → sklep pokazuje "Wysłane", podpina PDF faktury
• Anulowane / korekta → osobne procesy

Pull co 5-10 minut po stronie middleware, sprawdzanie listy zamówień z status changed since last_check.

PDF faktury z XL: pobieranie przez API (jeśli wersja na to pozwala) lub generowanie samodzielnie z danych XL (jeśli nie). W obu przypadkach - trzymanie w S3-compatible storage, nie w bazie sklepu.

Najczęstsze problemy z mojej praktyki

Problem 1: Limit sesji w XL. XL ma limit jednoczesnych sesji API (zazwyczaj 10-20, zależnie od licencji). Middleware musi tym zarządzać - pula połączeń, semafor. Bez tego po godzinie pikowej sklep zaczyna dostawać "no available session".

Problem 2: Timeout przy dużych odpowiedziach. Pobranie 5000 produktów jednym zapytaniem? XL zwróci 504 po 4 minutach. Paginacja po 200-500.

Problem 3: Aktualizacja XL psuje integrację. Klient aktualizuje XL z 2022 na 2024 (Comarch wymusza aktualizacje). Pojedyncze pola w response zmieniły nazwy. Twoja integracja przestaje czytać cenakontrahenta bo teraz to cenaKontrahenta. Testy integracyjne przy każdej aktualizacji są must-have.

Problem 4: Czas restartu XL = downtime sklepu. XL restartuje się w nocy 2-4 razy w tygodniu (na większych instalacjach). Bez kolejek w middleware - w tym czasie sklep wywala 500 na każde zamówienie.

Problem 5: Encoding. XL trzyma stringi w Windows-1250. API zwraca to różnie zależnie od wersji. „Łódź" potrafi pojawić się w sklepie jako „Ł?d?" jeśli nie ustawisz encoding wszędzie po drodze.

Czas wdrożenia i koszt

Czas:

• Audyt + projekt: 2-3 tygodnie
• MVP (produkty + ceny + stany, jedna strona): 6-8 tygodni
• Pełne MVP (z zamówieniami w obie strony, statusy, faktury): 12-16 tygodni
• Stabilizacja i go-live: dodatkowe 4-8 tygodni

Łącznie 5-8 miesięcy do pełnej produkcji dla średniego sklepu.

Koszt (orientacyjnie, dla scope „pełna integracja sklep ↔ XL"):

• 80-180 tys. zł wdrożenie
• 15-30 tys. zł rocznie utrzymanie (poprawki przy aktualizacjach XL, monitoring, drobne zmiany)

Dodatkowo:

• Licencja modułu API XL po stronie Comarcha - kilka-kilkanaście tys. zł rocznie
• Konsultacje XL-owe (od strony ERP klienta) - zazwyczaj na koszt klienta, 5-15 tys. zł

FAQ

Czy mogę zintegrować Magento z Comarch XL bez konektora gotowego? Tak. Większość konektorów na rynku to i tak custom dla konkretnego klienta. Gotowy konektor (np. od Comarcha lub partnerów) pokrywa 60-70% przypadku, resztę dorabiasz.

Comarch XL ma własny moduł e-commerce - co z nim? Comarch e-Sklep / Comarch B2B. Działa dla bardzo prostych przypadków, w skali 1-5k SKU bez ambicji. Powyżej tej skali większość firm migruje na Magento/Shopware ze względu na elastyczność i wydajność.

Czy mogę skorzystać z BaseLinkera jako warstwy między sklepem a XL? Tak, dla niektórych przypadków. BaseLinker łapie zamówienia i synchronizuje stany dla mniejszych integracji. Dla pełnego B2B (cenniki kontraktowe, limity kredytowe) - nie wystarczy. BaseLinker w sklepie B2B.

Co z integracją XL ↔ Shopware? Działa analogicznie do Magento. Mniej gotowych konektorów na rynku - większość projektów to custom przez middleware. Czas wdrożenia +10-20% wzgl. Magento.

Czy potrzebuję dewelopera Comarcha do projektu? Tak. Po stronie XL ktoś musi wystawić użytkownika API, ustawić uprawnienia, czasem zmienić konfigurację cennikową. Wewnętrzny administrator ERP + ewentualnie godziny konsultacji od partnera Comarcha.

Co dalej

• Inny ERP: SAP S/4HANA, Subiekt GT, enova365
• Architektura integracji: Middleware vs. bezpośrednio, Kolejki RabbitMQ i Redis
• Platforma: Magento dla B2B
• Pełny przegląd integracji: pillar /integracje