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.
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
| Objaw | Pierwszy odczyt – dowód w logu | Prawdopodobna przyczyna | Działanie |
|---|---|---|---|
| Autoryzacja i uruchomienie | |||
| proces działa lokalnie, nie działa w cronie | kod 401 tylko w logu cron | token niewidoczny dla użytkownika cron | wspólny magazyn tokenu i test pod tym samym użytkownikiem sekcja 03 → |
| brak jakichkolwiek zmian, brak błędów | brak wpisu partii w logu | proces nie uruchomił się | alert na ciszę, nie tylko na błąd sekcja 04 → |
| Odczyt | |||
| integracja zwalnia i się blokuje | seria 429 bez przerwy w logu | ponawianie natychmiast po 429 | kolejka, limit współbieżności, Retry-After sekcja 05 → |
| część katalogu nie trafia do sklepu | oczekiwano X, pobrano Y < X | pętla paginacji kończy się po pierwszej stronie | warunek końca pętli + kontrola liczby unikalnych sekcja 06 → |
| Zapis | |||
| zaktualizowano niewłaściwy produkt | różne SKU, ten sam rekord docelowy | matching po nazwie zamiast po mapie ID | utrwalona mapa source_id → target_id sekcja 08 → |
| duplikaty zamówień w ERP | dwa dokumenty, jeden identyfikator operacji | retry po timeoucie bez idempotencji | klucz idempotencji i status operacji przed ponowieniem sekcja 09 → |
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
- Ustal konkretną operację i przedział czasu
- Znajdź identyfikator partii
- Sprawdź token, kod HTTP i obsługę nagłówków limitu
- Porównaj liczbę rekordów oczekiwanych, pobranych i unikalnych
- Sprawdź paginację
- Odtwórz jeden błędny rekord
- Porównaj payload przed i po mapowaniu
- Sprawdź mapę ID
- Zweryfikuj retry, duplikaty i idempotencję operacji zapisu
- 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.
Autoryzacja działa lokalnie, ale wygasa w procesie cyklicznym
Zapisz w logu
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.
Proces cron działa, ale nikt nie wie, co zrobił
Zapisz w logu partii
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ówLog „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.
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.
- setki żądań równolegle
- odpowiedź 429 i natychmiastowe ponowienie wszystkich
- utrzymanie blokady przy rosnącej kolejce
- kolejka z limitem współbieżności
- odczyt
Retry-After - backoff z górnym limitem prób i osobna kolejka błędów
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.Paginacja kończy się po pierwszej stronie
Zapisz w logu i sprawdź
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 duplikatyListy 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.
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”.
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
- SKU, EAN, ID ERP lub BaseLinkeraklucz po stronie źródła
source_id → target_idzapisana po pierwszym utworzeniu produktuproduct_idistock_idw rekordzie magazynowym polacode(SKU) iean
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.
Retry tworzy duplikaty
Przed ponowieniem
- Sprawdź identyfikator operacji
- Wyszukaj istniejący rekord po mapie ID albo stabilnym kluczu
- Zapisuj status
started / confirmed / failed / unknown - Oddziel błąd transportu od błędu biznesowego
- 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ł.
Ś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