Przejdź do głównej treści

Operacje zapisu, które zmieniają istniejący zasób

Nie jest tu potrzebny żaden nagłówek. Tam, gdzie powtórzenie wcześniej zwracało błąd, teraz zwraca bieżący stan: Powtórzenie niczego nie zapisuje, a odpowiedź zawiera nagłówek Idempotent-Replayed: true — dzięki niemu odróżnisz „anulowano teraz” od „było już anulowane”. Trzy wyjątki zwracają zamiast tego 409:
  • Aktywacja z innym activated_at. Czas pobrania trafia na raport laboratoryjny, więc ponowna próba nie może go po cichu nadpisać.
  • Anulowanie już anulowanej wizyty z innym cancellation_reason. Ten sam powód: zapisana przyczyna mogła zostać w międzyczasie poprawiona i ponowna próba nie może jej nadpisać. Wyślij ponownie zapisaną przyczynę albo ją pomiń.
  • Anulowanie po punkcie bez powrotu — potwierdzone pobranie krwi, odebrana przesyłka, wysłany lub aktywowany zestaw.
Trzy endpointy celowo nie są bezpieczne do ponawiania:
  • Potwierdź pobranie krwi — drugie wywołanie zwraca 409.
  • Wyślij wyniki e-mailem (POST /v1/appointments/{id}/results/email) oraz Wyślij wyniki e-mailem (POST /v1/home-kit-orders/{id}/results/email) — każde wywołanie wysyła jednego e-maila. Ponowna próba po przekroczeniu czasu oczekiwania lub błędzie 5xx może wysłać klientowi duplikat.

Operacje zapisu, które coś tworzą

Pięć endpointów akceptuje opcjonalny nagłówek Idempotency-Key o długości maksymalnie 255 znaków: Jeden klucz, cztery próby, jedno zamówienie — to, co otrzymasz, zależy od momentu ponowienia i tego, czy treść żądania jest taka sama: Diagram sekwencji: duplikat wysłany 350 ms po pierwszym żądaniu otrzymuje odpowiedź 409, gdy to żądanie wciąż trwa, pierwsze zwraca 201, późniejsze ponowienie z tym samym kluczem zwraca to samo zamówienie oznaczone Idempotent-Replayed, a ten sam klucz ze zmienioną treścią żądania zwraca 409. Diagram sekwencji: duplikat wysłany 350 ms po pierwszym żądaniu otrzymuje odpowiedź 409, gdy to żądanie wciąż trwa, pierwsze zwraca 201, późniejsze ponowienie z tym samym kluczem zwraca to samo zamówienie oznaczone Idempotent-Replayed, a ten sam klucz ze zmienioną treścią żądania zwraca 409. Klucze są przypisane do twojego klucza API oraz do endpointu, więc nigdy nie kolidują z kluczami innego partnera ani z tym samym kluczem użytym gdzie indziej.
  • Ten sam klucz, ta sama treść → przez 24 godziny otrzymujesz pierwotną odpowiedź oznaczoną Idempotent-Replayed: true. Kolejność pól i białe znaki nie mają znaczenia.
  • Ten sam klucz, inna treść → 409.
  • Pusty Idempotency-Key → 400 zamiast zignorowania.

Kiedy klucz jest zwalniany

Tworzenie nie jest atomowe — błąd 5xx nie oznacza, że nic nie zostało zapisane.
  • Żądanie nie powiodło się, zanim cokolwiek utworzono → klucz jest zwalniany, więc możesz ponowić próbę z tym samym kluczem.
  • Żądanie nie powiodło się po tym, jak coś utworzono, lub w ogóle nie zwróciło odpowiedzi → klucz pozostaje zajęty, a ponowne próby zwracają 409. Pobierz zasób, aby sprawdzić, czy istnieje, a jeśli nie, użyj nowego klucza.
Powtórzenie zwraca treść odpowiedzi zapisaną w momencie utworzenia zasobu — migawkę, a nie bieżący odczyt. Jeśli zasób od tego czasu się zmienił, pobierz go bezpośrednio.

Niektóre operacje tworzenia mają też klucz naturalny

Dwa endpointy odrzucają duplikaty samodzielnie, niezależnie od nagłówka:
  • Utwórz wizytę pozwala na jedną wizytę dla danego profilu, lokalizacji i terminu. Powtórzenie zwraca 409 z istniejącym appointment_id.
  • Utwórz profil zwraca 409, gdy dla email istnieje już profil. Jeśli pominiesz email, dla każdego żądania generowana jest unikalna wartość zastępcza, więc powtórzenia faktycznie tworzą osobne profile.
Gdy zadziałają oba mechanizmy, otrzymasz 409 z klucza naturalnego i tylko ta odpowiedź zawiera dodatkowe pole (appointment_id lub wyróżnik error_name) — 409 z idempotentności zawiera wyłącznie error, więc odczytuj te pola defensywnie.