Zapowiedź

Dokumentacja poglądowa. Interfejs jest w trakcie udostępniania — przykłady mają charakter zapowiedzi, a finalne wartości potwierdzimy przy starcie.

Paginacja, limity, rate limits

Ta sekcja opisuje, jak stronicować listy, jakie są maksymalne rozmiary payloadów oraz jak reagować na rate limiting. Trzymanie się limitów pozwala uniknąć błędów 413 i 429.

Cursor pagination

Listy zwracają wyniki stronami z opaque cursor pagination. Kursor to nieprzezroczysty token — nie parsuj go ani nie buduj samodzielnie; użyj wartości zwróconej przez API, aby pobrać kolejną stronę.

limit — liczba elementów na stronie; domyślnie 50, maksymalnie 200.
cursor — token kolejnej strony; brak w odpowiedzi oznacza koniec listy.

# pierwsza strona
curl "https://api.callbotagent.ai/api/v1/commerce/orders?limit=50" \
  -H "X-CBA-Key-Id: cba_test_••••••••"
# kolejna strona — użyj kursora z pola next_cursor poprzedniej odpowiedzi
curl "https://api.callbotagent.ai/api/v1/commerce/orders?limit=50&cursor=eyJvIjoxMjN9" \
  -H "X-CBA-Key-Id: cba_test_••••••••"

let cursor = null;
do {
  const url = new URL(`${baseUrl}/api/v1/commerce/orders`);
  url.searchParams.set('limit', '50');
  if (cursor) url.searchParams.set('cursor', cursor);
  const page = await (await fetch(url, { headers: signedHeaders(keyId) })).json();
  cursor = page.next_cursor; // brak → koniec listy
} while (cursor);

$cursor = null;
do {
    $query = ['limit' => 50] + ($cursor ? ['cursor' => $cursor] : []);
    $page = json_decode((string) $client->get('/api/v1/commerce/orders', ['query' => $query])->getBody(), true);
    $cursor = $page['next_cursor'] ?? null;
} while ($cursor);

Limity payloadów i zasobów

Limit	Wartość
Rozmiar body requestu	2 MiB
Produkty w jednym batchu	500 (do 100 wariantów na produkt)
Pozycje w jednym zamówieniu	250
Warunki w jednej regule	100
Strona listy (`limit`)	domyślnie 50, maks. 200
Eksport synchroniczny	do 10 000 rekordów
Rozmiar payloadu webhooka	1 MiB
Próby dostarczenia webhooka	8 w ciągu 24 h
Timeout serwera (przetwarzanie)	10 s
Callback partnera	5 s na połączenie / 15 s łącznie

Przekroczenie rozmiaru body lub batcha zwraca 413 payload_too_large — dziel duże importy na mniejsze partie. Dla eksportów powyżej 10 000 rekordów użyj stronicowania zamiast eksportu synchronicznego.

Rate limiting i Retry-After

Po przekroczeniu limitu żądań API zwraca 429 rate_limited z nagłówkiem Retry-After (liczba sekund do ponowienia). Ten sam nagłówek towarzyszy odpowiedzi 503 tenant_unavailable.

Odczekaj czas z Retry-After, zanim ponowisz request.
Stosuj exponential backoff z jitterem, gdy Retry-After nie jest podany.
Przy mutacjach ponawiaj z tym samym Idempotency-Key — patrz Idempotency.
Znaczenie kodów opisuje sekcja Błędy.