Ambienti, limiti e versioni

Sandbox e produzione, un solo URL di base

URL di base: https://api.dubaitrip.com/v1. Sandbox e produzione lo condividono; la chiave con cui firmi seleziona l'ambiente. Una chiave dt_sbx_ opera sugli ambienti di test dei nostri fornitori: ricerche, prezzi, verifiche tariffarie, ordini, prenotazioni, emissione e cancellazioni funzionano tutti dall'inizio alla fine su inventario di test, senza biglietti o voucher reali e senza alcun addebito. Una chiave dt_live_, emessa dopo la revisione per la produzione, raggiunge l'inventario reale e viene regolata sul tuo deposito.

Le prenotazioni sandbox e di produzione sono tenute separate nel tuo portale sviluppatori (ogni prenotazione è contrassegnata), e scope, limiti e regole IP si gestiscono per ambiente.

Limiti di frequenza e quote

Ogni chiave è limitata da un token bucket (richieste sostenute al secondo più un burst) e da una quota giornaliera. Valori predefiniti della sandbox: 2 richieste/secondo, burst 5, 2.000 richieste/giorno. I limiti di produzione vengono concordati per account. Superare il bucket restituisce 429 api_rate_limited con un'intestazione Retry-After; esaurire la quota restituisce 429 api_quota_exceeded fino alla mezzanotte UTC.

Le ricerche pesanti sono asincrone per progettazione: passa wait=false per ottenere subito un searchId ed esegui il polling dell'endpoint di ricerca, oppure wait=true per ricevere il risultato completo in un'unica chiamata. Il polling conta sui tuoi limiti come qualsiasi altra richiesta.

Limite look-to-book

Le ricerche sono anche contingentate in base alle prenotazioni che effettui. Ogni giorno di una finestra mobile (7 giorni per impostazione predefinita) concede una quota gratuita di ricerche, e ogni prenotazione effettuata in quella finestra aggiunge altre cap ricerche: cap è il numero di ricerche per prenotazione concordato per il tuo account e mostrato nel portale sviluppatori. Polling, prezzi, regole tariffarie e letture di contenuti non contano mai; contano solo le chiamate di ricerca voli e hotel.

Una volta esaurita la quota, le ricerche restituiscono 429 look_to_book_exceeded con un'intestazione Retry-After che punta alla successiva mezzanotte UTC, quando il giorno più vecchio esce dalla finestra. Una prenotazione riapre subito la quota. La scheda Rapporto look-to-book del portale sviluppatori mostra i contatori in tempo reale, il tetto e quanto resta; se la tua integrazione cerca legittimamente molto più di quanto prenota, chiedici di alzare il tetto invece di ritentare nonostante il rifiuto.

Idempotenza

Gli endpoint che impegnano denaro o inventario (creazione di un ordine o di una prenotazione, emissione, cancellazione) richiedono un'intestazione Idempotency-Key (qualsiasi stringa univoca fino a 128 caratteri; un UUID è l'ideale). Ripetere con la stessa chiave restituisce la risposta originale invece di creare un duplicato; un corpo diverso con una chiave riutilizzata restituisce 409.

Versioni

La versione è nel percorso (/v1). Le modifiche additive (nuovi campi facoltativi, nuovi valori enum, nuovi endpoint) vengono rilasciate senza cambiare versione, quindi effettua il parsing in modo difensivo e ignora i campi sconosciuti. Le modifiche incompatibili ottengono una nuova versione principale con un periodo di migrazione; la guida Registro delle modifiche elenca ogni modifica.