Środowiska, limity i wersjonowanie

Sandbox i produkcja, jeden Base URL

Base URL: https://api.dubaitrip.com/v1. Sandbox i produkcja go współdzielą; środowisko wybiera klucz, którym podpisujesz. Klucz dt_sbx_ działa na środowiskach testowych naszych dostawców — wyszukiwania, wyceny, weryfikacje stawek, zamówienia, rezerwacje, wystawianie biletów i anulowania działają od początku do końca na ofercie testowej, bez prawdziwego biletu czy vouchera i bez żadnych obciążeń. Klucz dt_live_, wydawany po weryfikacji produkcyjnej, trafia do rzeczywistej oferty i jest rozliczany z Twojego depozytu.

Rezerwacje z sandboksa i produkcyjne są w portalu dewelopera rozdzielone (każda rezerwacja jest oznaczona), a zakresy, limity i reguły IP są zarządzane osobno dla każdego środowiska.

Limity żądań i limity dzienne

Każdy klucz jest ograniczany przez token bucket (stała liczba żądań na sekundę plus seria) i dzienny limit. Domyślnie w sandboksie: 2 żądania/sekundę, seria 5, 2000 żądań/dzień. Limity produkcyjne są ustalane indywidualnie dla każdego konta. Przekroczenie bucketu zwraca 429 api_rate_limited z nagłówkiem Retry-After; wyczerpanie limitu dziennego zwraca 429 api_quota_exceeded do północy UTC.

Ciężkie wyszukiwania są z założenia asynchroniczne: przekaż wait=false, aby od razu dostać searchId i odpytywać endpoint wyszukiwania, lub wait=true, aby otrzymać kompletny wynik w jednym wywołaniu. Odpytywanie liczy się do limitów jak każde inne żądanie.

Limit wyszukiwań na rezerwację

Wyszukiwania są też racjonowane względem dokonywanych rezerwacji. Każdy dzień kroczącego okna (domyślnie 7 dni) daje bezpłatną pulę wyszukiwań, a każda rezerwacja dokonana w tym oknie dodaje kolejne cap wyszukiwań — cap to uzgodniona dla Twojego konta liczba wyszukiwań na rezerwację, widoczna w portalu dewelopera. Odpytywania, wyceny, zasady taryfowe i odczyty treści nigdy się nie liczą; liczą się tylko wywołania wyszukiwania lotów i hoteli.

Po wyczerpaniu puli wyszukiwania zwracają 429 look_to_book_exceeded z nagłówkiem Retry-After wskazującym najbliższą północ UTC, gdy najstarszy dzień wypada z okna. Rezerwacja natychmiast ponownie otwiera pulę. Karta „Wyszukiwania a rezerwacje” w portalu dewelopera pokazuje bieżące liczniki, cap i pozostałą pulę; jeśli Twoja integracja w uzasadniony sposób wyszukuje znacznie więcej, niż rezerwuje, poproś nas o podniesienie cap zamiast ponawiać żądania mimo odmowy.

Idempotencja

Endpointy, które angażują pieniądze lub ofertę — tworzenie zamówienia lub rezerwacji, wystawianie, anulowanie — wymagają nagłówka Idempotency-Key (dowolny unikalny ciąg do 128 znaków; idealny jest UUID). Ponowienie z tym samym kluczem zwraca oryginalną odpowiedź zamiast tworzyć duplikat; inna treść pod ponownie użytym kluczem zwraca 409.

Wersjonowanie

Wersja jest w ścieżce (/v1). Zmiany addytywne — nowe opcjonalne pola, nowe wartości enum, nowe endpointy — są publikowane bez zmiany wersji, więc parsuj defensywnie i ignoruj nieznane pola. Zmiany niekompatybilne dostają nową wersję główną z okresem migracji; przewodnik „Dziennik zmian” wymienia każdą zmianę.