Zapowiedź

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

Idempotency, replay, source version

Mutacje (POST, PATCH, DELETE) obsługują idempotency, dzięki czemu możesz bezpiecznie ponawiać request po błędzie sieci, nie ryzykując duplikatu. Do każdej mutacji dołączasz nagłówek Idempotency-Key — najlepiej losowy UUID v4.

Jak działa Idempotency-Key

Zakres (scope) klucza idempotencji jest wyznaczany przez cztery elementy:

integrację (Twój klucz API),
metodę HTTP,
kanoniczną ścieżkę,
wartość Idempotency-Key.

Ta sama kombinacja identyfikuje jedną operację. Serwer zapisuje odpowiedź pierwszego udanego wywołania i zwraca ją przy powtórzeniach.

Scenariusz	Zachowanie
Ten sam klucz + ten sam hash body	Zwracana identyczna, zapisana odpowiedź (replay)
Ten sam klucz + inny hash body	`409 idempotency_key_reused` — konflikt
Nowy klucz	Wykonanie nowej operacji

Wniosek praktyczny: ponawiając request, wyślij dokładnie to samo body z tym samym Idempotency-Key. Jeśli zmienisz zawartość, ale zostawisz stary klucz, otrzymasz konflikt zamiast nowego zapisu.

Source version i konflikt stale

Dla zasobów aktualizowanych wielokrotnie (np. produkt, klient) obowiązuje source_version — monotoniczny licznik wersji po stronie źródła (Twojego sklepu). Przy zapisie porównujemy przesłaną wersję z ostatnią znaną:

Relacja wersji	Zachowanie
Wersja nowsza niż zapisana	Aktualizacja przyjęta
Wersja starsza niż zapisana	`409 stale_source_version` — odrzucenie
Wersja identyczna	Replay — zwracany dotychczasowy stan bez zmian

Dzięki temu spóźniony lub przetasowany request nie nadpisze świeższych danych. Ustaw source_version na wartość rosnącą przy każdej zmianie w sklepie (np. znacznik czasu w milisekundach lub własny licznik zdarzeń).

Retencja zapisanej odpowiedzi

Zapisana odpowiedź powiązana z Idempotency-Key jest przechowywana przez 7 dni. Ponowienie w tym oknie zwróci identyczny wynik. Po upływie retencji ten sam klucz może zostać potraktowany jak nowa operacja — dlatego nie polegaj na idempotency dla powtórzeń oddalonych o więcej niż tydzień.

Wzorce bezpiecznego ponawiania

Generuj klucz raz na operację — zapisz Idempotency-Key po swojej stronie zanim wyślesz request; przy retry użyj tej samej wartości.
Ponawiaj z backoffem — dla 429 rate_limited i 503 tenant_unavailable odczekaj (patrz Retry-After) i powtórz z tym samym kluczem.
Nie zmieniaj body przy retry — zmiana treści przy tym samym kluczu daje 409 idempotency_key_reused.
Reaguj na 409 świadomie — idempotency_key_reused oznacza rozjazd body, a stale_source_version oznacza, że masz nieaktualną wersję zasobu; pobierz aktualny stan zanim spróbujesz ponownie.

Pełne znaczenie kodów opisuje sekcja Błędy. Sposób podpisywania requestów znajdziesz w sekcji Uwierzytelnianie.