Flatfile na Amazon: gdy raport mówi sukces, a produktów nie ma

Raport przetwarzania na Amazonie potwierdza, że plik został przyjęty i przetworzony, a nie że zmiana weszła do katalogu. To dwie różne rzeczy i Amazon opisuje je wprost: status DONE oznacza tylko tyle, że przetwarzanie się zakończyło, a osobna grupa problemów pojawia się dopiero po przyjęciu zgłoszenia, już poza raportem. Dlatego walka z plikiem bywa ślepa. Wysyłasz kolejną wersję, czekasz, dostajesz to samo potwierdzenie i nadal nie wiesz, co poszło nie tak. Niżej: co dokładnie znaczą statusy przetwarzania, jak zdiagnozować taki przypadek, zanim wyślesz dziesiąty plik, i kiedy opłaca się przejść na SP-API, razem z uczciwą listą tego, czego to wymaga.

Stan dokumentacji Amazona: 13 sierpnia 2026. Opieramy się na oficjalnej dokumentacji Selling Partner API (Feeds, Listings Items, Product Type Definitions), a dwa opisane przypadki pochodzą z naszej pracy i są oznaczone jako doświadczenie, nie jako udokumentowana zasada. Nazwy statusów, nazwy atrybutów i limity zapytań Amazon aktualizuje, więc przed wdrożeniem potwierdź je w bieżącej wersji dokumentacji i w panelu swojego konta.

Co naprawdę znaczy „sukces" w raporcie przetwarzania

Flatfile, czyli wsad z danymi ofertowymi, przechodzi przez kolejkę. Amazon zwraca jego stan jako status przetwarzania i to jest pierwsze miejsce, w którym łatwo się pomylić. Te statusy mówią o losie pliku, nie o losie Twoich ofert.

Źródło: Amazon SP-API, Submit a feed. Ta sama strona podaje, że przy dużym obciążeniu przetwarzanie potrafi zająć do ośmiu godzin.

Druga warstwa jest ważniejsza i mniej oczywista. Nawet gdy zgłoszenie zostanie przyjęte, sprawa nie jest zamknięta. W dokumentacji zarządzania problemami ofert Amazon pisze, że „przyjęte" nie oznacza „zakończone": pozycję w katalogu tworzy kilka procesów po drodze i każdy z nich może wygenerować problem zwracany asynchronicznie, czyli już po tym, jak dostałeś potwierdzenie.

Stąd bierze się efekt, który wygląda jak awaria, a jest normalnym zachowaniem systemu: raport zamknięty, zero błędów, zero zmian na koncie. Ten sam mechanizm dotyczy aktualizacji cen i stanów magazynowych, więc cicha porażka wsadu przy zarządzaniu zapasami FBA oznacza po prostu, że sprzedajesz towar, którego nie masz, albo nie sprzedajesz tego, który leży w magazynie.

Dwa przypadki z naszej pracy

Poniższe dwie historie to nasze doświadczenie, nie reguła z dokumentacji. Opisujemy je, bo dobrze pokazują koszt diagnozy prowadzonej wyłącznie plikiem.

Warianty, których nie dało się podpiąć

U pierwszego klienta nie dawało się połączyć wariantów z produktem nadrzędnym. Wysyłaliśmy flatfile, Amazon zwracał potwierdzenie powodzenia, a po 48 godzinach okazywało się, że zmiany nie ma. Bez komunikatu błędu i bez wskazania przyczyny.

Napisaliśmy do wsparcia Amazona około sześciu razy w jednej sprawie i nie dostaliśmy odpowiedzi, która by to wyjaśniła. Równolegle szła standardowa procedura: kolejna wersja pliku, w każdej zmieniony jeden szczegół, bo nie było wiadomo, który jest winny. Każda próba to kolejne czekanie.

Do dziś nie wiemy, co dokładnie odrzucał wtedy Amazon. Nie mamy kodu błędu z tamtych wysyłek, bo raport go nie zwrócił, a wsparcie go nie podało. Wiemy tylko, że po przejściu na zapytania API sprawa zamknęła się tego samego dnia.

Produkty, których nie dało się dodać

Drugi przypadek był ostrzejszy: produktów nie dawało się dodać w ogóle. Znowu potwierdzenie powodzenia, znowu pusto na koncie, znowu wiele prób i wiele godzin oczekiwania między nimi.

W obu przypadkach zamknęliśmy sprawę w jeden dzień, pracując przez SP-API (Selling Partner API), zamiast wysyłać kolejne pliki w ciemno. Zapytania pisaliśmy i uruchamialiśmy w Claude Code, co skróciło drogę do pierwszego działającego wywołania. Samo narzędzie niczego jednak nie naprawiło: naprawiła to informacja zwrotna, której plik nie dawał. To zresztą dobry przykład zadania, w którym AI realnie pomaga sprzedawcy, bo pracuje na sprawdzalnej odpowiedzi systemu, a nie na treści pisanej na wyczucie.

Uczciwe zastrzeżenie: „jeden dzień" to nasze dwa przypadki, a nie obietnica. Skala katalogu, typ produktu, rynek i to, czy masz gotowy dostęp deweloperski, przesuwają ten czas w obie strony.

Dlaczego API pokazuje to, czego plik nie pokaże

Różnica nie polega na tym, że API jest „mocniejsze". Amazon w FAQ dla API ofertowych pisze wprost, że feed kolejkuje Twoje zgłoszenie i sam wywołuje Listings Items API w Twoim imieniu. Obie drogi trafiają docelowo w to samo miejsce. Różnica jest w tym, co i kiedy widzisz.

To ostatnie jest sednem. Odpowiedź z operacji putListingsItem albo patchListingsItem zawiera status zgłoszenia (ACCEPTED, INVALID, VALID) oraz listę problemów. Każdy problem ma kod, opis, wagę (ERROR, WARNING, INFO) i nazwy atrybutów, których dotyczy. Zamiast „coś jest nie tak z plikiem" dostajesz nazwę pola.

Dochodzą do tego trzy rzeczy, których w pracy plikiem po prostu nie ma:

• Podgląd błędów bez zapisu. Zapytanie z parametrem mode=VALIDATION_PREVIEW waliduje ofertę, nie zapisując danych w katalogu. Możesz sprawdzić poprawkę, zanim cokolwiek wyślesz na żywe konto.
• Stan oferty na żądanie. Operacja getListingsItem z parametrem includedData=issues pokazuje problemy przypięte do oferty w tej chwili, w tym te, które pojawiły się już po przyjęciu zgłoszenia.
• Wymagania zamiast zgadywania. Product Type Definitions API zwraca schemat JSON z wymaganiami atrybutów dla danego typu produktu na danym rynku. Odpowiada na pytanie „które pole jest tu obowiązkowe", zanim wypełnisz szablon.

Warto też znać zmianę, która przeszła bokiem: od 31 lipca 2025 r. Feeds API nie obsługuje już starych wsadów XML i flat file dla ofert, cen, stanów, relacji i zdjęć. Amazon zaznacza przy tym, że nie dotyczy to plików wgrywanych przez sprzedawcę bezpośrednio w Seller Central. Panel działa dalej, ale integracja oparta na starych typach feedów już nie.

Procedura: co sprawdzić, zanim wyślesz kolejny plik

Kolejność ma znaczenie, bo każdy krok odcina inną grupę przyczyn. Przy każdym podajemy, co robi się w panelu, a co przez API.

• Krok 1. Sprawdź stan oferty, nie raport wsadu. Raport mówi o pliku, karta oferty mówi o produkcie. Przez API: getListingsItem z parametrem includedData=issues. W panelu: widok problemów przy konkretnym SKU.
• Krok 2. Ustal, czy plik w ogóle doszedł do końca. Status inny niż terminalny (DONE, FATAL, CANCELLED) oznacza, że nie ma jeszcze czego oceniać. Wsady idą sekwencyjnie, więc wcześniejsza wysyłka potrafi blokować kolejną.
• Krok 3. Pobierz wymagania typu produktu dla tego rynku. Schemat z Product Type Definitions API rozstrzyga, które atrybuty są obowiązkowe. Ten sam typ produktu potrafi mieć różne wymagania w różnych krajach.
• Krok 4. Zawęź zmianę do jednego SKU i jednego atrybutu. Wsad zbiorczy miesza przyczyny. Pojedyncze zapytanie daje odpowiedź przypiętą do jednej oferty.
• Krok 5. Użyj podglądu błędów zamiast wysyłki. Tryb walidacji zwraca listę problemów bez zapisywania czegokolwiek, więc pętla skraca się z godzin do sekund.
• Krok 6. Sprawdź, czy ktoś nie nadpisuje Twoich danych. Amazon nie gwarantuje, że zgłoszenia z jednego feedu zostaną przetworzone w kolejności, w jakiej w nim występują, a dane z innych źródeł mogą mieć wyższy priorytet niż Twoje. Dwie równoległe integracje potrafią kasować sobie zmiany nawzajem.
• Krok 7. Dopiero teraz pisz do wsparcia. Zgłoszenie z kodem problemu, nazwą atrybutu i identyfikatorem zgłoszenia to rozmowa o konkrecie. Zgłoszenie „wysłałem plik i nic się nie stało" zwykle wraca z prośbą o wysłanie pliku jeszcze raz.

Reguła kciuka z naszej praktyki: jeśli po dwóch pełnych cyklach (plik, raport, brak zmiany) nadal nie masz kodu błędu, trzeci plik nie doda Ci informacji. Doda tylko kolejne godziny czekania.

Warianty: gdzie to najczęściej pęka po cichu

Relacje rodzic-dziecko są najbardziej wrażliwym miejscem w danych ofertowych, bo poprawność pojedynczej oferty nie wystarcza. Musi się zgadzać powiązanie między ofertami. Amazon wymaga od oferty potomnej trzech rzeczy naraz:

• Poziom w rodzinie: atrybut parentage_level ustawiony na wartość child.
• Wskazanie rodzica: atrybut child_parent_sku_relationship z typem relacji variation i numerem SKU produktu nadrzędnego.
• Temat wariantu: variation_theme zgodny z tematem ustawionym u rodzica, wraz z atrybutami, których ten temat wymaga.

Ostatni punkt jest tym, o który najłatwiej się potknąć. Wybór tematu wariantu, na przykład rozmiaru i koloru, nakłada obowiązek wypełnienia odpowiadających mu pól w każdej ofercie potomnej. Brakująca wartość w jednym dziecku potrafi wywrócić operację, a w szablonie wygląda jak pusta komórka wśród setek innych.

Czy to była przyczyna u naszego klienta? Nie wiemy i nie zamierzamy tego udawać. Sprawa domknęła się przez API, zanim udało się ustalić, co dokładnie odrzucała ścieżka plikowa. To niesatysfakcjonujące, ale prawdziwe.

Kiedy przejść na API i czego to wymaga

Przejście na API nie jest darmowe i nie każdemu się opłaca. Zanim je rozważysz, policz cztery koszty wejścia.

• Dostęp deweloperski. Potrzebujesz zarejestrowanej aplikacji w SP-API i autoryzacji na koncie sprzedawcy, z rolami odpowiednimi do zarządzania ofertami. To formalność, ale zajmuje czas.
• Umiejętności. Ktoś musi umieć wysłać uwierzytelnione zapytanie i przeczytać odpowiedź w formacie JSON. Asystent kodujący skraca drogę do pierwszego działającego wywołania, natomiast decyzję o tym, co poleci na żywe konto, podejmuje człowiek.
• Limity zapytań. Przy dużym katalogu to realne ograniczenie, nie formalność. Operacja createFeed ma limit 0,0083 zapytania na sekundę przy zapasie 15 zapytań, a dla typu JSON_LISTINGS_FEED Amazon dokłada próg 5 zgłoszeń na konto co 5 minut i 25 000 rekordów na zgłoszenie. Operacje Listings Items mają 5 zapytań na sekundę na parę konto-aplikacja, a tryb podglądu błędów ma własny, ostrzejszy limit. Dokumentacja podaje dla tego trybu różne wartości w różnych miejscach, więc przed projektowaniem integracji sprawdź aktualną stronę limitów.
• Utrzymanie. Schematy typów produktów się zmieniają. Integracja, której nikt nie dogląda, po kilku miesiącach zaczyna wysyłać dane niezgodne z bieżącymi wymaganiami.

Kiedy to się spina? Gdy problem jest powtarzalny, czyli ta sama operacja nie przechodzi na wielu SKU; gdy katalog jest duży; gdy ceną jednej nieudanej próby są godziny; albo gdy trzeba porównać stan oferty z tym, co według Ciebie zostało wysłane. Przy jednorazowej poprawce w dwudziestu ofertach plik nadal jest szybszy i nie ma w tym nic wstydliwego.

Warto przy okazji oddzielić dwa problemy: błąd w danych i błąd w procesie. Jeżeli te same pola co miesiąc wracają jako niezgodne, przyczyna leży wyżej, w źródle danych i sposobie ich rozsyłania. Automatyzację tej warstwy, czyli sprawdzanie ofert względem reguł kanału jeszcze przed publikacją, prowadzi nasza marka siostrzana Seedlight w ramach analizy błędów ofert.

Czego API nie naprawi

Przejście na zapytania zmienia jakość informacji zwrotnej, a nie prawa fizyki tej platformy. Zostaje z Tobą kilka rzeczy.

• Problemy asynchroniczne nie znikają. Status ACCEPTED nadal znaczy „przyjęte do przetwarzania", a nie „gotowe". Weryfikacja stanu oferty osobnym zapytaniem pozostaje częścią procesu.
• Kolejność nadal nie jest gwarantowana. Zgłoszenia z jednego feedu nie muszą być przetwarzane w kolejności, w jakiej w nim występują.
• Nie każdy brak zmiany to błąd danych. Część blokad wynika z polityk, kategorii albo zgodności produktu i widać je w innym miejscu niż w odpowiedzi API. Jeśli oferta znika albo nie daje się aktywować, sprawdź też stronę Account Health.
• Wsparcie nadal bywa wąskim gardłem. Kod błędu radykalnie poprawia rozmowę, ale są sprawy, których po stronie sprzedawcy zamknąć się nie da.

Jak z tym pracuje Amazonway

Prowadząc konta klientów, traktujemy pracę na danych ofertowych jako pracę techniczną, a nie klikanie w szablonach. Kolejność jest zawsze ta sama: najpierw ustalamy stan oferty i kod problemu, potem dobieramy narzędzie, a plik jest jednym z narzędzi, nie punktem wyjścia. Ten zakres wchodzi w obsługę kont marketplace, a podstawy samego wystawiania i optymalizacji oferty opisujemy w rozdziale przewodnika o wystawianiu produktu.

Uczciwe zastrzeżenie: nie każdy przypadek da się rozstrzygnąć po naszej stronie i nie obiecujemy terminów naprawy, bo część decyzji zapada w systemach Amazona, do których nie mamy wglądu. Odpowiadamy za to, żeby diagnoza opierała się na kodzie błędu i stanie oferty, a nie na kolejnej wersji pliku wysłanej na wyczucie.

FAQ: flatfile, raport przetwarzania i API

Dlaczego flatfile pokazuje sukces, a produktów nie ma?

Bo raport dotyczy przetwarzania wsadu, a nie stanu katalogu. Status DONE znaczy „przetwarzanie zakończone" i Amazon każe sprawdzić zawartość raportu pod kątem błędów. Dodatkowo część problemów powstaje dopiero po przyjęciu zgłoszenia, w procesach tworzących pozycję w katalogu, i wraca asynchronicznie. Stan oferty trzeba więc sprawdzić osobno.

Ile czasu Amazon potrzebuje na przetworzenie pliku?

Nie ma jednej liczby. Dokumentacja podaje, że przy dużym obciążeniu przetwarzanie potrafi zająć do ośmiu godzin, a czas przygotowania raportu nie zależy od liczby rekordów: plik z kilkoma wierszami też potrafi iść godzinami. Wsady z danymi produktowymi przetwarzane są sekwencyjnie.

Czy przejście na SP-API rozwiąże każdy problem z ofertami?

Nie. Zmienia jakość informacji zwrotnej: dostajesz kod problemu, jego wagę i nazwy atrybutów, których dotyczy, przypięte do konkretnego SKU. Problemy asynchroniczne, brak gwarancji kolejności przetwarzania oraz blokady wynikające z polityk czy kategorii zostają.

Czy mogę sprawdzić poprawkę, zanim wyślę ją na żywe konto?

Tak. Operacje putListingsItem i patchListingsItem z parametrem mode=VALIDATION_PREVIEW walidują ofertę bez zapisu danych w katalogu. Ten tryb ma osobny limit zapytań, więc nie nadaje się do masowego skanowania całego katalogu w krótkim czasie.

Czy Amazon wycofał pliki flat file?

Częściowo. Od 31 lipca 2025 r. Feeds API nie obsługuje już starych wsadów XML i flat file dla ofert, cen, stanów, relacji i zdjęć. Amazon zaznacza, że nie dotyczy to plików wgrywanych przez sprzedawcę bezpośrednio w Seller Central, więc praca w panelu jest dalej możliwa. Integracje oparte na starych typach feedów trzeba było przenieść na JSON_LISTINGS_FEED albo na Listings Items API.

Co wysłać do wsparcia Amazona, żeby dostać sensowną odpowiedź?

Z naszej praktyki: numer SKU, rynek, identyfikator zgłoszenia albo feedu, kod problemu wraz z nazwą atrybutu oraz opis tego, czego oczekiwałeś i co zastałeś. Bez kodu problemu rozmowa zwykle wraca do punktu wyjścia, czyli do prośby o ponowne wysłanie pliku.

Źródła

• Amazon SP-API, Submit a feed (statusy przetwarzania, czas przetwarzania, kolejność wsadów)
• Amazon SP-API, Manage listings issues („przyjęte" nie znaczy „zakończone", problemy asynchroniczne)
• Amazon SP-API, Listings Items API v2021-08-01 use case guide (odpowiedzi zgłoszeń, podgląd błędów)
• Amazon SP-API, Building listings management workflows (raport przetwarzania, relacje rodzic-dziecko, kolejność zgłoszeń)
• Amazon SP-API, Listings APIs FAQ (feed wywołuje Listings Items API, weryfikacja stanu oferty)
• Amazon SP-API, Feeds API rate limits oraz Listings Items API rate limits
• Amazon SP-API changelog, Deprecation of Feeds API support for XML and Flat File Listings Feeds oraz Listings migration FAQ (data 31 lipca 2025 r., brak wpływu na Seller Central)
• Amazon SP-API, Notification type values (powiadomienie FEED_PROCESSING_FINISHED)

Utknąłeś na ofertach, które nie chcą się zmienić?

Jeśli wysyłasz kolejny plik i nadal nie masz kodu błędu, problemem nie jest plik, tylko brak informacji zwrotnej. Przejrzymy sprawę na konkretnym SKU: co pokazuje stan oferty, co zwraca zgłoszenie i czy da się to domknąć bez przebudowy integracji.

Umów bezpłatną konsultację techniczną →