Integracja ERP i PIM z Magento 2 – SAP, Comarch, Akeneo

Integracja systemowa to nie jednorazowy projekt – to ciągły przepływ danych między Magento a ERP (stany magazynowe, zamówienia, faktury), PIM (opisy, zdjęcia, atrybuty) i CRM (historia klienta, segmentacja). Każdy błąd synchronizacji to realny koszt: złe stany = nieaktualne produkty = utracone sprzedaże lub paczki, których nie można wyekspediować.

Architektura integracji: REST, GraphQL, Bulk API i Webhooki

Magento 2 oferuje kilka mechanizmów wymiany danych z systemami zewnętrznymi. Wybór właściwego zależy od kierunku przepływu danych (do Magento czy z Magento), wolumenu rekordów i tolerancji na opóźnienie synchronizacji.

Mechanizm	Kierunek	Wolumen	Tryb	Zastosowanie
REST API	ERP → Magento	do ~1 000/req	Synchroniczny	Ceny, pojedyncze zamówienia
Bulk API	ERP → Magento	10 000+/req	Asynchroniczny	Masowy import produktów, stanów
GraphQL	Magento → Frontend	odczyt	Synchroniczny	Headless/PWA, katalog produktów
Webhooki (M2.4.7+)	Magento → ERP	zdarzenia	Push (real-time)	Nowe zamówienia, zmiany statusów

Middleware – dlaczego nie łączą bezpośrednio ERP z Magento

Bezpośrednia integracja ERP↔Magento przez API to pułapka. Systemy ERP często eksportują dane w formatach (XML, CSV, SOAP), które wymagają transformacji zanim trafią do REST API Magento. Co ważniejsze – ERP może wysłać produkt z brakującym sku lub złą jednostką ceny, co bez walidacji zapiśe się bezpośrednio w bazie sklepu.

Warstwa middleware (dedykowana aplikacja, iPaaS jak Boomi/Mule, lub serwis Node.js/PHP) pełni rolę tlumacza i strаżnika jakości: sprawdza kompletność rekordów, mapuje pola (np. ItemCode → sku), buforuje retry po błędach sieciowych i loguje każdą transakcję danych.

Pro Tip: Asynchronous Bulk API

Dla importów powyżej 1 000 rekordów zawsze używaj Bulk API. Magento zwraca natychmiast bulk_uuid, a przetwarzanie odbywa się w tle przez RabbitMQ – bez blokowania serwera WWW i bez timeoutów.

# Przykład: masowy import cen przez Bulk API (curl):

curl -X POST "https://sklep.pl/async/bulk/V1/products/byCriteria" \

-H "Authorization: Bearer $TOKEN" \

-H "Content-Type: application/json" \

-d '[{"product":{"sku":"ABC-001","price":99.90}},{"product":{"sku":"ABC-002","price":149.90}}]'

# Odpowiedź: bulk_uuid do śledzenia statusu:

{"bulk_uuid":"550e8400-e29b-41d4-a716-446655440000","request_items":[...],"errors":false}

# Sprawdzenie statusu importu:

curl "https://sklep.pl/rest/V1/bulk/550e8400-.../status" -H "Authorization: Bearer $TOKEN"

Zarządzanie consumerami RabbitMQ przez CLI

Bulk API wymaga działających procesów consumerów. Jeśli nie działają (np. po restarcie serwera), kolejka będzie rość, ale dane nie będą przetwarzane.

# Lista wszystkich dostępnych consumerów:

php bin/magento queue:consumers:list

# Uruchomienie głównego consumera dla operacji zbiorczych:

php bin/magento queue:consumers:start async.operations.all --max-messages=10000 &

# Sprawdzenie statusów operacji zbiorczych (wynik bulk importu):

php bin/magento queue:consumers:start bulk.operation.start &

# Reindeksacja po dużym imporcie produktów:

php bin/magento indexer:reindex catalog_product_price cataloginventory_stock

Synchronizacja stanów MSI – Multi-Source Inventory

Magento 2.3+ wprowadza Multi-Source Inventory (MSI), które zmienia całkowicie model zarządzania stanami. Zamiast jednego globalnego licznika, możesz przypisywać zapasy do konkretnych source’ów (magazynów fizycznych, dropshippingów, salonów). To idealne odwzorowanie logiki większości systemów ERP.

Kluczowa zasada: ERP powinien aktualizować stany na poziomie source (konkretnego magazynu), a nie zagregowanego stock. Magento automatycznie przeliczy dostępność dla każdego kanału sprzedaży na podstawie przypisanych źródeł.

MSI – komendy CLI do zarządzania źródłami

Szybka inspekcja źródeł MSI i aktualizacja stanów przez API – wzorzec stosowany w integracjach z ERP.

# Lista skonfigurowanych źródeł (source) MSI:

php bin/magento inventory:source:list

# REST API: aktualizacja stanu konkretnego źródła (source):

curl -X POST "https://sklep.pl/rest/V1/inventory/source-items" \

-H "Authorization: Bearer $TOKEN" \

-d '{"sourceItems":[{"sku":"ABC-001","source_code":"warehouse_waw","quantity":150,"status":1}]}'

# Reindeksacja MSI po masowym imporcie stanów:

php bin/magento indexer:reindex inventory

# Sprawdzenie źródła przypisanego do produktu:

curl "https://sklep.pl/rest/V1/inventory/source-items?searchCriteria[filterGroups][0][filters][0][field]=sku&searchCriteria[filterGroups][0][filters][0][value]=ABC-001" -H "Authorization: Bearer $TOKEN"

Integracja PIM – Akeneo, Pimcore i własne systemy

System PIM (Product Information Management) to centralne repozytorium treści produktowych: opisy, zdjęcia, atrybuty techniczne, tłumaczenia. Magento pełni rolę kanaułu sprzedaży, który pobiera dane z PIM – nigdy odwrotnie. Dzięki temu ten sam opis produktu może być używany jednocześnie w sklepie www, aplikacji mobilnej i katalogach drukowanych.

Akeneo Community Edition

Open-source, oficjalny konektor dla Magento 2 przez Composer. Idealny dla katalogów 1 000 – 100 000 SKU. Obsługuje warianty i rodziny atrybutów.

Pimcore

Open-source PIM + DAM (Digital Asset Management). Mocna obsługa hierarchii kategorii i zarządzania mediami. Integracja przez REST API lub dedykowany bundle.

ERP jako PIM (Comarch, SAP)

Wiele polskich firmów trzyma dane produktowe w ERP. Wymaga warstwy middleware do transformacji formatów (XML SOAP → JSON REST) i obsługi obrazów.

Własny system (CSV/FTP/SFTP)

Najprostszy model – pliki CSV wystawiane na SFTP, pobierane przez Magento Cron. Skuteczny dla katalogów nie zmieniających się częściej niż co kilka godzin.

Mapowanie atrybutów – transformacja i walidacja danych

Każdy system zewnętrzny używa własnej nomenklatury pól. Proces mapowania (np. ItemCode → sku, GrossPrice → price, StockQty → quantity) musi być dokładnie udokumentowany i testowany przy każdej aktualizacji schematu ERP. Błędy w mapowaniu to najczęstsza przyczyna awarii synchronizacji.

Debugowanie atrybutów i zestawów atrybutów przez CLI

Weryfikacja dostępnych atrybutów i ich kodów jest niezbędna przed napisaniem logiki mapowania w middleware.

# Lista wszystkich atrybutów produktu (kod + typ):

php bin/magento eav:attribute:list --entity-type catalog_product | head -30

# Szczegóły konkretnego atrybutu (np. "color"):

php bin/magento eav:attribute:show color catalog_product

# REST API: pobranie listy zestawów atrybutów (attribute sets):

curl "https://sklep.pl/rest/V1/products/attribute-sets/sets/list?searchCriteria" \

-H "Authorization: Bearer $TOKEN" | python3 -m json.tool | grep '"name"\|"attribute_set_id"'

# Pobranie wszystkich atrybutów danego zestawu (ID=4 = Default):

curl "https://sklep.pl/rest/V1/products/attribute-sets/4/attributes" -H "Authorization: Bearer $TOKEN"

Monitoring synchronizacji i obsługa błędów

Każda integracja powinna mieć wbudowany mechanizm retry z wykładniczym opóźnieniem (exponential backoff) oraz alerting przy przekroczeniu proga błędów. Typowe źródła błędów to: timeout API Magento przy dużych importach, walidacja schema (brak wymaganego pola), duplikaty SKU oraz niedostępność RabbitMQ.

Consumer zatrzymany – kolejka rośnie

Supervisord lub systemd nie zrestartował procesu. Import czeka w RabbitMQ, stany się nie aktualizują. Sprawdź: queue:consumers:list.

Błąd 400: "sku is required"

ERP wysłał rekord bez pola SKU lub z pustym SKU. Walidacja w middleware powinna odrzucać takie rekordy przed wysłaniem do Magento API.

Zduplikowane produkty po imporcie

Import tworzy nowe produkty zamiast aktualizować istniejące. Przyczyna: brak identycznego SKU lub różna wielkość liter (case sensitivity).

Stary stan widoczny po imporcie

Import powiodł się, ale indeks nie został przeliczony. Uruchom indexer:reindex inventory lub włącz tryb "Update on Schedule".

Pro Tip: Monitoring stanu kolejek i błędów synchronizacji (SQL)

Szybki wgląd w stan operacji zbiorczych bezpośrednio z bazy danych – do ustawiania alertów w systemach monitoringu.

-- Operacje zbiorcze z błędami (ostatnie 24h):

SELECT uuid, status, result_serialized, started_at, user_type

FROM magento_bulk JOIN magento_operation ON magento_bulk.uuid = magento_operation.bulk_uuid

WHERE magento_operation.status IN (2, 4) -- 2=error, 4=skipped

AND magento_bulk.started_at >= NOW() - INTERVAL 24 HOUR

ORDER BY magento_bulk.started_at DESC LIMIT 20;

-- Produkty bez przypisanego źródła MSI (potencjalnie niewidoczne w sklepie):

SELECT cpe.sku, cpe.entity_id

FROM catalog_product_entity cpe

LEFT JOIN inventory_source_item isi ON cpe.sku = isi.sku

WHERE isi.sku IS NULL

LIMIT 50;

Integracja ERP/PIM z Magento to projekt architektoniczny, nie tylko techniczny. W Mage24.pl projektujemy i wdrażamy kompletne ekosystemy integracyjne – od analizy przepływu danych, przez budowę middleware, aż po monitoring produkcyjny z alertingiem.

Integracja ERP i PIM: Magento w Sercu Organizacji