Masowe wystawianie ofert z pliku CSV i API - jak uniknąć błędów

Masowe wystawianie ofert z pliku CSV - typowe pułapki

Plik CSV wygląda prosto, ale ma kilka miejsc, w których import się sypie. Pierwsze to kodowanie znaków. Dokumentacja importera produktów WooCommerce zaleca zapisywanie pliku jako CSV w UTF-8 i sprawdzenie go po zapisie, bo arkusze kalkulacyjne potrafią zmienić kodowanie i formatowanie (stan na luty 2026 - sprawdź aktualną dokumentację WooCommerce). W polskich danych źle zakodowany plik kończy się krzaczkami zamiast liter z ogonkami w tytułach.

Drugie to separator i liczby. Arkusz z polskimi ustawieniami regionalnymi może zapisać plik ze średnikiem jako separatorem i przecinkiem w cenach, podczas gdy importer oczekuje przecinka jako separatora i kropki w liczbach. Trzecie to aktualizacja istniejących produktów. Importer WooCommerce przy opcji aktualizacji dopasowuje wiersze po ID lub SKU, a wiersz z nieznanym ID jest pomijany - dlatego brak lub literówka w SKU oznacza, że produkt się nie zaktualizuje albo powstanie duplikat.

Czwarta pułapka to rozmiar pliku. Dokumentacja WooCommerce wskazuje, że duże importy zależą od pamięci serwera, limitów wysyłania i czasu przetwarzania, i zaleca dzielenie dużego pliku na mniejsze partie. To samo dotyczy innych platform. Jak różnią się gotowe moduły importu i integracje dedykowane na przykładzie PrestaShop, opisujemy we wpisie integracja PrestaShop z marketplace - moduły gotowe czy dedykowane.

Masowe wystawianie ofert przez API na przykładzie Allegro

REST API Allegro pozwala wystawić ofertę powiązaną z produktem jednym zapytaniem POST /sale/product-offers. Według poradnika Allegro odpowiedź 201 oznacza, że oferta została przetworzona od razu, a odpowiedź 202 - że zapytanie przyjęto do dalszej, asynchronicznej weryfikacji, co nie gwarantuje jeszcze wystawienia. W nagłówku location przychodzi adres operacji, a jej wynik sprawdza się zasobem GET /sale/product-offers/{offerId}/operations/{operationId}. Stan na luty 2026 - sprawdź aktualną dokumentację Allegro.

To kluczowa różnica wobec importu z pliku. Program nie może uznać oferty za wystawioną tylko dlatego, że wysłanie się powiodło. Musi zapisać identyfikator operacji, odczekać czas wskazany w nagłówku retry-after i sprawdzić wynik. Błędy walidacji synchronicznej Allegro zwraca z kodem 422 i tablicą errors, w której są m.in. pola code, message, path i userMessage - warto zapisywać je w całości przy ofercie.

Do zmian w wielu istniejących ofertach Allegro udostępnia komendy grupowe, np. zmianę cen przez PUT /sale/offer-price-change-commands/{commandId} - według poradnika do 1000 ofert w jednym wywołaniu - oraz zmianę ilości przez offer-quantity-change-commands. Wynik sprawdza się w zasobie /tasks danej komendy, który pokazuje status dla każdej oferty (stan na luty 2026 - sprawdź aktualną dokumentację Allegro).

[#przyklad] Uproszczona logika kolejki dla jednej oferty: wyślij POST /sale/product-offers; jeśli 201 - zapisz offerId i status; jeśli 202 - zapisz adres z nagłówka location i sprawdź go po czasie z retry-after; jeśli 422 - zapisz tablicę errors i przenieś ofertę do poprawek; jeśli 429 - odczekaj i ponów później, bez zwiększania tempa.

Kolejka wystawień i limity API - jak nie zablokować integracji

Platformy ograniczają liczbę zapytań w czasie. Dokumentacja Allegro opisuje główny limit 9000 zapytań na minutę na Client ID, po którego przekroczeniu API zwraca błąd 429 i blokuje Client ID na minutę. Niektóre zasoby mają dodatkowe, niższe limity, a zbyt wiele równoległych zapytań w imieniu tego samego użytkownika także kończy się błędem 429 (stan na luty 2026 - sprawdź aktualną dokumentację Allegro). Allegro wprowadziło też limit liczby produktów, które sprzedający może dodać do katalogu w miesiącu - przy dużym imporcie nowych produktów trzeba to uwzględnić w planie.

Dlatego masowe wystawianie przez API powinno działać jako kolejka, a nie pętla, która wysyła wszystko naraz. Dobra kolejka:

1. Zapisuje każdą ofertę jako zadanie ze statusem: oczekuje, wysłana, w weryfikacji, wystawiona, odrzucona.

2. Ogranicza tempo i równoległość - kilka zapytań naraz zamiast setek.

3. Ponawia z opóźnieniem zapytania zakończone błędem 429 lub błędem serwera, z rosnącym odstępem.

4. Nie ponawia błędów walidacji - oferta z błędem 422 wymaga poprawy danych, nie kolejnej próby.

5. Jest idempotentna - po restarcie nie tworzy drugiej oferty dla tego samego SKU, bo sprawdza zapisany identyfikator.

Postęp importu warto mierzyć jednym prostym wskaźnikiem, który pokazuje, ile ofert wymaga ręcznej pracy:

[#chart:wpr45c]

Jak obsłużyć odrzucone oferty przy masowym wystawianiu

Odrzucone oferty nie powinny znikać w logach. Każda trafia do listy poprawek z pełnym komunikatem błędu, SKU i datą próby. Po poprawie danych w źródle oferta wraca do kolejki jako nowe zadanie. Najczęstsze przyczyny i poprawki wyglądają tak:

[#chart:wpr45b]

Po każdej partii warto przejrzeć statystykę błędów. Jeśli jeden komunikat powtarza się w setkach ofert, problem leży w danych źródłowych lub mapowaniu pól, a nie w pojedynczych produktach - poprawa reguły w skrypcie rozwiązuje go hurtowo.

Przydatny jest też prosty raport końcowy dla osoby, która zleciła import: ile ofert wysłano, ile wystawiono, ile czeka na weryfikację, ile odrzucono i z jakich powodów. Taki raport zamyka partię i pozwala ocenić, czy kolejna może pójść w większej skali. Oferty, które pozostają w weryfikacji dłużej niż zwykle, warto sprawdzić ponownie po kilku godzinach, zamiast od razu wysyłać je drugi raz. Przy cyklicznych importach dobrze zachować historię wszystkich partii, żeby po kilku tygodniach widzieć, czy odsetek odrzuceń maleje i czy poprawki w danych źródłowych przynoszą efekt.

Masowe wystawianie ofert w wielu kanałach naraz

Sprzedawcy, którzy wystawiają ten sam katalog na Allegro, w sklepie i na innych marketplace, mają dodatkowe wyzwanie: każda platforma ma inne kategorie, inne wymagane parametry i inne limity. Wysyłanie tego samego pliku wszędzie kończy się odrzuceniami. Lepiej utrzymywać jedną bazę produktów z danymi wspólnymi, a dla każdego kanału osobne mapowanie kategorii i parametrów oraz osobną kolejkę wystawień. Wtedy błąd w jednym kanale nie blokuje pozostałych, a poprawka mapowania działa dla wszystkich przyszłych ofert.

Drugą sprawą jest kolejność. Najpierw warto wystawić produkty w kanale, w którym najłatwiej sprawdzić poprawność danych, a potem przenosić je dalej. Przy dużych katalogach dobrze sprawdza się też podział na fale według kategorii: najpierw kategoria z najprostszymi parametrami, potem trudniejsze. Każda fala daje informację zwrotną, która poprawia walidację przed kolejną. Pomaga też zapisywanie w bazie, w których kanałach dany SKU jest już wystawiony i z jakim identyfikatorem oferty, bo bez tego łatwo o duplikaty i oferty, których nikt nie aktualizuje. Gdy po wystawieniu mają się automatycznie aktualizować ceny i stany, ta sama tabela powiązań SKU z ofertami staje się podstawą synchronizacji.

[#checklista] Przed masowym wystawieniem: walidacja danych bez błędów krytycznych; plik w UTF-8 z właściwym separatorem; unikalne SKU i poprawne EAN; test na partii kilkunastu ofert; kolejka z limitem tempa i obsługą 429; zapis identyfikatorów ofert i operacji; lista odrzuconych z komunikatami; kontrola wystawionych ofert w panelu po zakończeniu.

Jak Vinson pomaga w masowym wystawianiu ofert

Zapewniamy wsparcie programistyczne dla sklepów i sprzedawców: integracje, automatyzacje, poprawki i rozwój sklepów oraz narzędzi. Przy masowym wystawianiu ofert piszemy walidatory danych, przygotowujemy eksporty CSV zgodne z wymaganiami platform, budujemy kolejki wystawień przez API z obsługą limitów i raportem odrzuconych ofert oraz łączymy je z ERP lub sklepem. Jeśli Twoje narzędzie już działa, ale gubi oferty albo tworzy duplikaty, znajdziemy przyczynę i ją usuniemy. Szczegóły znajdziesz na stronie Wsparcie programistyczne dla e-commerce.

Najczęściej zadawane pytania

Jak masowo wystawić oferty z pliku CSV?

Przygotuj plik w UTF-8 z kolumnami wymaganymi przez platformę, sprawdź identyfikatory, ceny i parametry, a potem zaimportuj go narzędziem platformy lub integratora. Zacznij od małej partii testowej i sprawdź wynik w panelu. Dopiero gdy test przejdzie bez błędów, importuj resztę w mniejszych plikach.

Dlaczego import CSV pomija część produktów?

Najczęściej dlatego, że wiersze mają brakujące lub błędne SKU albo ID, źle zakodowane znaki, niewłaściwy separator lub liczby z przecinkiem. Importer może też pominąć wiersze, które nie pasują do istniejących produktów przy aktualizacji. Raport importu i porównanie liczby wierszy z liczbą produktów pokażą, które pozycje zostały pominięte.

Co oznacza odpowiedź 202 przy wystawianiu oferty przez API Allegro?

Odpowiedź 202 oznacza, że Allegro przyjęło zapytanie do dalszej weryfikacji, ale oferta nie jest jeszcze na pewno wystawiona. Wynik trzeba sprawdzić pod adresem operacji podanym w nagłówku location. Dopiero status operacji pokazuje, czy oferta przeszła weryfikację, czy ma błędy.

Jak uniknąć błędu 429 przy masowym wystawianiu?

Wysyłaj oferty przez kolejkę z ograniczonym tempem i niewielką liczbą równoległych zapytań, a po błędzie 429 odczekaj przed ponowieniem. Sprawdź w dokumentacji platformy limity główne i dodatkowe dla używanych zasobów. Nie ponawiaj natychmiast całej partii, bo to wydłuża blokadę.

CSV czy API - co wybrać do wystawiania ofert?

CSV wystarczy przy jednorazowych importach i niewielkim katalogu, bo nie wymaga programowania. API jest lepsze przy dużych katalogach, częstych zmianach i sprzedaży w wielu kanałach, bo daje wynik dla każdej oferty i pozwala zautomatyzować poprawki. Wiele firm zaczyna od CSV i przechodzi na API, gdy liczba ofert rośnie.

Masowe wystawianie ofert przestaje być loterią, gdy dane są walidowane, oferty idą przez kolejkę, a odrzucenia wracają do poprawki. Jeśli potrzebujesz takiego procesu lub narzędzia, sprawdź wsparcie programistyczne Vinson. Więcej o łączeniu sklepu z Allegro przeczytasz we wpisie integracja WooCommerce z Allegro - wtyczka czy własne rozwiązanie.