Integracje B2B w Magento 2: Profiles, Mappings i kontrola synchronizacji w B2B Suite

Integracja Magento 2 z ERP, PIM, WMS lub CRM nie kończy się na wysłaniu danych do API. Trzeba jeszcze ustalić, której firmy dotyczą, powiązać identyfikatory, sprawdzić wynik i obsłużyć sytuację, w której druga strona nie przyjmie komunikatu. W sprzedaży B2B od tego zależy, czy zamówienie trafi do realizacji, kontrahent zostanie prawidłowo rozpoznany, a uzgodniony cennik dotrze do właściwego kanału.

Obszar Integrations w Kowal B2B Suite porządkuje tę pracę w pięciu miejscach: Profiles, Mappings, Sync Jobs, Dead Letter Queue oraz Sync Errors. Poniżej wyjaśniamy ich działanie i pokazujemy, jak wykorzystać je w codziennej obsłudze integracji B2B.

Opis opiera się na implementacji sprawdzonej w listopadzie 2026 r. Przykłady są ilustracyjne i zakładają wdrożenie adaptera obsługującego wskazany system oraz operację.

Co zapewnia Integrations, a za co odpowiada adapter?

Integrations dostarcza wspólną infrastrukturę: konfigurację profili, mapowania identyfikatorów, rejestr zadań, kontrolę prób, wyniki i historię błędów. Konkretne połączenie z ERP, PIM, WMS lub CRM realizuje adapter, czyli komponent, który zna API danego systemu i zasady wymiany danych.

To adapter ustala m.in. sposób uwierzytelniania, format komunikatów, przekształcanie pól i wykonanie operacji. Wybór typu „ERP” w profilu opisuje przeznaczenie integracji; nie instaluje automatycznie gotowego połączenia z dowolnym programem ERP.

Podobnie zapisanie zadania oznacza zarejestrowanie pracy do wykonania. Sam formularz nie uruchamia cyklicznego procesu w tle. Przetwarzanie i dobór zadań do uruchomienia trzeba podłączyć w ramach wdrożenia, np. przez proces wykonawczy, harmonogram lub middleware korzystające z udostępnionej logiki i API.

Pięć ekranów, pięć konkretnych pytań

Wszystkie te elementy opisują ten sam proces z innej perspektywy. Profil określa jego kontekst, mapowanie łączy rekordy, zadanie reprezentuje operację, a dwa ostatnie widoki pomagają obsługiwać niepowodzenia.

Profiles: konfiguracja integracji dla właściwego website

W B2B > Integrations > Profiles tworzysz i edytujesz profile integracji. Każdy profil należy do określonego website Magento z aktywnym B2B. Pozwala to rozdzielić konfigurację kanałów sprzedaży, np. krajowego i eksportowego, jeśli działają jako osobne websites.

Website jest tu jednostką organizacji kanału sprzedaży Magento. Kilka widoków językowych w tym samym website nie oznacza automatycznie kilku niezależnych integracji.

Config JSON nie ma jednego uniwersalnego zestawu pól dla wszystkich integracji. Znaczenie jego kluczy wynika z adaptera. Formularz sprawdza poprawność JSON, ale nie zastępuje testu połączenia z docelowym systemem. Dane dostępowe warto przekazywać przez odwołania do bezpiecznej konfiguracji, zgodnie z wymaganiami adaptera.

Praktyczne zastosowanie: zamiast wpisywać parametry ERP w wielu niezależnych skryptach, integrator korzysta z nazwanego profilu. Operator widzi, jaki system i kierunek wymiany obsługuje dany proces.

Mappings: powiązanie identyfikatorów Magento i systemu zewnętrznego

Ta sama firma może mieć identyfikator 42 w B2B Suite i kod ERP-C-0084 w ERP. Dla człowieka oba rekordy oznaczają jednego kontrahenta. Integracja potrzebuje jawnego powiązania, aby odczytać lub zaktualizować właściwą kartotekę.

W Mappings zapisujesz website, typ systemu, typ encji, identyfikator lokalny, identyfikator zewnętrzny i opcjonalne metadane JSON. Interfejs przewiduje m.in. firmy, klientów, produkty, kategorie, cenniki, zamówienia, RFQ i dokumenty.

Wartości w tabeli są przykładowe. To adapter ustala, jaką reprezentację identyfikatora lokalnego stosuje dla danej encji. Mapowania można wyszukiwać zarówno od strony identyfikatora lokalnego, jak i zewnętrznego.

Mappings jest mapą tożsamości rekordów, a nie wizualnym edytorem transformacji pól. Reguła typu „pole nazwa klienta z ERP trafia do pola company w Magento” należy do logiki adaptera. Podobnie samo zapisanie mapowania nie pobiera danych i nie wykonuje synchronizacji.

Kontekst mapowania obejmuje website, typ systemu i typ encji. Nie jest ono przypisane wyłącznie do jednego profilu. Przy kilku połączeniach tego samego typu w jednym website integrator powinien zaplanować spójną identyfikację rekordów. W danym kontekście baza pilnuje unikalności zarówno identyfikatora lokalnego, jak i zewnętrznego.

Sync Jobs: rejestr pracy i przebiegu synchronizacji

Sync Job reprezentuje konkretną operację, np. przekazanie jednego zamówienia do ERP. W formularzu Schedule Sync Job wybierasz aktywny profil, typ encji i operację. Możesz podać kierunek, dane wejściowe w JSON, klucz idempotencji, limit prób oraz termin zaplanowania. Jeśli kierunek nie został nadpisany, wynika z profilu.

Typ encji i nazwa operacji muszą być zrozumiałe dla adaptera. Przykładowa nazwa export_order może być częścią uzgodnionego rozwiązania, ale samo jej wpisanie nie tworzy obsługi eksportu.

Po otwarciu zadania przez View widzisz podsumowanie, dane wejściowe, wynik zapisany przez adapter, logi i błędy. Możesz sprawdzić website, profil, kierunek, encję, operację, liczbę prób, klucz idempotencji oraz czasy zaplanowania, rozpoczęcia i zakończenia.

Status success należy interpretować zgodnie z kontraktem adaptera. Jeżeli zewnętrzne API tylko przyjmuje komunikat do dalszej pracy, integrator powinien ustalić, czy wynik oznacza przyjęcie żądania, czy potwierdzone zakończenie operacji biznesowej.

Termin zaplanowania jest informacją dla procesu wykonawczego. Samo ustawienie daty nie zastępuje uruchomienia tego procesu ani zasad wyboru zadań gotowych do wykonania.

Idempotencja: jak ograniczyć duplikowanie zadań

Zdarza się, że middleware po przerwanym połączeniu ponownie zgłasza tę samą operację. Klucz idempotencji pozwala rozpoznać, że zadanie już istnieje. Przy publikowaniu zadania z tym samym kluczem w tym samym website mechanizm zwraca istniejący rekord zamiast tworzyć kolejny.

Klucz powinien identyfikować konkretną operację biznesową, np. eksport określonego zamówienia w danej wersji. Jest wspólny dla website, więc warto zawrzeć w nim rozpoznawalny kontekst systemu i operacji. Ponowne użycie starego klucza nie służy do aktualizowania danych wejściowych istniejącego zadania.

To ochrona przed powielaniem rejestracji zadań. Zabezpieczenie skutków po stronie ERP, np. przed utworzeniem drugiego dokumentu po niepewnym wyniku połączenia, musi również uwzględniać adapter i możliwości zewnętrznego API.

Dead Letter Queue: zadania wymagające decyzji operatora

Dead Letter Queue pokazuje zadania o statusie dead. Jest widokiem tych samych rekordów zadań, a nie drugą kopią komunikatów. Pomaga wyodrębnić operacje, których nie udało się zakończyć w przyznanym limicie prób.

Przy limicie trzech prób trzecie nieudane wykonanie adaptera ustawi zadanie jako dead. Nie oznacza to, że moduł sam uruchomi trzy próby jedna po drugiej. Kolejne uruchomienia i ewentualne odstępy między nimi wynikają z obsługi ponowień i procesu wykonawczego wdrożonego w sklepie.

Operator otwiera zadanie, analizuje błąd i usuwa przyczynę, np. poprawia brakujące powiązanie kontrahenta lub konfigurację połączenia. Następnie może użyć Retry Job.

Ponowienie jest dostępne dla zadań failed i dead. Nie tworzy nowego zadania i nie zeruje historii prób. Ustawia status retry, zapisuje bieżący termin ponowienia oraz czyści czas poprzedniego rozpoczęcia i zakończenia. Jeśli limit był wyczerpany, zwiększa go tak, aby dopuścić jeszcze jedną próbę. Dopiero późniejsze przetworzenie wykonuje adapter.

Sync Errors: historia błędów z kontekstem zadania

W Sync Errors przeglądasz zapisy błędów powstałych przy wykonaniu adaptera: kod, komunikat, czas oraz informację o możliwości ponowienia. Lista łączy je z aktualnym kontekstem zadania, profilu i website. Ułatwia to odróżnienie problemu jednego klienta od awarii całego połączenia.

W szczegółach zadania dostępne są powiązane błędy i logi techniczne. Logi pokazują m.in. rozpoczęcie, zakończenie i zaplanowanie ponowienia. Dane błędu przechowują również ślad techniczny przydatny integratorowi.

Jedno zadanie może mieć kilka wpisów błędów z kolejnych prób. Dlatego liczba błędów nie jest równoznaczna z liczbą niezrealizowanych operacji. Zadanie, które później zakończyło się sukcesem, może nadal mieć wcześniejsze błędy w historii.

Znacznik Retryable w tym mechanizmie wynika z pozostającego limitu prób w chwili błędu. Nie rozpoznaje automatycznie, czy przyczyna jest chwilowa. Błędny identyfikator nie naprawi się od samego ponowienia, nawet jeśli kolejna próba jest jeszcze dozwolona.

Najprostsze rozróżnienie: Sync Errors służy do analizy przyczyn, a Dead Letter Queue do przeglądu zadań, które wyczerpały próby.

Scenariusz 1: powiązanie firmy B2B z kontrahentem w ERP

Firma Alfa ma konto w Magento, ale w ERP już istnieje jej kartoteka. Zespół chce uniknąć tworzenia drugiego kontrahenta.

1. Integrator przygotowuje adapter ERP i profil dla właściwego website.
2. W Mappings zapisuje powiązanie firmy 42 z ERP-C-0084.
3. Zadanie obsługiwane przez adapter korzysta z mapowania, aby skierować dane do istniejącego rekordu.
4. Operator w Sync Jobs sprawdza wynik i identyfikatory zwrócone przez adapter.

Korzyścią jest spójna tożsamość kontrahenta. To, które pola są aktualizowane i który system jest ich źródłem, pozostaje częścią ustalonego zakresu integracji.

Scenariusz 2: zamówienie B2B trafia do ERP po przerwie w połączeniu

Klient składa zamówienie, a wdrożony mechanizm tworzy zadanie eksportu. ERP jest chwilowo niedostępny. Wykonanie adaptera kończy się błędem, który trafia do historii, a zadanie otrzymuje failed lub — po wyczerpaniu prób — dead.

Po przywróceniu połączenia operator analizuje wynik poprzedniej próby po stronie ERP. Następnie planuje Retry tego samego zadania. Adapter powinien rozpoznać ewentualny istniejący dokument, aby nie utworzyć go ponownie, jeśli wcześniejsze żądanie zostało przyjęte mimo zerwanej odpowiedzi.

Po poprawnym zakończeniu wynik zadania może zawierać identyfikator dokumentu ERP, a adapter może zapisać odpowiednie mapowanie. Konkretna zawartość wyniku i moment utworzenia mapowania zależą od implementacji połączenia.

Scenariusz 3: aktualizacja cennika dla właściwego kanału B2B

ERP jest źródłem uzgodnionych warunków handlowych. Dla kanału hurtowego przygotowany jest profil importu i mapowanie cennika 7 na ERP-PRICELIST-DEALERS.

Adapter odczytuje dane z ERP, sprawdza SKU, walutę i progi ilościowe, a następnie zapisuje je zgodnie z zasadami modułu Pricing. Sync Job pozwala śledzić tę operację, a wynik adaptera może podsumować liczbę przetworzonych pozycji. Jeżeli wystąpi problem, operator ma kontekst zadania i komunikat błędu.

Integrations zapewnia obsługę przebiegu; reguły wyboru ceny pozostają w Pricing. Opisaliśmy je osobno w artykule o cennikach B2B i Price List w Magento 2. Zakres walidacji, obsługa częściowych zapisów i sposób aktualizacji indeksu muszą być określone w adapterze.

Scenariusz 4: powtarzający się błąd wymaga poprawy danych

System magazynowy odrzuca operację, ponieważ nie rozpoznaje produktu. Samo ponawianie nie zmienia sytuacji. Zadanie wyczerpuje limit i pojawia się w Dead Letter Queue.

Operator otwiera View Job, odczytuje komunikat, sprawdza identyfikatory i — jeżeli przyczyną jest brak odpowiedniego powiązania — poprawia Mappings. Po usunięciu przyczyny wybiera Retry Job i kontroluje wynik kolejnego przetworzenia.

Ten scenariusz pokazuje, dlaczego potrzebne są zarówno mapowania, jak i historia błędów. Kolejka daje możliwość powrotu do operacji, a diagnoza wskazuje, co trzeba naprawić przed następną próbą.

Jak wdrożyć Integrations krok po kroku

1. Wybierz pierwszy proces. Zacznij np. od eksportu zamówień, zamiast łączyć od razu wszystkie obszary.
2. Ustal źródła danych. Zdecyduj, który system zarządza kontrahentem, cennikiem lub statusem realizacji i jak rozstrzygane są konflikty.
3. Przygotuj adapter i wykonawcę zadań. Określ obsługiwane operacje, formaty, uwierzytelnianie, uruchamianie i zasady ponowień.
4. Skonfiguruj Profiles oraz Mappings. Sprawdź website, kierunek i identyfikatory na kilku rzeczywistych przypadkach.
5. Przetestuj sukces i błędy. Uwzględnij niedostępne API, błędne dane, ponowne zgłoszenie tego samego zadania i wyczerpanie limitu prób.
6. Sprawdź wynik biznesowy. Potwierdź nie tylko status zadania, lecz także właściwy rekord w systemie docelowym.
7. Przypisz odpowiedzialność za obsługę. Ustal, kto sprawdza Sync Errors i Dead Letter Queue oraz kto poprawia dane lub połączenie.

Takie podejście pozwala oceniać integrację przez liczbę poprawnie obsłużonych operacji i czas usuwania problemów, zamiast wyłącznie przez sam fakt istnienia połączenia API.

Najczęstsze pytania o Integrations w B2B Suite

Czy profil ERP oznacza gotową integrację z każdym ERP?

Nie. Profil przechowuje kontekst i konfigurację. Komunikację z konkretnym systemem realizuje adapter przygotowany dla jego API i uzgodnionych procesów.

Czy Mappings służy do mapowania pól importu?

Ten ekran łączy identyfikatory rekordów lokalnych i zewnętrznych. Transformacje pól oraz formatowanie danych są odpowiedzialnością adaptera.

Czy kliknięcie Retry od razu wysyła dane?

Nie. Ponownie planuje istniejące zadanie. Wysłanie lub pobranie danych następuje przy kolejnym wykonaniu przez podłączony proces przetwarzania.

Czym różni się Dead Letter Queue od Sync Errors?

Dead Letter Queue pokazuje zadania o statusie dead, a Sync Errors zapisane błędy z kontekstem zadań. W historii mogą pozostać błędy operacji, która później zakończyła się sukcesem.

Czy moduł sam zapewnia ponawianie co kilka minut?

Mechanizm przechowuje terminy, statusy i liczniki oraz udostępnia ponowienie. Harmonogram przetwarzania, odstępy i ewentualne automatyczne wybieranie zadań do kolejnej próby trzeba skonfigurować w rozwiązaniu wykonawczym.

Czy można obsługiwać integrację przez API?

Warstwa API B2B Suite udostępnia zarządzanie profilami i mapowaniami, publikowanie, przetwarzanie i ponawianie zadań oraz odczyt zadań, logów i błędów. Wymaga właściwych uprawnień integracyjnych i kontekstu website tam, gdzie operacja go używa.

Integracja B2B, nad którą zespół ma kontrolę

Profiles porządkuje konfigurację, Mappings tożsamość rekordów, Sync Jobs przebieg pracy, a Dead Letter Queue i Sync Errors obsługę niepowodzeń. Wspólnie tworzą fundament integracji Magento 2 z systemami zaplecza, który można rozwijać o adaptery dopasowane do firmy.

Sprawdź Kowal B2B Suite dla Magento 2 Open Source lub opisz nam proces, który chcesz połączyć z ERP, PIM, WMS albo CRM. Na początek wystarczy wskazać system, kierunek wymiany i jedną operację, która dziś wymaga pracy ręcznej.

Przeczytaj także: jak ograniczyć ręczną obsługę sprzedaży B2B oraz ile kosztuje ręczna obsługa zamówienia B2B.