Stronicowanie, limity i kody odpowiedzi

Zasady z tego artykułu dotyczą wszystkich endpointów API zewnętrznego (/external/v1/).

Stronicowanie

Bez parametrów lista jest zwracana w całości jako tablica JSON.
Z parametrami limit i offset odpowiedź jest stroną w kopercie:

GET https://{amper_ws}/external/v1/products/?limit=500&offset=0&ordering=id

{
  "count": 1817,
  "next": "https://{amper_ws}/external/v1/products/?limit=500&offset=500&ordering=id",
  "previous": null,
  "results": [ ... ]
}

Pole	Opis
`count`	liczba wszystkich obiektów na liście (po filtrach)
`next`	adres następnej strony; `null` na ostatniej stronie
`previous`	adres poprzedniej strony; `null` na pierwszej stronie
`results`	obiekty z tej strony

Przy dużym katalogu pobieraj dane stronami, aż next będzie równe null. Zalecany rozmiar strony: 200–500 dla produktów, zdjęć, przypisań i stanów, 50 dla promocji (mają rozbudowaną strukturę). Największy rozmiar strony to 100 000.

Lista produktów nie ma stałej kolejności – przy pobieraniu stronami dodaj ordering=id, żeby żaden produkt nie wypadł między stronami. Promocje są zawsze uporządkowane (domyślnie od najnowszej).

Pamiętaj o kluczu API w adresie, jeśli go używasz: ?api_key={api_key}&limit=500&offset=0. Adresy w next i previous zawierają wszystkie parametry pierwszego zapytania, także klucz.

Limity zapytań

Najwyżej 3 jednoczesne zapytania na jednego klienta API (klucz albo login). Kolejne dostają odpowiedź 429 Too Many Requests z nagłówkiem Retry-After: 1 – odczekaj wskazaną liczbę sekund i ponów zapytanie. Strony pobieraj po kolei albo najwyżej dwie, trzy naraz.
Około 800 zapytań na minutę z jednego adresu IP. Po przekroczeniu odpowiedź to również 429 z nagłówkiem Retry-After.
Limit dotyczy liczby zapytań, które trwają w tej samej chwili – nie ich tempa. Integracja może pobierać strony jedna po drugiej tak szybko, jak pozwala serwer.
Zapytanie o pełną listę bez stronicowania trwa długo (przy dużym katalogu kilkanaście sekund i więcej) i przez cały ten czas zajmuje jedno z 3 miejsc. Ustaw w kliencie HTTP limit czasu co najmniej 120 sekund.

Jak często odświeżać dane

Dane	Zalecana częstotliwość
kategorie, przypisania do kategorii, zdjęcia, opisy produktów	raz dziennie albo co kilka godzin
ceny (`products`) i stany (`stocks`)	co 15–60 minut
promocje	co 1–4 godziny; zmiany z panelu AMPER widać w API najpóźniej po około 5 minutach
rodzaje wysyłki	raz dziennie

Nie pobieraj całego katalogu co kilka minut. Przy częstym odświeżaniu cen możesz zawęzić listę produktów filtrem ids do tych, które masz w swoim sklepie – patrz Produkty i zdjęcia.

Kody odpowiedzi

Kod	Znaczenie	Co zrobić
`200 OK`	poprawna odpowiedź	–
`201 Created`	żądanie `create-order` przyjęte – sprawdź `order_id`	–
`400 Bad Request`	błędne dane w żądaniu (np. brak klienta w `create-order`)	popraw żądanie – opis błędu jest w polu `error` albo `detail`
`401 Unauthorized`	brak danych dostępu, klucz wygasł lub jest wyłączony, token wygasł	odśwież token albo poproś o nowy klucz
`403 Forbidden`	konto nie ma uprawnień do tej operacji (np. zamówienie z kluczem API, zamówienie dla cudzego klienta, token z `/external/v1/auth/` użyty poza API zewnętrznym)	sprawdź dane dostępu i uprawnienia konta
`404 Not Found`	nie ma obiektu o podanym `id` albo nie jest dostępny dla klienta	–
`422 Unprocessable Entity`	instalacja nie jest skonfigurowana do zamówień producenckich (`create-order`)	wyślij zamówienie ponownie później
`429 Too Many Requests`	przekroczony limit jednoczesnych zapytań, zapytań na minutę albo nieudanych logowań	odczekaj czas z nagłówka `Retry-After` i ponów
`500`, `502`, `503`, `504`	błąd lub przeciążenie serwera	ponów po kilku–kilkudziesięciu sekundach, z rosnącą przerwą

Błędy mają postać obiektu JSON z opisem w polu detail (albo error w create-order), np.:

{ "detail": "Request was throttled. Expected available in 1 second." }

Treść komunikatów może się zmieniać – w kodzie sprawdzaj kod odpowiedzi, a komunikat zapisuj w logu.