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.
Integracja „działa”, ale w sklepie brakuje części produktów, a niektóre zamówienia mają dwa dokumenty w ERP.
Znajdź w logu identyfikator partii i porównaj: ile rekordów oczekiwano, ile pobrano, ile było unikalnych i ile retry wykonano.
Autoryzacja działa lokalnie, ale wygasa w procesie cyklicznym
Pierwsze wywołanie testowe często przechodzi, a automatyczny proces przestaje działać po czasie. Przyczyną może być wygasły token, błędne odświeżenie, inny klient OAuth, nieprawidłowe uprawnienia albo przechowywanie tokenu w miejscu, którego proces cron nie odczytuje.
- identyfikator aplikacji bez sekretu
- data uzyskania i odświeżenia tokenu
- kod odpowiedzi i nazwa operacji
- informacja, czy wykonano ponowną autoryzację
Błąd 429 nie jest sygnałem do natychmiastowego ponawiania
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, natychmiastowe ponowienie wszystkich — i 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.
Paginacja kończy się po pierwszej stronie
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ń.
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.
- liczba wyników i liczba stron
- bieżąca strona lub offset
- limit rekordów
- warunek zakończenia pętli
- powtórzenia i luki między stronami
Payload ma poprawny JSON, ale złą semantykę
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.
- wymagane pola i typy danych
- format daty
- ceny i waluta
- ID kategorii i producenta
- status rekordu
- długość i kodowanie tekstu
ID Shopera jest mylone z SKU lub ID systemu zewnętrznego
API zwykle operuje własnymi identyfikatorami rekordów. Integracja musi przechowywać mapę między ID Shopera, SKU, EAN i ID ERP lub BaseLinkera. 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.
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
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ł.
- 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ść
Proces cron działa, ale nikt nie wie, co zrobił
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ł.
- czas startu i końca
- typ operacji i zakres danych
- liczba pobranych, utworzonych, zmienionych, pominiętych i błędnych rekordów
- kody odpowiedzi i liczba retry
- identyfikator partii
- odnośnik do raportu błędów
Od objawu do działania
Diagnoza idzie od objawu, przez dowód, do konkretnej zmiany. Bez dowodu w logu każda poprawka jest zgadywaniem.
| Objaw | Prawdopodobna przyczyna | Dowód | Działanie |
|---|---|---|---|
| proces działa lokalnie, nie działa w cronie | token niewidoczny dla użytkownika cron | kod 401 tylko w logu cron | wspólny magazyn tokenu i test pod tym samym użytkownikiem |
| część katalogu nie trafia do sklepu | pętla paginacji kończy się po pierwszej stronie | oczekiwano X, pobrano Y < X | warunek końca pętli + kontrola liczby unikalnych |
| integracja zwalnia i się blokuje | ponawianie natychmiast po 429 | seria 429 bez przerwy w logu | kolejka, limit współbieżności, Retry-After |
| duplikaty zamówień w ERP | retry po timeoucie bez idempotencji | dwa dokumenty, jeden identyfikator operacji | klucz idempotencji i status operacji przed ponowieniem |
| zaktualizowano niewłaściwy produkt | matching po nazwie zamiast po mapie ID | różne SKU, ten sam rekord docelowy | utrwalona mapa source_id → target_id |
| brak jakichkolwiek zmian, brak błędów | proces nie uruchomił się | brak wpisu partii w logu | alert na ciszę, nie tylko na błąd |
Ś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.
- produkty proste i wariantowe
- brakujące EAN
- znaki polskie i wiele zdjęć
- nieistniejąca kategoria
- cena promocyjna i zerowy stan
- rekord już istniejący
Minimalna procedura diagnostyczna
Kolejność ma znaczenie. Poprawianie kodu przed zebraniem dowodu zwykle kończy się drugą poprawką tego samego miejsca.
- ustal konkretną operację i przedział czasu
- znajdź identyfikator partii
- sprawdź token i kod HTTP
- porównaj liczbę oczekiwanych oraz pobranych rekordów
- sprawdź paginację
- odtwórz jeden błędny rekord
- porównaj payload przed i po mapowaniu
- sprawdź mapę ID
- zweryfikuj retry i duplikaty
- dopiero potem poprawiaj kod