Середовища, ліміти та версіонування

Пісочниця й продакшн, один базовий URL

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

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

Ліміти запитів і квоти

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

Важкі пошуки асинхронні за задумом: передайте wait=false, щоб одразу отримати searchId і опитувати ендпоінт пошуку, або wait=true, щоб отримати повний результат одним викликом. Опитування враховується в лімітах, як і будь-який інший запит.

Обмеження look-to-book

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

Щойно ліміт вичерпано, пошуки повертають 429 look_to_book_exceeded із заголовком Retry-After, що вказує на найближчу північ за UTC, коли найстаріший день періоду випадає з вікна. Бронювання одразу відновлює ліміт. Картка Look-to-book на порталі розробника показує поточні лічильники, cap і залишок; якщо ваша інтеграція обґрунтовано шукає значно більше, ніж бронює, попросіть нас підвищити cap, а не повторюйте запити попри відмову.

Ідемпотентність

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

Версіонування

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