Integracja feedu Kaufland: czego naprawdę wymaga model danych

Kaufland nie przyjmuje jednego pliku z produktami i cenami. Przyjmuje dane produktowe, które zasilają wspólny rekord w katalogu, i osobno ofertę: Twoją cenę, stan magazynowy, czas obsługi i Twój własny identyfikator. Większość problemów z integracją bierze się z próby wciśnięcia obu rzeczy w jeden „feed”, w takim sensie, w jakim feedem jest plik do Google Shopping.

Ten tekst opisuje model danych Kauflandu od strony wdrożenia: co jest kluczem, co jest polem wymaganym, co dzieje się z danymi po wysłaniu i w którym miejscu takie integracje najczęściej pękają. Wszystko sprawdzone w dokumentacji Seller API 27 października 2026. Jeśli szukasz narzędzia, a nie modelu, mamy osobny tekst o budowie feedów agentem.

Dwie rzeczy jadą do Kauflandu, nie jedna

Dokumentacja stawia ten podział na pierwszej stronie: dane produktowe i dane magazynowe są trzymane osobno. Produkt to wpis w katalogu, wspólny dla wszystkich sprzedawców. Oferta, w dokumentacji nazywana jednostką, to dane magazynowe jednego produktu u jednego sprzedawcy. Jeden rekord produktu, wiele ofert podpiętych pod niego.

Konsekwencja jest praktyczna i widać ją w harmonogramie. Zmiana ceny albo stanu nie dotyka katalogu, więc może lecieć co kilka minut i nie podlega żadnej moderacji. Poprawka tytułu, atrybutu albo zdjęcia dotyka wspólnego rekordu, więc idzie inną drogą, wolniej i z weryfikacją. Jeśli jeden proces w Twoim systemie robi obie rzeczy jednym wywołaniem, to przy każdej aktualizacji ceny wysyłasz do moderacji cały opis, a przy każdej poprawce opisu ryzykujesz, że stan na magazynie poczeka na zakończenie kontroli.

Ofertę identyfikuje Twój własny id_offer, który musi być unikalny w całym Twoim asortymencie. Po tym identyfikatorze Kaufland synchronizuje magazyn i ilość, więc to on, a nie EAN, jest kluczem Twojej strony integracji. Wymagane przy tworzeniu oferty są jeszcze cena większa od zera, stan produktu oraz czas obsługi liczony w dniach roboczych.

Ten jeden szczegół decyduje o spokoju przy każdej kolejnej aktualizacji.

EAN decyduje, czy produkt w ogóle istnieje

Dokumentacja plików produktowych nie owija tego w bawełnę: każdy produkt ma EAN, a bez EAN-u Kaufland nie potrafi produktu zidentyfikować. EAN jest spoiwem, które łączy Twoją ofertę z rekordem w katalogu i z ofertami innych sprzedawców tego samego produktu.

Dla marki własnej oznacza to zadanie, które trzeba zaplanować przed integracją: zdobycie i przypisanie kodów do każdego wariantu, który ma być sprzedawany osobno. Mapowanie po SKU tego nie zastąpi, bo SKU jest Twoim wewnętrznym porządkiem, a EAN wspólnym językiem całego rynku. Zestawy, multipacki i warianty rozmiarowe są w tym modelu osobnymi produktami, więc każdy potrzebuje własnego kodu, a nie wariantu dopisanego do kodu produktu bazowego. Przy katalogu liczonym w tysiącach pozycji sama ewidencja, który wariant ma już kod, bywa osobnym projektem.

Brakujące EAN-y są najczęstszą przyczyną tego, że projekt „integracja Kauflandu” zatrzymuje się na dwa tygodnie w połowie.

Plik: średnik, UTF-8 i locale w każdym wierszu

Jeśli dane idą plikiem, a nie przez API, wymagania są konkretne i warto je znać przed pierwszym eksportem. Poniżej to, co dokumentacja podaje wprost.

Ostatni wiersz tabeli bywa pułapką. Automatyczna kategoryzacja działa, dopóki katalog jest typowy, a przy produktach z pogranicza kategorii zaczyna wybierać gałęzie, których nikt u Ciebie nie sprawdził. Skutek nie jest kosmetyczny: gałąź decyduje o tym, jakie atrybuty są wymagane i w jakich filtrach produkt się pokaże, więc zła kategoria potrafi wyciąć ofertę z wyników, w których ktoś faktycznie szuka. Dla asortymentu, który ma znaczenie dla przychodu, kategorię warto podawać jawnie i trzymać ją w mapowaniu razem z atrybutami.

Twoje dane są kandydatem do opisu, nie opisem

To jest ta część modelu, która zaskakuje najmocniej. Opis produktu w Kauflandzie powstaje z połączenia wielu źródeł: serwisów informacji produktowej, sprzedawców, producentów i zespołu zarządzania danymi po stronie Kauflandu. Dokumentacja dodaje wprost, że część przesłanych przez Ciebie danych może nie zostać wybrana do finalnego opisu.

Dla kogoś, kto przychodzi z Amazona albo z własnego sklepu, to zmiana nawyku: karta produktu jest wspólna, a nie Twoja.

Wniosek dla wdrożenia: nie buduj procesu, którego miarą sukcesu jest „nasz opis jest na karcie”. Miarą jest stan Twojej oferty i jej widoczność. Treść warto wysyłać dobrze przygotowaną, bo to zwiększa szansę, że zostanie wybrana, ale kontrolujesz ofertę, nie katalog.

Co dzieje się po wysłaniu

Dane nie publikują się w momencie odpowiedzi. Status aktualizacji zaczyna się od stanu oczekującego, a przy kontroli automatycznej albo ręcznej przechodzi w stan „w toku”. Część wartości, jak podaje dokumentacja, trafia do ręcznej weryfikacji przez category management. Na końcu oferta albo jest widoczna, albo dostaje blokadę z jednym z kodów przyczyny.

Czas tej kontroli nie jest po Twojej stronie.

Kodów przyczyny jest dwadzieścia cztery i dotyczą rzeczy, których żaden eksport sam nie naprawi: braku zgody na markę, wątpliwości co do autentyczności, braku certyfikatów, ograniczeń regulacyjnych, bezpieczeństwa produktu. To znaczy, że integracja musi umieć je odczytać i pokazać człowiekowi, bo poprawka siedzi w dokumentach albo w decyzji biznesowej, nie w pliku.

Gdzie te integracje pękają w praktyce

Z naszych wdrożeń kanałowych wracają te same cztery rzeczy, zawsze w tej samej kolejności.

• Wysyłka w jedną stronę. Dane lecą do kanału, nikt nie czyta statusów ani kodów blokad. Panel sprzedawcy staje się jedynym miejscem, w którym widać prawdę, więc nikt tam nie zagląda regularnie.
• Mapowanie w arkuszu. Przypisanie atrybutów i kategorii żyje w pliku na dysku jednej osoby. Przy zmianie wymagań kanału nie ma czego wersjonować ani czego przetestować.
• Oferta aktualizowana per produkt. Stan i cena wysyłane po EAN-ie zamiast po id_offer kończą się rozjazdem, gdy ten sam produkt pojawi się u Ciebie w dwóch magazynach albo w dwóch stanach.
• Jeden locale potraktowany jako tłumaczenie tytułu. Rynki różnią się nie tylko językiem, ale też wymaganymi atrybutami i oczekiwaniami filtrów, a wiersz z locale jest miejscem, gdzie te różnice trzeba obsłużyć.

Jak zbudować to tak, żeby dało się utrzymać

Architektura, która u nas przechodzi próbę czasu, ma cztery warstwy i każda z nich odpowiada za jedną rzecz.

• Katalog jako źródło prawdy. Jedno miejsce z danymi produktowymi, z którego zasilane są wszystkie kanały. Bez tego każdy kanał zaczyna żyć własnym życiem.
• Warstwa mapowania per kanał. Schemat Kauflandu opisany w kodzie: wymagane atrybuty, kategorie, jednostki, locale. Zmiana wymagań kanału to zmiana w jednym pliku i jeden test.
• Walidacja przed wysłaniem. Brak EAN-u, zero w cenie, ujemny czas obsługi albo zduplikowany id_offer wychodzą u Ciebie, a nie w moderacji. Tanio i od razu.
• Kolejka z ponowieniami i odczytem stanu. Każda wysyłka ma swój identyfikator, a jej stan jest sprawdzany i zapisywany. Blokady trafiają na listę do człowieka z kodem i produktem.

To jest dokładnie zakres, który u klientów robimy jako automatyzację feedów, a przy wejściu na nowy kanał jako ekspansję na marketplace. Jeśli masz katalog w sklepie i chcesz go wystawić na Kauflandzie bez ręcznego klepania plików, napisz do nas i obejrzyjmy razem Twoje dane produktowe.

Jedno zastrzeżenie na koniec. Kaufland zmienia wymagania niezależnie od nas, a liczby, których dokumentacja nie podaje, jak limity rozmiaru pliku albo czas publikacji, celowo w tym tekście nie występują. Przed wdrożeniem sprawdź aktualną wersję dokumentacji Seller API.