Medii, limite și versiuni

Sandbox și producție, un singur URL de bază

URL de bază: https://api.dubaitrip.com/v1. Sandboxul și producția îl folosesc în comun; cheia cu care semnezi selectează mediul. O cheie dt_sbx_ rulează pe mediile de test ale furnizorilor noștri — căutările, calculul prețurilor, verificările de tarif, comenzile, rezervările, emiterea biletelor și anulările funcționează toate cap-coadă pe inventar de test, fără bilete sau vouchere reale și fără nicio taxare. O cheie dt_live_, emisă după evaluarea pentru producție, ajunge la inventarul live și se decontează din depozitul tău.

Rezervările din sandbox și cele din producție sunt ținute separat în portalul pentru dezvoltatori (fiecare rezervare este marcată), iar scopurile, limitele și regulile IP se gestionează per mediu.

Limite de rată și cote

Fiecare cheie este limitată printr-un token bucket (cereri susținute pe secundă plus o rafală) și o cotă zilnică. Valori implicite în sandbox: 2 cereri/secundă, rafală 5, 2000 de cereri/zi. Limitele de producție se stabilesc pentru fiecare cont. Depășirea bucketului întoarce 429 api_rate_limited cu un header Retry-After; epuizarea cotei întoarce 429 api_quota_exceeded până la miezul nopții UTC.

Căutările grele sunt asincrone prin design: trimite wait=false pentru a primi imediat un searchId și a interoga endpointul de căutare, sau wait=true pentru a primi rezultatul complet într-un singur apel. Interogările repetate se contorizează în limitele tale ca orice altă cerere.

Protecție look-to-book

Căutările sunt raționalizate și în funcție de rezervările pe care le faci. Fiecare zi dintr-o fereastră glisantă (implicit 7 zile) acordă o alocare gratuită de căutări, iar fiecare rezervare făcută în acea fereastră adaugă încă cap căutări — cap este numărul de căutări per rezervare convenit pentru contul tău și afișat în portalul pentru dezvoltatori. Interogările repetate, calculul prețurilor, regulile tarifare și citirile de conținut nu se contorizează niciodată; se contorizează doar apelurile de căutare de zboruri și hoteluri.

După epuizarea alocării, căutările întorc 429 look_to_book_exceeded cu un header Retry-After care indică următorul miez al nopții UTC, când cea mai veche zi iese din fereastră. O rezervare redeschide imediat alocarea. Cardul Look-to-book din portalul pentru dezvoltatori arată contoarele live, plafonul și ce a mai rămas; dacă integrarea ta caută în mod legitim mult mai mult decât rezervă, cere-ne să mărim plafonul în loc să reîncerci peste refuz.

Idempotență

Endpointurile care angajează bani sau inventar — crearea unei comenzi sau rezervări, emiterea, anularea — necesită un header Idempotency-Key (orice șir unic de până la 128 de caractere; un UUID este ideal). O reîncercare cu aceeași cheie întoarce răspunsul original în loc să creeze un duplicat; un corp diferit sub o cheie reutilizată întoarce 409.

Versiuni

Versiunea se află în cale (/v1). Modificările aditive — câmpuri opționale noi, valori enum noi, endpointuri noi — sunt lansate fără schimbarea versiunii, așa că parsează defensiv și ignoră câmpurile necunoscute. Modificările incompatibile primesc o nouă versiune majoră, cu o perioadă de migrare; ghidul Jurnal de modificări enumeră fiecare schimbare.