Integracja może używać kilku warstw naraz: wewnętrznego ID systemu, stabilnego SKU firmy, EAN jednostki handlowej, identyfikatora dostawcy i mapy powiązań. Problem zaczyna się wtedy, gdy proces szuka „pierwszego podobnego kodu”.
Po każdym uruchomieniu powstają nowe produkty zamiast aktualizacji istniejących, a część stanów aktualizuje się na niewłaściwym rekordzie — albo pozycje zamówienia w BaseLinkerze mają pustą kolumnę „ID produktu” i stan nie schodzi (patrz zamówienie z Magento nie zmniejsza stanu w BaseLinkerze).
Sprawdź, czy integracja przechowuje relację source_id → target_id, czy przy każdym przebiegu szuka produktu od nowa.
Ścieżka 1 z 2 Wybieram klucz
Sekcje 1–8: klucz dla konkretnej operacji, kolejność dopasowania, rola SKU i EAN, identyfikatory wariantu, zmiana SKU i spisana polityka.
Jaki identyfikator do jakiej operacji
Zamiast jednej reguły „zawsze SKU” albo „zawsze EAN” warto mieć tabelę decyzji dla konkretnych operacji. SKU i EAN zapisane w zamówieniu w chwili zakupu są kluczem także w historii zamówień partnerów na platformie B2B.
| Operacja | Preferowany klucz |
|---|---|
| aktualizacja istniejącego produktu | mapa ID lub stabilne SKU |
| matching z hurtownią | ID dostawcy + EAN/SKU według jakości danych |
| skanowanie magazynowe | EAN |
| warianty | unikalne SKU i EAN wariantu |
| historia zamówienia | wewnętrzne ID + zapis SKU/EAN z momentu zakupu |
Kolejność dopasowania produktów
Mapa identyfikatorów jest najpewniejsza, bo nie wymaga ponownego zgadywania przy każdym uruchomieniu. Po pierwszym poprawnym połączeniu rekordów integracja zapisuje relację i używa jej dalej.
- Mapa IDistniejąca mapa
source_id → target_id - SKUzgodne i unikalne SKU
- EANzgodny i unikalny EAN
- Ręczna kolejkaręczna kolejka dopasowania
- Nigdy: nazwanigdy: automatyczne dopasowanie wyłącznie po nazwie
SKU jest identyfikatorem operacyjnym
SKU powstaje wewnątrz firmy. Może kodować model, kolor, rozmiar, sezon albo kolejny numer. Najważniejsze, żeby było stabilne, unikalne w danym katalogu i nie zmieniało się bez procesu migracji.
SKU jest dobrym kluczem do aktualizacji stanów, cen i danych pomiędzy systemami tej samej organizacji, jeżeli wszystkie systemy rzeczywiście korzystają z tej samej wartości. Nie można zakładać tego bez sprawdzenia — ERP, sklep i BaseLinker mogą mieć różne pola nazwane „SKU”.
EAN identyfikuje jednostkę handlową
EAN jest używany w handlu, skanowaniu, marketplace i wymianie danych z partnerami. W katalogu wariantowym zwykle identyfikuje konkretny wariant, nie całą rodzinę produktu.
EAN może być dobrym kluczem do matchingu z hurtownią albo marketplace, ale tylko wtedy, gdy jest poprawny i unikalny. Brak EAN nie oznacza automatycznie, że produktu nie da się integrować. Produkty własne, usługi lub część katalogów B2B mogą działać wyłącznie na SKU.
Ta sama wartość w pliku, dwie różne role
- powstaje wewnątrz firmy; stabilne i unikalne w katalogu
- klucz do stanów, cen i danych w systemach tej samej organizacji
- warunek: wszystkie systemy używają tej samej wartości
- identyfikuje jednostkę handlową, zwykle wariant
- klucz do hurtowni i marketplace, gdy jest poprawny i unikalny
- brak EAN nie wyklucza integracji
Dlaczego nie należy wybierać jednego identyfikatora dla wszystkiego
Najbezpieczniejszy matching nie polega na szukaniu pierwszego podobnego kodu. Powinien mieć ustaloną kolejność i poziom pewności.
- ID rekorduwewnętrzny identyfikator rekordu systemu
- SKUstabilne SKU firmy
- EANEAN jednostki handlowej
- Dostawcaidentyfikator dostawcy
- Mapamapa powiązań między systemami
Warianty wymagają identyfikatora na poziomie jednostki sprzedażowej
Koszulka w kolorze czarnym i rozmiarze M musi mieć identyfikator odróżniający ją od rozmiaru L. Wspólne SKU rodziny nie wystarczy do aktualizacji stanu wariantu.
parent_sku- Rodzina albo model. Nie jest sprzedawaną jednostką.
sku- Konkretny wariant. Klucz operacyjny aktualizacji.
ean- Jednostka handlowa wariantu. Klucz do skanowania i marketplace.
source_id/target_id- Rekord w systemie źródłowym i docelowym. Podstawa mapy powiązań.
Zmiana SKU jest migracją, nie zwykłą edycją
Jeżeli SKU pełni funkcję klucza integracji, jego zmiana może zerwać powiązania, utworzyć duplikat albo przestać aktualizować stary rekord. Dlatego zmiana SKU powinna tworzyć historię aliasów lub aktualizować mapę identyfikatorów.
Zmiana SKU krok po kroku
- Mapaeksportuj mapę stary SKU → nowy SKU
- Zależnościsprawdź zamówienia, magazyn i marketplace
- Kopiawykonaj migrację na kopii
- Blokadazablokuj równoległe aktualizacje
- Liczbyzweryfikuj liczbę rekordów przed i po
Polityka identyfikatorów powinna być spisana
To krótki dokument, ale usuwa wiele problemów z importami, stanami i zamówieniami. Szersza architektura — kto rządzi którym polem między sklepem, ERP i BaseLinkerem — jest tematem poradnika o źródle prawdy.
| Pytanie, na które odpowiada |
|---|
| kto nadaje SKU i czy może się zmienić |
| czy wielkość liter ma znaczenie |
| czy SKU produktu i wariantu są oddzielne |
| kiedy EAN jest obowiązkowy i jak obsłużyć jego brak |
| jak wykrywać duplikaty (procedura dla EAN – sekcja 10) |
| gdzie przechowywana jest mapa identyfikatorów między systemami |
Ścieżka 2 z 2 Rozwiązuję duplikat
Sekcje 9–10: typowe konflikty i procedura dla duplikatu EAN – eksport, wykrycie, rozpoznanie przypadku, korekta i sprawdzenie.
Typowe konflikty
Każdy z poniższych przypadków powinien trafić do raportu, nie do cichego automatycznego połączenia. Wykrywamy je w ramach audytu danych produktowych. Procedurę wykrywania i rozstrzygania duplikatów EAN opisuje sekcja 10.
| Konflikt do raportu, nie do cichego połączenia |
|---|
| jedno SKU występuje przy dwóch produktach |
| jeden EAN przypisano do kilku rozmiarów |
| ERP przechowuje SKU bez prefiksu, sklep z prefiksem |
BaseLinker ma własny numer katalogowy zamiast SKU producenta. W naszym wdrożeniu B2B product_id z katalogu BaseLinkera zapisujemy w atrybucie produktu Magento przy cyklicznej synchronizacji stanów, bo odpowiedź API i tak go zwraca; eksport zamówienia nie szuka produktu od nowa |
| dostawca zmienił kod produktu |
| stary produkt został skopiowany wraz z EAN |
| arkusz usunął zera z początku EAN |
| produkt główny i wariant mają ten sam identyfikator |
Jak wykryć i rozstrzygnąć duplikat EAN
Duplikat EAN to dwa albo więcej rekordów z tym samym kodem w jednym katalogu. Nie zawsze jeden z nich jest zbędny: czasem to ten sam produkt zapisany dwa razy, czasem kod trafił do innego wariantu albo do innej jednostki sprzedażowej. Dlatego najpierw ustalamy, który przypadek zachodzi, a dopiero potem zmieniamy dane i powiązania.
- Eksportte same kolumny z każdego systemu, EAN jako tekst
- Wykryciekolumna do porównania, kod w 14 pozycjach, grupy po kodzie
- Rozpoznanieatrybuty, ilość w opakowaniu, kod z etykiety
- Korektawstrzymanie zapisu, kopia, wyłączenie zamiast usunięcia
- Sprawdzeniejeden aktywny rekord na kod w katalogu
Te same atrybuty, ilość i jednostka: jeden rekord zostaje główny, drugi zostaje wyłączony.
Inny wariant, inne opakowanie, produkt główny albo kopia: kod zostaje przy rekordzie potwierdzonym etykietą albo kartą producenta.
Ręczna kolejka dopasowania (sekcja 02), bez automatycznego połączenia po tym kodzie.
1. Eksport do porównania
ID, SKU, parent_sku, atrybuty, EAN jako tekst, opakowanie, status, powiązania
Z każdego systemu, w którym EAN służy do łączenia rekordów (sklep, ERP, BaseLinker, plik hurtowni), potrzebny jest eksport z tymi samymi kolumnami:
- wewnętrzne ID rekordu, SKU, SKU rodziny (
parent_sku) i atrybuty wariantu (rozmiar, kolor) - EAN zapisany jako tekst – format liczbowy w arkuszu obcina zera z początku kodu
- ilość w opakowaniu i jednostka miary (sztuka, zgrzewka, karton)
- status rekordu, źródło (import, hurtownia, ręczne dodanie) i data utworzenia
- powiązania: wpis w mapie identyfikatorów, oferty marketplace, stan
2. Wykrycie konfliktu
kolumna do porównania, długość i cyfra kontrolna, zapis w 14 pozycjach, grupy po kodzie
Wartość źródłowa zostaje bez zmian; do porównania powstaje osobna kolumna. Usuwa się z niej wyłącznie uzgodnione znaki formatowania (na przykład spacje wstawione przy eksporcie), a potem sprawdza długość (GTIN ma 8, 12, 13 albo 14 cyfr), to, czy zostały same cyfry, i cyfrę kontrolną.
Dopiero poprawny kod porównuje się w postaci 14-cyfrowej, uzupełnionej zerami z lewej – tak GS1 zapisuje krótsze GTIN w 14 pozycjach, więc ten sam kod z obciętym zerem i bez niego daje tę samą wartość. Zapisu nietypowego albo uszkodzonego (litera w środku, zła długość, błędna cyfra kontrolna) nie naprawia się przez usuwanie znaków – trafia do wyjaśnienia.
Rekordy grupujemy po kodzie w obrębie jednego katalogu – także te z kodem do wyjaśnienia (po wartości źródłowej), bo błędny kod też może powtarzać się w kilku rekordach. Każda grupa z więcej niż jednym rekordem trafia do raportu konfliktów; przy kodzie uszkodzonym raport pokazuje oba problemy, a automatyczne dopasowanie po tym kodzie zostaje wstrzymane.
Ten sam EAN w sklepie i w ERP to oczekiwane powiązanie, a nie konflikt – konfliktem jest dopiero sytuacja, w której kod prowadzi w drugim systemie do innego rekordu niż mapa powiązań.
3. Rozpoznanie przypadku i jednostki sprzedażowej
pięć przypadków w tabeli: co widać, co to zwykle oznacza, rozstrzygnięcie
| Co widać w grupie | Co to zwykle oznacza | Rozstrzygnięcie |
|---|---|---|
| te same atrybuty, ilość i jednostka; inne źródło albo data utworzenia | ten sam produkt zapisany dwa razy (drugi import, druga hurtownia) | po potwierdzeniu, że oba rekordy to ten sam produkt i ta sama jednostka, jeden zostaje główny (tu pomaga historia sprzedaży i ofert), drugi zostaje wyłączony; stanów nie sumuje się automatycznie (krok 4) |
| różne rozmiary albo kolory tej samej rodziny | kod przypisany do niewłaściwego wariantu | kod zostaje przy wariancie potwierdzonym przez źródło (etykieta, karta producenta, dane dostawcy); pozostałe dostają kod z tego samego źródła, nie z domysłu |
| różna ilość w opakowaniu (sztuka, zgrzewka, karton) | kod jednostki pomylony z kodem opakowania | według zasad GS1 każdy poziom opakowania powyżej jednostki podstawowej ma własny GTIN, a zmiana liczby sztuk w opakowaniu zbiorczym wymaga nowego – właściwy kod odczytuje się z etykiety danej jednostki albo z karty producenta |
| produkt główny i jego wariant | kod wpisany na poziomie rodziny | produkt główny nie jest sprzedawaną jednostką (sekcja 06) – kod zostaje przy wariancie |
| nowy rekord powstał przez skopiowanie starego | kod przeniesiony razem z kopią | kod zostaje przy rekordzie, którego wariant i jednostkę potwierdza etykieta albo karta producenta; drugi rekord dostaje kod ze źródła albo czeka bez EAN |
Rozstrzygnięcie opiera się na atrybutach, ilości w opakowaniu i kodzie z etykiety albo karty producenta – nie na nazwie produktu i nie na historii sprzedaży, bo starszy rekord też może mieć błędny kod. Historia pomaga wybrać rekord zachowywany przy scaleniu dopiero wtedy, gdy wiadomo, że oba rekordy oznaczają ten sam produkt. Grupa, której nie da się rozstrzygnąć jednoznacznie, idzie do ręcznej kolejki dopasowania (sekcja 02).
4. Bezpieczna korekta powiązań
co korzysta z kodu, wstrzymanie zapisu, stany, kolejność, wyłączenie, poprawka u źródła
- Co korzysta z kodu. Przed zmianą trzeba sprawdzić mapę powiązań, oferty marketplace połączone po EAN, zamówienia w realizacji i reguły importu z hurtowni.
- Wstrzymanie zapisu. Importy i synchronizacje, które mogą w tym czasie zapisać te rekordy, zostają wstrzymane – jak przy zmianie SKU (sekcja 07). Przed zmianą powstaje kopia danych.
- Stany przed korektą. Trzeba ustalić, czy stany obu rekordów to kopie tej samej dostępności, czy osobny zapas (inna partia, inny magazyn). Nie sumuje się ich automatycznie – dodanie kopii podwoiłoby dostępność, a osobny zapas wymaga decyzji, przy którym rekordzie i magazynie zostaje.
- Kolejność. Najpierw mapa powiązań wskazuje rekord główny, potem zmieniają się powiązania ofert i rekordów, a na końcu kod przy drugim rekordzie. Sposób zmiany powiązań ofert zależy od platformy; przy każdej zmianie zostaje zapis stanu „przed”, żeby dało się ją wycofać.
- Wyłączenie zamiast usunięcia. Historia zamówień odwołuje się do kodu z momentu zakupu (sekcja 01). W BaseLinkerze usunięcie produktu nie jest tym samym co stan 0 – według FAQ Base.com oferta traci wtedy powiązanie (mapa objawów BaseLinkera).
- Poprawka u źródła. Jeśli błędny kod przychodzi z pliku hurtowni albo z ERP, trzeba go poprawić u źródła albo dodać wyjątek w mapie powiązań – inaczej następny import odtworzy konflikt.
5. Sprawdzenie po korekcie
jeden aktywny rekord na kod, liczby rekordów, stan, oferty, kolejny import
- w każdej poprawionej grupie jeden aktywny rekord na kod w katalogu
- liczba wszystkich rekordów bez zmian – wyłączenie nie usuwa rekordu
- liczba aktywnych rekordów mniejsza dokładnie o rekordy wyłączone według planu
- stan zgodny z ustaleniem z kroku 4 (bez podwojenia), oferty przy właściwym rekordzie, w każdym systemie
- kolejny przebieg importu nie tworzy rekordu od nowa i nie przywraca starego kodu