Entornos, límites y versiones

Sandbox y producción, una sola URL base

URL base: https://api.dubaitrip.com/v1. Sandbox y producción la comparten; la clave con la que firma selecciona el entorno. Una clave dt_sbx_ trabaja contra los entornos de prueba de nuestros proveedores: búsquedas, precios, comprobaciones de tarifa, pedidos, reservas, emisión y cancelaciones funcionan de principio a fin sobre inventario de prueba, sin billete ni bono reales y sin ningún cargo. Una clave dt_live_, emitida tras la revisión de producción, llega al inventario real y se liquida contra su depósito.

Las reservas de sandbox y de producción se mantienen separadas en su portal para desarrolladores (cada reserva va marcada), y los ámbitos, los límites y las reglas de IP se gestionan por entorno.

Límites de tasa y cuotas

Cada clave está limitada por un token bucket (solicitudes sostenidas por segundo más una ráfaga) y por una cuota diaria. Valores predeterminados del sandbox: 2 solicitudes/segundo, ráfaga de 5, 2.000 solicitudes/día. Los límites de producción se acuerdan por cuenta. Superar el bucket devuelve 429 api_rate_limited con un encabezado Retry-After; agotar la cuota devuelve 429 api_quota_exceeded hasta la medianoche UTC.

Las búsquedas pesadas son asíncronas por diseño: pase wait=false para obtener un searchId de inmediato y consultar periódicamente el endpoint de búsqueda, o wait=true para recibir el resultado completo en una sola llamada. Las consultas periódicas cuentan para sus límites como cualquier otra solicitud.

Control de look-to-book

Las búsquedas también se racionan en función de las reservas que realiza. Cada día de un periodo móvil (7 días por defecto) concede una cuota gratuita de búsquedas, y cada reserva realizada en ese periodo añade otras cap búsquedas: cap es la cifra de búsquedas por reserva acordada para su cuenta y mostrada en el portal para desarrolladores. Las consultas periódicas, los precios, las reglas de tarifa y las lecturas de contenido nunca cuentan; solo cuentan las llamadas de búsqueda de vuelos y hoteles.

Una vez agotada la cuota, las búsquedas devuelven 429 look_to_book_exceeded con un encabezado Retry-After que apunta a la siguiente medianoche UTC, cuando sale del periodo el día más antiguo. Una reserva vuelve a abrir la cuota de inmediato. La tarjeta Look-to-book del portal para desarrolladores muestra los contadores en tiempo real, el límite y lo que queda; si su integración busca legítimamente mucho más de lo que reserva, pídanos que aumentemos el límite en lugar de reintentar contra el rechazo.

Idempotencia

Los endpoints que comprometen dinero o inventario (crear un pedido o una reserva, emitir, cancelar) exigen un encabezado Idempotency-Key (cualquier cadena única de hasta 128 caracteres; lo ideal es un UUID). Reintentar con la misma clave devuelve la respuesta original en lugar de crear un duplicado; un cuerpo distinto con una clave reutilizada devuelve 409.

Versiones

La versión va en la ruta (/v1). Los cambios aditivos (nuevos campos opcionales, nuevos valores de enumeración, nuevos endpoints) se publican sin cambiar de versión, así que analice las respuestas de forma defensiva e ignore los campos desconocidos. Los cambios incompatibles reciben una nueva versión principal con un periodo de migración; la guía Registro de cambios recoge cada cambio.