Magento a Comarch Optima: co i jak się synchronizuje?

Podział ról: kto jest masterem danych produktowych, a kto transakcyjnych?

W poprawnie zaprojektowanej architekturze Comarch ERP Optima jest jedynym źródłem prawdy (masterem) dla stanów magazynowych, bazowych cenników, stawek VAT oraz kartotek kontrahentów, natomiast Magento 2.4.7 zarządza warstwą prezentacyjną, marketingiem i koszykiem zakupowym. Dwukierunkowo wymieniane są wyłącznie statusy realizacji oraz dane logistyczne. Profesjonalnie wdrożona integracja Magento z Comarch Optima eliminuje ręczną edycję dokumentów handlowych i zamyka obieg transakcji od kliknięcia „Kupuję i płacę” po nadanie paczki i rejestrację w KSeF.

Próby uczynienia z Optimy systemu do zarządzania opisami marketingowymi zazwyczaj kończą się katastrofą. Pole „Nazwa” w Optimie ma ograniczenie do 40 znaków (lub 255 w nowszych polach rozszerzonych), a edytor tekstu w ERP nie nadaje się do formatowania layoutów pod Hyvä Themes czy Page Buildera w Adobe Commerce. Dlatego podział ról musi być bezwzględny:

• Comarch Optima (ERP) → Magento 2: Kod towaru (SKU), kod kreskowy (EAN), waga, podstawowa stawka VAT (23%, 8%, 5%, zw), ceny netto/brutto w PLN i walutach, dostępna ilość fizyczna (zasoby z wybranych magazynów).
• Magento 2 → Comarch Optima (ERP): Nowe zamówienia (RO – Rezerwacja Odbiorcy lub od razu dokumenty rozliczeniowe), dane płatnika i odbiorcy, numer NIP do weryfikacji w GUS i na Białej Liście VAT, metoda płatności, uwagi do zamówienia, paczkomat docelowy.
• Magento 2 (Master autonomiczny): Drzewo kategorii, opisy HTML/CSS, galerie zdjęć, atrybuty filtrów warstwowych (Layered Navigation od Amasty czy Mirasvit), tagi meta title/description i powiązania cross-sell/up-sell.

W którą stronę płyną stany magazynowe i jak pogodzić to z MSI w Magento 2.4.7?

Stany magazynowe wędrują wyłącznie w relacji Optima → Magento. W systemie Comarch punktem wyjścia są zasoby na konkretnych magazynach (np. MAG_GLOWNY, MAG_POZNAN, MAG_ZWROTY). Jeśli w e-commerce sprzedajesz tylko z magazynu centralnego, integracja pobiera parametr Ilość Dostępna (zasoby minus rezerwacje wewnętrzne) z tabeli CDN.TwrZasoby i aktualizuje pole quantity w Magento.

Schody zaczynają się przy architekturze Magento MSI (Multi-Source Inventory). W SISL najczęściej mapujemy poszczególne magazyny z Optimy na konkretne Inventory Sources w Magento 2. Jeśli prowadzisz sprzedaż wielokanałową (np. e-sklep + salon stacjonarny + Allegro przez Baselinker), dane z ERP muszą zasilać odpowiedni Source, a Magento samo przelicza Salable Quantity (ilość handlową).

Zasada twarda: Nigdy nie synchronizuj stanów na podstawie czystego stanu magazynowego z Optimy, ignorując rezerwacje blokujące. Klient, który zapłacił przez BLIK lub Przelewy24, musi natychmiast wywołać rezerwację towaru w ERP, inaczej sprzedasz ten sam produkt dwa razy w trakcie akcji promocyjnej.

Synchronizacja stanów nie może działać w trybie pełnego przeładowania bazy co 10 minut. Przy 40 000 SKU i PHP 8.3 wykonanie pełnego zapytania zarżnie procesor serwera bazodanowego MS SQL lub spowoduje kolejkowanie żądań w API Magento. Prawidłowy integrator odpytuje Optimę wyłącznie o delty – produkty, których znacznik Twr_CzasModyfikacji zmienił się od ostatniego uruchomienia crona (bin/magento cron:run).

Co dokładnie trafia z koszyka Magento do bazy Optimy przy nowym zamówieniu?

Gdy klient finalizuje zamówienie w Magento 2, konektor tworzy w Comarch Optima dokument RO (Rezerwacja Odbiorcy) lub rzadziej bufor PA (Paragon) / FS (Faktura Sprzedaży). Struktura rekordu przesyłanego przez API / WebSerwis obejmuje:

1. Nagłówek dokumentu: Typ dokumentu, seria (np. RO/SKLEP/2025), data wystawienia, forma płatności (zmapowana z metody w Magento, np. P24_BLIK → Przelew P24) oraz termin płatności.
2. Dane kontrahenta: Jeśli zamówienie składa firma, sprawdzany jest numer NIP. Jeśli kontrahent istnieje w bazie Optimy, dokument podpinany jest pod istniejące Knt_KntId. Jeśli nie – tworzona jest nowa kartoteka kontrahenta z adresem bilingowym. Klienci detaliczni trafiają na kontrahenta jednorazowego lub dedykowaną kartotekę zbiorczą (!NIEKRESLONY), aby nie zaśmiecać bazy Optimy setkami tysięcy rekordów B2C.
3. Pozycje zamówienia: Tablica obiektów zawierająca Twr_Kod (SKU), ilość, wynegocjowaną cenę jednostkową z koszyka, stawkę VAT oraz naliczony rabat (np. z modułu reguł koszykowych Mageworx).
4. Pozycja kosztu dostawy: Transport przesyłany jest jako usługa pomocnicza (np. usługa o kodzie KOSZT_WYSYLKI_INPOST) z odpowiednią stawką 23%.
5. Pola atrybutów i opisy: ID paczkomatu InPost (np. KRA01M), numer transakcji z bramki płatności, identyfikator zamówienia w Magento (increment_id) oraz uwagi kupującego.

Jak integracja radzi sobie z fakturami, paragonami i KSeF?

Odpowiedź brzmi krótko: Magento nie wystawia dokumentów księgowych. W polskim porządku prawnym (zwłaszcza w obliczu Krajowego Systemu e-Faktur) próbkowanie generowania faktur w silniku e-commerce to proszenie się o błędy w plikach JPK_V7 i niezgodności numeracji.

Proces księgowy przebiega jednostronnie z Optimy do Magento:

• Magazynier lub automatyczny automat Optimy przekształca dokument RO w FS (Fakturę Sprzedaży) lub WZ (Wydanie Zewnętrzne).
• Optima komunikuje się z bramką KSeF, nadaje e-Fakturze urzędowy numer identyfikacyjny oraz generuje UPO (Urzędowe Poświadczenie Odbioru).
• Integrator wyłapuje zmianę statusu w ERP, pobiera wygenerowany numer faktury (wraz z numerem KSeF) i odsyła go do Magento 2.
• Magento aktualizuje status zamówienia na Complete, wstrzykuje numer faktury do panelu klienta na koncie kupującego i opcjonalnie wysyła e-mail transakcyjny z powiadomieniem.

Jakie są typowe błędy i wąskie gardła w komunikacji API / WebSerwis?

U nas w projektach najwięcej czasu poświęcamy na eliminację trzech klasycznych problemów styku Magento z Optimą:

1. Rozbieżności groszowe w algorytmach zaokrągleń VAT

Magento domyślnie może liczyć podatki metodą Row Total lub Unit Price. Optima liczy VAT od sumy wartości netto pozycji lub od wartości brutto w zależności od konfiguracji serii dokumentu. Jeśli w Magento ustawisz zaokrąglanie od ceny jednostkowej z podatkiem, a Optima przelicza dokument od sumy netto pozycji, przy 15 sztukach towaru o wartości 12,30 PLN brutto powstanie różnica 1 grosza. W efekcie API Optimy odrzuci dokument błędem walidacji sumy: Wartość brutto pozycji nie zgadza się z nagłówkiem dokumentu. Wymaga to precyzyjnego ustawienia reguł podatkowych w Stores > Configuration > Sales > Tax.

2. Blokady transakcyjne i błędy deadlock na bazie MS SQL

Gdy sklep notuje kilkaset zamówień na godzinę, a Optima jednocześnie mieli raporty finansowe, WebSerwis potrafi odpowiedzieć błędem Lock request time out period exceeded. Integrator nie może wtedy porzucać zamówienia. Konieczna jest kolejka asynchroniczna (np. RabbitMQ) w Magento, która ponawia próbę wysyłki dokumentu z mechanizmem wykładniczego opóźnienia (Exponential Backoff).

3. Błędy unikalności adresów e-mail i NIP

W Magento klient może zmienić dane firmy na istniejącym koncie. W Optimie edycja NIP na powiązanym kontrahencie bywa zablokowana, jeśli wiszą na nim zatwierdzone dokumenty historyczne. Integrator musi posiadać logikę sprawdzającą: jeśli NIP uległ zmianie, tworzony jest sub-kontrahent lub odrębna kartoteka z prefiksem, zamiast wywalać krytyczny wyjątek Cannot modify customer tax ID.

Ile kosztuje wdrożenie i utrzymanie takiego połączenia?

Koszty integracji składają się z trzech niezależnych składowych, o których agencje często zapominają wspomnieć na etapie briefu:

Gotowe wtyczki „pudełkowe” za 200 zł miesięcznie sprawdzają się przy prostym WooCommerce z 500 produktami. Przy Magento 2.4.7 na PHP 8.3, z indeksacją OpenSearch 2.x i złożoną logiką rabatową B2B, standardowe konektory SaaS zazwyczaj wymagają głębokich modyfikacji na poziomie endpointów REST API i logiki zdarzeń (events/observers).

Jeśli planujesz połączenie Magento 2 z Optimą lub Twój obecny integrator regularnie gubi zamówienia i rozjeżdża stany magazynowe, napisz do nas – przeanalizujemy logi błędów i wdrożymy architekturę, która działa stabilnie pod każdym obciążeniem.