Przejdź do treści

Najczęstsze błędy Shoper API i jak je diagnozować

Integracja może zwracać poprawne odpowiedzi, a mimo to gubić produkty lub zamówienia. Najczęstsze problemy nie wynikają z jednego „błędu API”, lecz z autoryzacji, limitów, niepełnej paginacji, złego mapowania identyfikatorów, braku idempotencji i logów, które nie pokazują pełnego kontekstu operacji.

Gdzie jest błąd: od czego zacząć?

  1. AutoryzacjaProces działa lokalnie, a w cronie nie – albo nie uruchomił się wcalePierwsze sprawdzenie: kod 401 tylko w logu cron; brak wpisu partii w logu.Sekcje 03–04
  2. OdczytOdpowiedzi 429 i część katalogu, która nie trafia do sklepuPierwsze sprawdzenie: seria 429 bez przerwy w logu; oczekiwano X, pobrano Y < X.Sekcje 05–06
  3. ZapisKod 200 przy złych danych, niewłaściwy rekord i duplikaty po retryPierwsze sprawdzenie: różne SKU, ten sam rekord docelowy; dwa dokumenty, jeden identyfikator operacji.Sekcje 07–09
Kod 200 nie znaczy, że dane są poprawne

Odpowiedź może być poprawna składniowo i technicznie, a jednocześnie zapisać wartość spoza słownika, cenę w innym modelu brutto/netto albo zaktualizować niewłaściwy rekord po wcześniejszym błędnym dopasowaniu.

01

Objawy i pierwsze testy

Diagnoza idzie od objawu, przez dowód, do konkretnej zmiany. Bez dowodu w logu każda poprawka jest zgadywaniem.

Trzy najczęstsze: krótka diagnoza

odczyt

429 Too Many Requests

Odczytaj Retry-After i nagłówki limitu, zwolnij – bez natychmiastowego ponowienia.

Sekcja 05
zapis

product_id ≠ code (SKU)

ID Shopera pomylone z SKU albo ID systemu zewnętrznego – utrwalona mapa ID.

Sekcja 08
odczyt

page / limit

Pętla kończy się po pierwszej stronie – oczekiwano X, pobrano Y, unikalnych Z.

Sekcja 06
Objaw, pierwszy odczyt (dowód w logu), prawdopodobna przyczyna i działanie, z odnośnikiem do odpowiedzi
ObjawPierwszy odczyt – dowód w loguPrawdopodobna przyczynaDziałanie
Autoryzacja i uruchomienie
proces działa lokalnie, nie działa w croniekod 401 tylko w logu crontoken niewidoczny dla użytkownika cronwspólny magazyn tokenu i test pod tym samym użytkownikiem sekcja 03 →
brak jakichkolwiek zmian, brak błędówbrak wpisu partii w loguproces nie uruchomił sięalert na ciszę, nie tylko na błąd sekcja 04 →
Odczyt
integracja zwalnia i się blokujeseria 429 bez przerwy w loguponawianie natychmiast po 429kolejka, limit współbieżności, Retry-After sekcja 05 →
część katalogu nie trafia do sklepuoczekiwano X, pobrano Y < Xpętla paginacji kończy się po pierwszej stroniewarunek końca pętli + kontrola liczby unikalnych sekcja 06 →
Zapis
zaktualizowano niewłaściwy produktróżne SKU, ten sam rekord docelowymatching po nazwie zamiast po mapie IDutrwalona mapa source_id → target_id sekcja 08 →
duplikaty zamówień w ERPdwa dokumenty, jeden identyfikator operacjiretry po timeoucie bez idempotencjiklucz idempotencji i status operacji przed ponowieniem sekcja 09 →
02

Minimalna procedura diagnostyczna – wspólna dla wszystkich błędów

Kolejność ma znaczenie. Poprawianie kodu przed zebraniem dowodu zwykle kończy się drugą poprawką tego samego miejsca.

Objaw

Integracja „działa”, ale w sklepie brakuje części produktów, a niektóre zamówienia mają dwa dokumenty w ERP.

Pierwszy test

Znajdź w logu identyfikator partii i porównaj: ile rekordów oczekiwano, ile pobrano, ile było unikalnych i ile retry wykonano.

Wspólna procedura: sygnały do zebrania, zanim zmienisz kod

  1. Ustal konkretną operację i przedział czasu
  2. Znajdź identyfikator partii
  3. Sprawdź token, kod HTTP i obsługę nagłówków limitu
  4. Porównaj liczbę rekordów oczekiwanych, pobranych i unikalnych
  5. Sprawdź paginację
  6. Odtwórz jeden błędny rekord
  7. Porównaj payload przed i po mapowaniu
  8. Sprawdź mapę ID
  9. Zweryfikuj retry, duplikaty i idempotencję operacji zapisu
  10. Dopiero potem poprawiaj kod

Sekcje niżej opisują już tylko to, co jest inne dla danego błędu: co zapisać w logu, jak sprawdzić wynik i co zmienić. Gdy błędy dotyczą stanów, które rozjeżdżają się między systemami, zobacz jak synchronizować stany między ERP, sklepem i BaseLinkerem.

Wejście 1 z 3 Autoryzacja i uruchomienie

Token w procesie cyklicznym i proces, który nie zostawia śladu.

03

Autoryzacja działa lokalnie, ale wygasa w procesie cyklicznym

Zapisz w logu

log integracji · autoryzacjaprzykład
app_id: …identyfikator aplikacji bez sekretutoken: uzyskany … odświeżony …data uzyskania i odświeżenia tokenuoperacja: … kod: 401kod odpowiedzi i nazwa operacjiponowna autoryzacja: tak / nieczy wykonano ponowną autoryzację

Pierwsze wywołanie testowe często przechodzi, a automatyczny proces przestaje działać po czasie. Przyczyną może być wygasły token z /auth, błędne odświeżenie tokenu aplikacji, inne konto webapi, nieprawidłowe uprawnienia albo przechowywanie tokenu w miejscu, którego proces cron nie odczytuje.

04

Proces cron działa, ale nikt nie wie, co zrobił

Zapisz w logu partii

log partiiprzykład
partia: …identyfikator partiistart: … koniec: …czas startu i końcaoperacja: … zakres: …typ operacji i zakres danychpobrane … utworzone … zmienione … pominięte … błędne …liczba rekordów w każdym z tych stanówkody: … retry: …kody odpowiedzi i liczba retryraport: …odnośnik do raportu błędów

Log „cron uruchomiony” nie wystarcza. Dodatkowo potrzebny jest alert, gdy proces nie uruchomił się wcale. Brak błędu w logu nie oznacza sukcesu, jeżeli log nie powstał.

Wejście 2 z 3 Odczyt

Limit tempa (429) i stronicowanie list.

05

Błąd 429 nie jest sygnałem do natychmiastowego ponawiania

W logu

seria 429 bez przerwy w logu oznacza ponawianie natychmiast po odmowie; kontrola: odstępy między próbami zgodne z Retry-After.

Shoper API ogranicza tempo operacji i zwraca 429 Too Many Requests, gdy aplikacja przekroczy dostępne pasmo. Odpowiedź zawiera nagłówki limitu oraz Retry-After. Integracja powinna zwolnić i wykonać retry po wskazanym czasie, zamiast natychmiast wysłać kolejną serię żądań.

Lepszy model to kolejka, kontrolowana współbieżność, odczyt nagłówków limitu i backoff z limitem prób.

Zły wzorzec
  • setki żądań równolegle
  • odpowiedź 429 i natychmiastowe ponowienie wszystkich
  • utrzymanie blokady przy rosnącej kolejce
Dobry wzorzec
  • kolejka z limitem współbieżności
  • odczyt Retry-After
  • backoff z górnym limitem prób i osobna kolejka błędów
Tempo wyznaczają nagłówki odpowiedzi: X-Shop-Api-Limit (licznik operacji, według dokumentacji domyślnie 10) i X-Shop-Api-Bandwidth (ile operacji na sekundę schodzi z licznika, domyślnie 2). Limit liczony jest osobno dla każdej aplikacji, a wartości bywają inne niż domyślne: w sklepie sprawdzanym w październiku 2026 Bandwidth wynosił 10. Po przekroczeniu dostajesz 429 z Retry-After. Czytaj te nagłówki w kodzie zamiast zakładać stałą liczbę zapytań na sekundę. Pełny odczyt product-stocks dla ok. 22 tys. produktów trwa u nas kilkadziesiąt minut.
06

Paginacja kończy się po pierwszej stronie

Zapisz w logu i sprawdź

log odczytu listyprzykład
wyniki: … stron: …liczba wyników i liczba stronpage: … limit: …bieżąca strona lub offset, limit rekordówkoniec pętli: …warunek zakończenia pętlipowtórzenia: … luki: …powtórzenia i luki między stronamioczekiwano X, pobrano Y, unikalnych Ztrzy różne liczby: pętla czy duplikaty

Listy zasobów są stronicowane. Jeżeli integracja pobierze pierwszą stronę i uzna ją za komplet, będzie przetwarzać tylko fragment katalogu albo zamówień. W Shoper Web API listy (np. products, product-stocks, orders) stronicuje się parametrami page i limit.

Po zakończeniu zapisuj w logu: oczekiwano X, pobrano Y, unikalnych Z. Trzy różne liczby od razu pokazują, czy problem jest w pętli, czy w duplikatach.

Wejście 3 z 3 Zapis

Semantyka payloadu, mapa ID i duplikaty po ponowieniu.

07

Payload ma poprawny JSON, ale złą semantykę

Sprawdź w payloadzie, nie tylko kod HTTP

Wymagane pola i typy danych

Format daty

Ceny i waluta

ID kategorii i producenta

Status rekordu

Długość i kodowanie tekstu

Poprawny składniowo JSON może zawierać pole w złym typie, wartość spoza słownika, pusty wymagany identyfikator albo cenę w innym modelu brutto/netto. Sam status HTTP nie wystarcza do oceny sukcesu.

W logu zachowaj hash albo identyfikator payloadu, ale nie zapisuj danych osobowych zamówienia bez potrzeby.

Osobna sprawa to zapis częściowy: zależnie od zasobu Shoper przyjmuje wycinek, wymaga całego obiektu albo resetuje pola, których nie wysłano. Przypadek, w którym zapis SEO wyłączył kolekcję, opisuje poradnik Shoper API: częściowy PUT wyłączył kolekcję. Pozostałe wpisy tej serii dotyczą zapisu, który po chwili wraca do starej treści, wykluczeń z plików kampanii przez feeds_excludes i blokady IP „Zostałeś zablokowany”.

08

ID Shopera jest mylone z SKU lub ID systemu zewnętrznego

W logu

różne SKU, ten sam rekord docelowy – to dowód matchingu po nazwie zamiast po mapie ID.

API zwykle operuje własnymi identyfikatorami rekordów. Integracja musi przechowywać mapę między ID Shopera, SKU, EAN i ID ERP lub BaseLinkera. W Shoperze to product_id produktu i stock_id rekordu magazynowego, w którym siedzą pole code (SKU) i ean. Próba użycia SKU w polu oczekującym wewnętrznego ID może zwrócić błąd albo zaktualizować niewłaściwy rekord po wcześniejszym błędnym matchingu.

Utrwalona mapa ID zamiast wyszukiwania po nazwie

  1. system zewnętrznySKU, EAN, ID ERP lub BaseLinkeraklucz po stronie źródła
  2. integracjasource_id → target_idzapisana po pierwszym utworzeniu produktu
  3. Shoperproduct_id i stock_idw rekordzie magazynowym pola code (SKU) i ean

Po pierwszym utworzeniu produktu zapisz zwrócone ID. Nie wyszukuj produktu od nowa po nazwie przy każdym uruchomieniu. Zasady doboru klucza opisuje poradnik SKU czy EAN w integracjach.

09

Retry tworzy duplikaty

Przed ponowieniem

  1. Sprawdź identyfikator operacji
  2. Wyszukaj istniejący rekord po mapie ID albo stabilnym kluczu
  3. Zapisuj status started / confirmed / failed / unknown
  4. Oddziel błąd transportu od błędu biznesowego
  5. Nie ponawiaj w nieskończoność

Retry jest potrzebny przy timeoutach i chwilowych błędach, ale operacja tworząca zamówienie lub produkt musi być idempotentna. Jeżeli klient nie otrzymał odpowiedzi, nie oznacza to, że serwer niczego nie zapisał.

10

Środowisko testowe i produkcyjne korzystają z innych danych

Integracja może być poprawna technicznie, ale testowana na kilku ręcznie przygotowanych produktach. Przed produkcją użyj reprezentatywnej próbki.

Reprezentatywna próbka przed produkcją

Produkty proste i wariantowe

Brakujące EAN

Znaki polskie i wiele zdjęć

Nieistniejąca kategoria

Cena promocyjna i zerowy stan

Rekord już istniejący

FAQ: diagnostyka Shoper API

Aplikacja przekroczyła dostępne tempo operacji. Należy respektować nagłówek Retry-After, ograniczyć współbieżność i zastosować kontrolowany backoff. Natychmiastowe ponowienie wszystkich żądań utrzymuje blokadę i powiększa kolejkę.
Najczęściej nie obsługuje wszystkich stron wyników albo błędnie kończy pętlę paginacji. Warto zapisywać w logu trzy liczby: ile rekordów oczekiwano, ile pobrano i ile było unikalnych.
Nie. Serwer mógł zapisać dane, zanim klient utracił odpowiedź. Przed ponowieniem trzeba sprawdzić status operacji albo istnienie rekordu, inaczej retry utworzy duplikat.
Tylko z kontrolą danych osobowych i okresu przechowywania. Zwykle wystarczą identyfikatory, status, kod błędu i zanonimizowany fragment techniczny. Pełnego tokenu autoryzacji nie zapisuje się nigdy.

Integracja z Shoperem gubi dane? Zbudujemy proces, w którym każdy zapis jest sprawdzony

Projektujemy procesy na Shoper API z logiem partii, mapą identyfikatorów, ponawianiem bez duplikatów i odczytem po zapisie. Wiesz, co zmienił każdy przebieg, a błąd widać w raporcie, zanim zauważy go klient.

Podobna realizacja20 847 opisów w 96 h działania automatyzacjiCMP Polska · Shoper