# Авиабилеты
Поиск доступных авиабилетов для пары городов: цены в USD от самых дешёвых, с сегментами, пересадками и длительностью маршрута.
Поиск доступных вариантов билетов для пары городов. Результаты отсортированы по цене (сначала самые дешёвые) и кэшируются на **1 час**. Цены возвращаются в **USD** вместе с метаданными исходной валюты, если валюта предложения отличается.
Каждый **маршрут (itinerary)** — это полный вариант путешествия от пункта отправления до пункта назначения, возможно, со стыковками. Результаты включают авиакомпанию и номер рейса для каждого сегмента, аэропорты и местное время вылета/прилёта, длительность сегмента, количество пересадок и **время стыковки (layover)** в аэропортах пересадки.
**Важно:** этот эндпоинт ожидает **3-буквенные коды аэропортов IATA** (`LHR`, `JFK`, `CDG`), а не ICAO. Сначала определите коды через [Поиск аэропортов](/docs/v31/airport-search).
## Запрос [#request]
| Параметр | Тип | Обязательный | По умолчанию | Описание |
| ------------- | ------------- | ------------ | ------------ | ---------------------------------------------- |
| `origin` | string | Да | - | IATA-код аэропорта отправления, например `LHR` |
| `destination` | string | Да | - | IATA-код аэропорта назначения, например `JFK` |
| `date` | string (date) | Нет | через 7 дней | Дата поездки `YYYY-MM-DD` |
| `passengers` | integer | Нет | `1` | Количество пассажиров (1–9) |
## Ответ [#response]
```json
{
"origin": "LHR",
"destination": "JFK",
"date": "2026-05-01",
"passengers": 1,
"count": 2,
"flights": [
{
"price_usd": 542.0,
"original_price": 498.0,
"original_currency": "EUR",
"total_duration_min": 465,
"stops": 0,
"legs": [
{
"flight_number": "BA117",
"airline": "British Airways",
"airline_code": "BA",
"departure_airport": "LHR",
"departure_airport_name": "London Heathrow Airport",
"arrival_airport": "JFK",
"arrival_airport_name": "John F. Kennedy International Airport",
"departure_time": "09:00",
"arrival_time": "11:45",
"departure_datetime": "2026-05-01T09:00:00",
"arrival_datetime": "2026-05-01T11:45:00",
"duration_min": 465
}
]
},
{
"price_usd": 398.0,
"original_price": 367.0,
"original_currency": "EUR",
"total_duration_min": 680,
"stops": 1,
"legs": [
{
"flight_number": "IB3163",
"airline": "Iberia",
"airline_code": "IB",
"departure_airport": "LHR",
"departure_airport_name": "London Heathrow Airport",
"arrival_airport": "MAD",
"arrival_airport_name": "Adolfo Suárez Madrid–Barajas Airport",
"departure_time": "07:15",
"arrival_time": "10:30",
"departure_datetime": "2026-05-01T07:15:00",
"arrival_datetime": "2026-05-01T10:30:00",
"duration_min": 135
},
{
"flight_number": "IB6251",
"airline": "Iberia",
"airline_code": "IB",
"departure_airport": "MAD",
"departure_airport_name": "Adolfo Suárez Madrid–Barajas Airport",
"arrival_airport": "JFK",
"arrival_airport_name": "John F. Kennedy International Airport",
"departure_time": "13:05",
"arrival_time": "16:15",
"departure_datetime": "2026-05-01T13:05:00",
"arrival_datetime": "2026-05-01T16:15:00",
"duration_min": 490
}
],
"layovers": [
{
"airport": "MAD",
"airport_name": "Adolfo Suárez Madrid–Barajas Airport",
"duration_min": 155
}
]
}
]
}
```
### Поля верхнего уровня [#top-level-fields]
| Поле | Тип | Обязательный | Описание |
| ------------- | ------- | ------------ | -------------------------------------------------------------------- |
| `origin` | string | **Да** | IATA-код отправления из запроса |
| `destination` | string | **Да** | IATA-код назначения из запроса |
| `date` | string | **Да** | Дата поездки, использованная для поиска |
| `passengers` | integer | **Да** | Количество пассажиров |
| `count` | integer | **Да** | Количество маршрутов в `flights` |
| `flights` | array | **Да** | Варианты, отсортированные по цене (может быть пустым, если мест нет) |
**Важно:** `count: 0` с `flights: []` — допустимый ответ; показывайте состояние «нет доступных вариантов», а не ошибку.
### Маршрут (`flights[]`) [#itinerary-flights]
| Поле | Тип | Обязательный | Может быть null? | Описание |
| -------------------- | ------- | ------------ | ---------------- | ------------------------------------------------------------------- |
| `price_usd` | number | **Да** | Никогда | Итоговая цена в USD |
| `original_price` | number | **Да** | Никогда | Исходная цена до конвертации в USD |
| `original_currency` | string | **Да** | Никогда | Код валюты ISO для `original_price`, например `EUR` |
| `total_duration_min` | integer | **Да** | Никогда | Общая длительность «от двери до двери» в минутах, включая пересадки |
| `stops` | integer | **Да** | Никогда | Количество пересадок (`0` — беспосадочный перелёт) |
| `legs` | array | **Да** | Никогда | Сегменты перелёта по порядку |
| `layovers` | array | Нет | **Да** | Присутствует, если `stops` > 0 |
### Сегмент (`legs[]`) [#leg-legs]
| Поле | Тип | Обязательный | Описание |
| ------------------------ | ------- | ------------ | ------------------------------------------ |
| `flight_number` | string | **Да** | Коммерческий номер рейса |
| `airline` | string | **Да** | Отображаемое название авиакомпании |
| `airline_code` | string | **Да** | IATA-код авиакомпании |
| `departure_airport` | string | **Да** | IATA-код аэропорта вылета |
| `departure_airport_name` | string | **Да** | Название аэропорта вылета |
| `arrival_airport` | string | **Да** | IATA-код аэропорта прилёта |
| `arrival_airport_name` | string | **Да** | Название аэропорта прилёта |
| `departure_time` | string | **Да** | Местное время вылета `HH:MM` |
| `arrival_time` | string | **Да** | Местное время прилёта `HH:MM` |
| `departure_datetime` | string | **Да** | Местные дата и время вылета в формате ISO |
| `arrival_datetime` | string | **Да** | Местные дата и время прилёта в формате ISO |
| `duration_min` | integer | **Да** | Блочное время сегмента в минутах |
### Пересадка (`layovers[]`) [#layover-layovers]
| Поле | Тип | Обязательный | Описание |
| -------------- | ------- | ------------ | ------------------------------------- |
| `airport` | string | **Да** | IATA-код аэропорта пересадки |
| `airport_name` | string | **Да** | Название аэропорта пересадки |
| `duration_min` | integer | **Да** | Время на земле до следующего сегмента |
## Клиентские типы [#client-types]
## Интеграция [#integration]
Интерфейсы поиска билетов обычно применяют debounce к выбору аэропорта и кэшируют ответы для каждого набора `(origin, destination, date, passengers)` на срок до одного часа. Пример ниже получает результаты, преобразует самый дешёвый вариант в модель карточки и корректно обрабатывает пустые массивы `flights`.
### Примечания по реализации [#implementation-notes]
**Важно:** цены — это ориентировочные рыночные снимки, а не актуальные данные о наличии мест у авиакомпании. В интерфейсе для пассажиров сообщайте, что цена может измениться в момент бронирования.
Чтобы получить статус забронированного рейса в реальном времени, используйте [Статус рейса](/docs/v31/flight-status).
## Ответы с ошибками [#error-responses]
Общие ошибки платформы описаны в разделе [Обработка ошибок](/docs/errors). Поведение, специфичное для эндпоинта:
### 422 — недопустимые параметры [#422--invalid-parameters]
Возвращается, если `origin`/`destination` отсутствуют или не проходят валидацию.
### Руководства по интеграции [#integration-guides]
| Руководство | Что охватывает |
| -------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| [Поиск билетов](/docs/v31/tickets-integration) | Самые дешёвые и самые быстрые варианты, маршруты, несколько пассажиров |
| [Обработка ошибок](/docs/v31/tickets-integration-errors) | Пустые результаты, коды IATA, ориентировочные цены |
| [Кэширование и мониторинг](/docs/v31/tickets-integration-production) | Ключ кэша на 1 час и debounce |