Окружения, лимиты и версионирование

Sandbox и продакшен, один базовый URL

Базовый URL: https://api.dubaitrip.com/v1. Он общий для sandbox и продакшена; окружение определяется ключом, которым вы подписываете запрос. Ключ dt_sbx_ работает с тестовыми средами наших поставщиков — поиск, расчёт цены, проверка тарифов, заказы, бронирования, выписка билетов и отмены работают от начала до конца на тестовых предложениях, без реальных билетов или ваучеров и без списаний. Ключ dt_live_, выдаваемый после проверки для продакшена, работает с боевыми предложениями и оплачивается с вашего депозита.

Бронирования sandbox и продакшена разделены в портале разработчика (каждое бронирование помечено), а скоупы, лимиты и IP-правила настраиваются для каждого окружения отдельно.

Лимиты запросов и квоты

Каждый ключ ограничивается алгоритмом token bucket (устойчивое число запросов в секунду плюс всплеск) и дневной квотой. Значения sandbox по умолчанию: 2 запроса/секунду, всплеск 5, 2000 запросов/день. Лимиты продакшена согласуются для каждого аккаунта. При переполнении bucket возвращается 429 api_rate_limited с заголовком Retry-After; при исчерпании квоты — 429 api_quota_exceeded до полуночи UTC.

Тяжёлые поиски асинхронны по своей природе: передайте wait=false, чтобы сразу получить searchId и опрашивать эндпоинт поиска, или wait=true, чтобы получить полный результат одним вызовом. Опросы учитываются в лимитах, как и любой другой запрос.

Лимит поисков на бронирование

Поиски также нормируются относительно ваших бронирований. Каждый день скользящего окна (по умолчанию 7 дней) даёт бесплатный лимит поисков, а каждое бронирование в этом окне добавляет сверху ещё cap поисков — cap это согласованное для вашего аккаунта число поисков на бронирование, которое показано в портале разработчика. Опросы, расчёт цены, правила тарифов и чтение контента не учитываются никогда — только вызовы поиска авиабилетов и отелей.

Когда лимит исчерпан, поиски возвращают 429 look_to_book_exceeded с заголовком Retry-After, указывающим на ближайшую полночь UTC, когда самый старый день выпадает из окна. Бронирование сразу снова открывает лимит. Карточка «Поиски и бронирования» в портале разработчика показывает текущие счётчики, cap и остаток; если ваша интеграция обоснованно ищет гораздо больше, чем бронирует, попросите нас повысить cap, а не повторяйте запросы в обход отказа.

Идемпотентность

Эндпоинты, которые списывают деньги или резервируют места, — создание заказа или бронирования, выписка, отмена — требуют заголовок Idempotency-Key (любая уникальная строка длиной до 128 символов, идеально подходит UUID). Повтор с тем же ключом возвращает исходный ответ вместо создания дубликата; другое тело с повторно использованным ключом возвращает 409.

Версионирование

Версия указывается в пути (/v1). Дополняющие изменения — новые необязательные поля, новые значения enum, новые эндпоинты — выходят без смены версии, поэтому разбирайте ответы защитно и игнорируйте неизвестные поля. Ломающие изменения получают новую мажорную версию с периодом миграции; руководство «Журнал изменений» перечисляет все изменения.