Zapowiedź

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

Rozwiązywanie problemów integracji

Ta strona zbiera najczęstsze problemy przy integracji z Commerce API i wskazuje, gdzie szukać przyczyny. Do każdego zgłoszenia do wsparcia dołączaj correlation_id z odpowiedzi błędu — jednoznacznie wskazuje konkretny request.

Odrzucone uwierzytelnianie (401)

Najczęstsze przyczyny błędu invalid_signature:

Objaw (`code`)	Przyczyna	Rozwiązanie
`expired_timestamp`	`X-CBA-Timestamp` poza oknem 300 s	zsynchronizuj zegar serwera (NTP); wysyłaj świeży timestamp przy każdym podpisie
`replay_nonce`	`X-CBA-Nonce` użyty ponownie w oknie	generuj unikalny nonce per request
`invalid_signature`	błędny kanoniczny string albo sekret	sprawdź kolejność elementów podpisu: metoda, ścieżka, query, timestamp, nonce, hash body

Szczegóły liczenia podpisu: Uwierzytelnianie.

Konflikty idempotency (409)

idempotency_key_reused — ten sam Idempotency-Key z innym body. Użyj nowego klucza dla nowej treści, albo powtórz identyczne body, aby otrzymać zapisaną odpowiedź.
stale_source_version — przesłano starszą wersję zasobu. Pobierz aktualny stan i podnieś source_version.

Pełny kontrakt: Idempotency, replay, source version.

Brak uprawnień (403)

insufficient_scope oznacza, że klucz nie ma wymaganego zakresu (np. orders:write). Sprawdź scopes klucza i utwórz klucz z właściwym zestawem uprawnień — patrz tabela w Uwierzytelnianiu.

Odrzucone dane (422)

validation_failed zwraca listę błędów per pole (errors). Najczęściej: brak wymaganej ceny/waluty, telefon spoza formatu E.164, brak dowodu zgody albo niekompletne pozycje zamówienia. Popraw wskazane pola — request nie wywołał żadnego efektu ubocznego.

Limity i przeciążenie (413 / 429 / 503)

payload_too_large (413) — body przekracza 2 MiB lub batch przekracza limity; podziel na mniejsze partie. Zobacz Limity.
rate_limited (429) — zbyt wiele requestów; odczekaj wartość z nagłówka Retry-After i ponów.
tenant_unavailable (503) — chwilowa niedostępność; ponów z backoffem, nie traktuj jako trwałego błędu.

Webhook nie dochodzi

Diagnoza dostarczeń wychodzących (endpoint niedostępny, wymagane HTTPS, odrzucanie adresów prywatnych, ponawianie i replay) jest opisana osobno: Webhooki: podpis, retry, replay oraz w Centrum Pomocy: Webhook nie dochodzi.