Laravel API dla e-commerce B2B i PIM – stabilny przepływ danych produktowych

Laravel API między e-commerce B2B, PIM i ERP sprawdza się jako warstwa pośrednia, która przyjmuje dane z każdego systemu w jego formacie, zamienia je na jeden wspólny model produktu, waliduje i dopiero wtedy rozsyła dalej – przez kolejki, z logiem każdej operacji i możliwością ponowienia. Dzięki temu PIM odpowiada za treści, ERP za ceny i stany, sklep za sprzedaż, a żaden z nich nie musi znać wewnętrznej struktury pozostałych. Kiedy dane rozjeżdżają się między kanałami, zwykle przyczyną nie jest brak API, tylko brak takiej warstwy i jasnego podziału odpowiedzialności.

Dlaczego bezpośrednie połączenia przestają wystarczać

Na początku integracja wygląda prosto: sklep co noc pobiera plik z ERP, a opisy ktoś kopiuje z PIM. Potem dochodzi portal dla dealerów, marketplace, feed dla partnera, katalog PDF. Każdy kanał ma własny skrypt, własne mapowania kategorii i własną logikę wariantów. Typowe objawy:

• ten sam produkt ma inne atrybuty w sklepie i w portalu B2B,
• zmiana nazwy pola w PIM psuje eksport, o czym firma dowiaduje się od klienta,
• nikt nie wie, dlaczego część wariantów nie pojawiła się w sklepie,
• ponowny import tworzy duplikaty zamiast aktualizować rekordy.

Warstwa API zamienia sieć połączeń „każdy z każdym” w układ gwiazdy: systemy komunikują się z jednym miejscem, które rozumie dane produktowe. O samej idei piszemy szerzej w artykule co to jest warstwa API w systemie firmowym.

Podział odpowiedzialności za dane

Zanim powstanie pierwszy endpoint, ustalamy źródło prawdy dla każdej grupy danych:

• PIM – nazwy, opisy, atrybuty techniczne, zdjęcia, tłumaczenia, przypisanie do kategorii kanałów.
• ERP – indeks, jednostki miary, ceny bazowe i cenniki klientów, stany magazynowe, dostępność.
• E-commerce B2B – konta klientów, koszyki, zamówienia, ustawienia widoczności w danym kanale.
• Warstwa API w Laravel – wspólny model produktu, mapowania identyfikatorów i kategorii, reguły walidacji, historia zmian.

Reguła jest prosta: dane edytuje się tylko w systemie źródłowym. Jeśli handlowiec chce poprawić opis w sklepie, poprawka trafia do PIM, a nie do bazy sklepu.

Architektura warstwy API w Laravel

Wspólny model produktu

Sercem rozwiązania jest kanoniczny model: produkt, warianty, atrybuty z typami i jednostkami, media, relacje (akcesoria, zamienniki) oraz tabela mapowań identyfikatorów, bo SKU w ERP, identyfikator w PIM i ID w sklepie rzadko są tym samym. Każdy rekord ma sumę kontrolną ostatniej wersji – pozwala szybko wykryć, czy coś faktycznie się zmieniło.

Wejście: webhooki i synchronizacja przyrostowa

Nowoczesne systemy PIM (np. Akeneo) udostępniają REST API, a część z nich wysyła zdarzenia o zmianach. Tam, gdzie zdarzeń nie ma, stosujemy synchronizację przyrostową: pobieranie rekordów zmienionych od ostatniego znacznika czasu. Raz na dobę wykonujemy pełne uzgodnienie, które wychwytuje rekordy pominięte przez przyrost.

Przetwarzanie: kolejki i idempotencja

Każda paczka danych trafia do kolejki jako osobne zadanie (Laravel Queues z Redisem, podgląd i monitoring w Horizon). Zadania są idempotentne: rekord identyfikowany jest po stabilnym kluczu, a ponowne przetworzenie tej samej paczki nie tworzy kopii. Błędne rekordy nie blokują całego importu – trafiają do osobnej listy z opisem przyczyny.

Walidacja

Reguły walidacji zależą od kanału. Produkt może być kompletny dla katalogu wewnętrznego, ale nie dla sklepu, jeśli brakuje zdjęcia albo jednostki opakowania. Warstwa API zapisuje status kompletności per kanał i nie publikuje produktów, które go nie spełniają.

Wyjście: API dla kanałów

Sklep, portal B2B czy partnerzy dostają wersjonowane API (np. `/api/v1/products`) zbudowane na API Resources, z uwierzytelnianiem tokenami (Laravel Sanctum lub OAuth2 przez Passport), limitami zapytań i dokumentacją w formacie OpenAPI. Tam, gdzie kanał tego wymaga, warstwa sama wypycha zmiany do jego API.

Stos technologiczny

Nowe integracje budujemy na aktualnym Laravel (12 lub 13) i PHP 8.3 lub 8.4. Jeśli firma ma starszą integrację na PHP 7.4 czy 8.0, warto pamiętać, że te wersje od dawna nie mają wsparcia bezpieczeństwa, podobnie jak PHP 8.1 od końca 2025 roku.

Przykładowy przepływ: nowy produkt od PIM do sklepu

1. Zespół produktowy uzupełnia w PIM opis, atrybuty i zdjęcia nowego wariantu i oznacza go jako gotowy dla kanału B2B.
2. PIM wysyła zdarzenie lub warstwa API wykrywa zmianę przy kolejnym przebiegu przyrostowym.
3. Zadanie w kolejce pobiera pełny rekord, mapuje atrybuty na model kanoniczny i sprawdza kompletność.
4. Warstwa dociąga z ERP cenę bazową, jednostki i stan dla tego SKU.
5. Produkt spełnia reguły kanału – zadanie publikuje go w sklepie B2B, a identyfikator nadany przez sklep zapisuje w tabeli mapowań.
6. Wszystkie kroki są w logu. Jeśli sklep odrzuci rekord, zadanie wraca do kolejki z ograniczoną liczbą ponowień, a po ich wyczerpaniu trafia do panelu błędów.

Typowe błędy

• Logika biznesowa rozsiana po skryptach eksportu. Przeliczenia jednostek czy reguły widoczności powinny być w jednym miejscu.
• Brak tabeli mapowań. Łączenie rekordów po nazwie produktu kończy się duplikatami przy pierwszej literówce.
• Synchronizacja „wszystko co noc”. Pełny eksport tysięcy produktów przy każdej zmianie obciąża systemy i opóźnia aktualizacje. Przyrost plus nocne uzgodnienie to rozsądny kompromis.
• Ciche błędy. Zadanie, które kończy się niepowodzeniem bez alertu, oznacza produkt, który zniknął ze sklepu i nikt o tym nie wie.
• Brak wersjonowania API. Zmiana struktury odpowiedzi psuje integrację partnera, który nie był na nią przygotowany.

O ograniczaniu błędów w wymianie danych z partnerami piszemy w tekście API i integracje z partnerami – jak ograniczyć błędy danych, a o połączeniu ERP, PIM i paszportu produktu w artykule API, ERP, PIM i DPPC – jak połączyć dane produktowe.

Monitoring i utrzymanie

Warstwa API działa w tle, więc potrzebuje własnej widoczności: dashboard kolejek, alert przy rosnącej liczbie nieudanych zadań, dzienny raport produktów zablokowanych przez walidację i prosty panel, w którym zespół produktowy sam sprawdzi, dlaczego dany SKU nie trafił do sklepu. To ostatnie odciąża IT bardziej niż jakakolwiek optymalizacja kodu.

Kiedy taka warstwa nie jest potrzebna

Nie każda firma musi budować osobną warstwę API. Jeśli masz jeden sklep, prosty katalog bez wariantów i PIM z gotowym, utrzymywanym konektorem do tej platformy, dodatkowy system może być zbędnym kosztem. Warstwa w Laravel zaczyna się opłacać, gdy kanałów jest kilka, reguły cenowe i widoczności różnią się między nimi, a zespół traci czas na wyjaśnianie, skąd wzięła się rozbieżność.

Następny krok

Spisz listę systemów, które dziś wymieniają dane produktowe, i dla każdej grupy danych zaznacz, który system jest źródłem prawdy. Jeżeli przy którejś pozycji pojawiają się dwa systemy albo odpowiedź „to zależy”, właśnie tam warto zacząć. Jak projektujemy takie rozwiązania, opisujemy na stronie integracje API w Laravel. Jeśli chcesz omówić swój przypadek, skontaktuj się z nami.