Environnements, limites et versions

Bac à sable et production, une seule URL de base

URL de base : https://api.dubaitrip.com/v1. Le bac à sable et la production la partagent ; c’est la clé avec laquelle vous signez qui sélectionne l’environnement. Une clé dt_sbx_ fonctionne sur les environnements de test de nos fournisseurs — recherches, tarification, vérifications de tarif, commandes, réservations, émission et annulations fonctionnent de bout en bout sur une offre de test, sans billet ni bon réel et sans aucun débit. Une clé dt_live_, émise après l’examen pour la production, atteint l’offre réelle et est réglée sur votre dépôt.

Les réservations en bac à sable et en production sont séparées dans votre portail développeur (chaque réservation est marquée), et les portées, limites et règles IP sont gérées par environnement.

Limites de débit et quotas

Chaque clé est régulée par un seau à jetons (requêtes soutenues par seconde plus une rafale) et un quota quotidien. Valeurs par défaut du bac à sable : 2 requêtes/seconde, rafale de 5, 2 000 requêtes/jour. Les limites de production sont convenues par compte. Dépasser le seau renvoie 429 api_rate_limited avec un en-tête Retry-After ; épuiser le quota renvoie 429 api_quota_exceeded jusqu’à minuit UTC.

Les recherches lourdes sont asynchrones par conception : passez wait=false pour obtenir immédiatement un searchId et interroger l’endpoint de recherche, ou wait=true pour recevoir le résultat complet en un seul appel. Les interrogations comptent dans vos limites comme toute autre requête.

Garde-fou look-to-book

Les recherches sont aussi rationnées en fonction des réservations que vous effectuez. Chaque jour d’une période glissante (7 jours par défaut) accorde un quota gratuit de recherches, et chaque réservation effectuée sur cette période ajoute cap recherches supplémentaires — cap est le nombre de recherches par réservation convenu pour votre compte et affiché dans le portail développeur. Les interrogations, la tarification, les règles tarifaires et les lectures de contenu ne comptent jamais ; seuls les appels de recherche de vols et d’hôtels comptent.

Une fois le quota épuisé, les recherches renvoient 429 look_to_book_exceeded avec un en-tête Retry-After pointant vers le prochain minuit UTC, lorsque le jour le plus ancien de la période sort du calcul. Une réservation rouvre immédiatement le quota. La carte Look-to-book du portail développeur affiche les compteurs en direct, le plafond et ce qui reste ; si votre intégration recherche légitimement bien plus qu’elle ne réserve, demandez-nous de relever le plafond plutôt que de réessayer malgré le refus.

Idempotence

Les endpoints qui engagent de l’argent ou de l’offre — création d’une commande ou d’une réservation, émission, annulation — exigent un en-tête Idempotency-Key (toute chaîne unique de 128 caractères au plus ; un UUID est idéal). Réessayer avec la même clé renvoie la réponse d’origine au lieu de créer un doublon ; un corps différent sous une clé réutilisée renvoie 409.

Gestion des versions

La version figure dans le chemin (/v1). Les changements additifs — nouveaux champs facultatifs, nouvelles valeurs d’énumération, nouveaux endpoints — sont publiés sans changement de version : analysez donc de manière défensive et ignorez les champs inconnus. Les changements incompatibles donnent lieu à une nouvelle version majeure avec une période de migration ; le guide Journal des modifications recense chaque changement.