> ## Documentation Index > Fetch the complete documentation index at: https://developer.every.ru/llms.txt > Use this file to discover all available pages before exploring further. # Получение списка доступных фаст-треков ## OpenAPI ````yaml GET /v2/catalog/fast-tracks openapi: 3.1.0 info: version: 1.0.0 title: Every Travel B2B API description: > Партнёрский B2B API для оформления travel-сервисов: бизнес-залы (lounges), фаст-трек (fast-track) и eSIM. Все B2B-эндпоинты доступны после получения access token через `POST /oauth/v2/token` и (где требуется) с клиентским сертификатом mTLS. ## Состав API - **Идентификация и токены** — OAuth2 (`client_credentials`), JWKS для оффлайн-проверки JWT. - **Каталоги** — список бизнес-залов, фаст-треков и тарифов eSIM, доступных партнёру. - **Бронирование (lounge / fast-track)** — двухшаговый сценарий «создать → подтвердить», получение данных прохода (`/pass`), отмена. - **Заказ eSIM** — двухшаговый сценарий «создать заказ → подтвердить заказ», по подтверждению возвращается выпущенная eSIM с данными для активации (QR/LPA). - **Webhooks** — подписка на события (`booking.status.changed`, `pass.status.changed`, `esim.package.usage_threshold_reached`, `esim.package.exhausted`, `esim.package.expired`). ## Кэширование каталогов API поддерживает условные запросы для эндпоинтов каталогов через заголовки `ETag`/`If-None-Match` и `Last-Modified`/`If-Modified-Since`. Это позволяет клиентам экономить трафик при повторных запросах. ### Использование ETag При первом запросе сервер возвращает заголовок `ETag` с уникальным идентификатором версии ресурса. При последующих запросах клиент может передать это значение в заголовке `If-None-Match`. Если ресурс не изменился, сервер возвращает `304 Not Modified` без тела ответа. ### Использование Last-Modified Сервер также возвращает заголовок `Last-Modified` с датой последнего изменения ресурса. Клиент может передать это значение в заголовке `If-Modified-Since` при следующем запросе. Если ресурс не был изменен после указанной даты, сервер возвращает `304 Not Modified`. ### Пример использования ``` # Первый запрос GET /v2/catalog/lounges → 200 OK → ETag: "abc123" → Last-Modified: Wed, 21 Oct 2015 07:28:00 GMT # Повторный запрос с ETag GET /v2/catalog/lounges If-None-Match: "abc123" → 304 Not Modified → ETag: "abc123" → Last-Modified: Wed, 21 Oct 2015 07:28:00 GMT ``` ## Идемпотентность API поддерживает идемпотентность операций через заголовок `Idempotency-Key`. Операции создания бронирований (POST /v2/b2b/booking/lounges, POST /v2/b2b/booking/fast-tracks), операции выпуска и пополнения eSIM (POST /v2/b2b/fulfilment/esims, POST /v2/b2b/fulfilment/esims/{iccid}/topup) и операции создания аккаунтов и приложений (POST /v2/admin/accounts, POST /v2/admin/accounts/{accountID}/applications) требуют обязательного заголовка `Idempotency-Key`. Операции подтверждения и отмены бронирований (POST /v2/b2b/booking/*/confirm, POST /v2/b2b/booking/*/cancel) идемпотентны по своей природе через бизнес-логику (повторный вызов возвращает 409 при недопустимом состоянии) и не требуют ключа идемпотентности. ### Поведение (Source-of-Truth) При повторном запросе с тем же `Idempotency-Key`: - **Совпадение тела запроса**: сервер возвращает **строго тот же HTTP-код и тело ответа**, что были возвращены при первом запросе. Заголовок `Idempotency-Status: reused` указывает на повторное использование. - **Несовпадение тела запроса**: сервер возвращает `409 IdempotencyConflict`, если тело запроса отличается от сохранённого (см. правила сравнения ниже). ### Правила сравнения тела запроса Для определения конфликта сравниваются следующие поля: - **POST /v2/b2b/booking/lounges**: все поля `LoungeBookingRequest` (lounge_id, first_name, last_name, email, phone, calling_code, transport_number, guests) - **POST /v2/b2b/booking/fast-tracks**: все поля `FastTrackBookingRequest` (fast_track_id, first_name, last_name, email, phone, calling_code, transport_number, guests) - **POST /v2/b2b/fulfilment/esims**: все поля `CreateAccountEsimRequest` (package_template_id, active_period, validity_period) - **POST /v2/b2b/fulfilment/esims/{iccid}/topup**: путь (`iccid`) и все поля `CreateAccountEsimRequest` (package_template_id, active_period, validity_period) - **POST /v2/admin/accounts**: все поля `AdminCreateAccountRequest` (name, csr_pem) - **POST /v2/admin/accounts/{accountID}/applications**: все поля `AdminCreateApplicationRequest` (name, allowed_scopes) Сравнение выполняется путём нормализации JSON (игнорирование порядка полей, нормализация пробелов) и побайтового сравнения нормализованных представлений. ### TTL и истечение срока действия Ключ идемпотентности имеет TTL **72 часа** с момента первого использования. После истечения TTL: - Ключ считается недействительным - Новый запрос с тем же ключом обрабатывается как новый запрос (создаётся новая операция) - Возвращается `Idempotency-Status: created` - **Не** возвращается ошибка 422 или 409 ### Заголовки ответа Все операции, поддерживающие идемпотентность, возвращают: - `Idempotency-Key`: эхо переданного ключа - `Idempotency-Status`: - `created` — операция создана впервые - `reused` — операция повторно использована (возвращён сохранённый результат) ## Webhooks API поддерживает отправку webhook-уведомлений для отслеживания жизненного цикла бронирований и проходов. Это позволяет получать уведомления об изменениях статусов без поллинга API. ### Управление подпиской Партнёр может иметь **не более одной** webhook-подписки на аккаунт. Управление осуществляется через узкие command-эндпоинты, соответствующие поддерживаемым операциям: - `POST /v2/b2b/webhooks` — создание подписки - `GET /v2/b2b/webhooks` — список подписок (0 или 1 элемент) - `GET /v2/b2b/webhooks/{webhookID}` — получение подписки - `POST /v2/b2b/webhooks/{webhookID}/change-url` — изменение URL endpoint - `POST /v2/b2b/webhooks/{webhookID}/rotate-secret` — ротация секрета подписи - `POST /v2/b2b/webhooks/{webhookID}/disable` — приостановить доставку - `POST /v2/b2b/webhooks/{webhookID}/enable` — возобновить доставку - `DELETE /v2/b2b/webhooks/{webhookID}` — удаление подписки При создании подписки указываются: - `url` — URL endpoint для приёма webhook-уведомлений (должен быть доступен по HTTPS) - `secret` — секретный ключ для подписи webhook-уведомлений (HMAC-SHA256) Партнёр получает уведомления обо всех поддерживаемых событиях; отдельная подписка на конкретные типы не требуется. ### Формат webhook-уведомлений Все webhook-уведомления отправляются в формате JSON и содержат: - `event` — тип события - `timestamp` — время возникновения события (ISO 8601) - `data` — данные события (зависит от типа события) ### Поддерживаемые события - `booking.status.changed` — изменение статуса бронирования - `pass.status.changed` — изменение статуса прохода ### Безопасность Webhook-уведомления подписываются с использованием HMAC-SHA256. Подпись передаётся в заголовке `X-Webhook-Signature`. servers: - url: https://api.phoenixpass.space description: Production - url: http://localhost:8080 description: Local development - url: https://api.sandbox.every.ru description: Sandbox security: [] paths: /v2/catalog/fast-tracks: get: tags: - b2b - catalog summary: Получение списка доступных фаст-треков operationId: getFastTracks parameters: - $ref: '#/components/parameters/PaginationLimit' - $ref: '#/components/parameters/PaginationOffset' - $ref: '#/components/parameters/NameSearch' - $ref: '#/components/parameters/Language' - $ref: '#/components/parameters/RequestID' - $ref: '#/components/parameters/IfNoneMatch' - $ref: '#/components/parameters/IfModifiedSince' responses: '200': description: Успешный ответ headers: Content-Language: $ref: '#/components/headers/ContentLanguage' ETag: $ref: '#/components/headers/ETag' Last-Modified: $ref: '#/components/headers/LastModified' Vary: $ref: '#/components/headers/Vary' content: application/json: schema: $ref: '#/components/schemas/FastTracksPage' '304': $ref: '#/components/responses/NotModified' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '500': $ref: '#/components/responses/InternalError' '503': $ref: '#/components/responses/ServiceUnavailable' security: - Bearer: - catalog.fasttrack:read components: parameters: PaginationLimit: name: limit description: Лимит записей в одном запросе in: query required: false schema: type: integer default: 100 PaginationOffset: name: offset description: Текущий указатель отступа in: query required: false schema: type: integer default: 0 NameSearch: name: name in: query required: false description: > Отбор по вхождению подстроки в локализованном человекочитаемом названии (без учёта регистра). Локаль сравнения совпадает с локалью строк в ответе (см. заголовок Accept-Language). Пустое значение — без фильтра. Условие применяется до пагинации (`limit` / `offset`). schema: type: string maxLength: 64 example: домодед Language: name: Accept-Language in: header required: false schema: $ref: '#/components/schemas/Language' description: | Язык локализации ответов в формате BCP 47 (например, "en-US", "ru-RU"). Если не указан — используется язык по умолчанию сервиса. RequestID: name: X-Request-ID in: header required: false schema: type: string description: > Уникальный идентификатор для трассировки запроса. Не влияет на логику исполнения запроса. IfNoneMatch: name: If-None-Match in: header required: false schema: type: string description: > Условный запрос для проверки актуальности ресурса. Если значение ETag ресурса совпадает с переданным значением, сервер возвращает 304 Not Modified без тела ответа. Значение должно быть в формате, полученном в заголовке ETag предыдущего ответа. Пример: `"abc123"` или `W/"abc123"` (для слабых ETag). IfModifiedSince: name: If-Modified-Since in: header required: false schema: type: string description: > Условный запрос для проверки актуальности ресурса по дате изменения. Если ресурс не был изменен после указанной даты, сервер возвращает 304 Not Modified без тела ответа. Значение должно быть в формате HTTP-date (RFC 7231, Section 7.1.1.1). Пример: `Wed, 21 Oct 2015 07:28:00 GMT`. headers: ContentLanguage: description: > Язык локализации ответа в формате BCP 47 (например, "en-US", "ru-RU"). Соответствует языку, указанному в заголовке `Accept-Language` запроса или языку по умолчанию сервиса. schema: $ref: '#/components/schemas/Language' ETag: description: > Entity Tag (ETag) для условных запросов. Уникальный идентификатор версии ресурса. Используется для оптимизации запросов к каталогам через заголовок `If-None-Match`. Формат: строка в кавычках, например `"abc123"` или слабый ETag `W/"abc123"`. Клиент должен сохранять это значение и передавать в заголовке `If-None-Match` при следующем запросе. schema: $ref: '#/components/schemas/ETag' LastModified: description: > Дата и время последнего изменения ресурса в формате HTTP-date (RFC 7231, Section 7.1.1.1). Используется для условных запросов через заголовок `If-Modified-Since`. Клиент может передавать это значение в заголовке `If-Modified-Since` при следующем запросе для проверки, изменился ли ресурс. schema: $ref: '#/components/schemas/LastModified' Vary: description: Указывает, что ответ зависит от заголовка Accept-Language schema: type: string example: Accept-Language RetryAfter: description: Рекомендуемая задержка перед повтором в секундах schema: type: integer minimum: 1 schemas: FastTracksPage: type: object description: Список доступных фаст-треков required: - data - pagination properties: data: type: array items: $ref: '#/components/schemas/FastTrack' pagination: $ref: '#/components/schemas/Pagination' Language: type: string enum: - ru-RU - en-US description: | Язык локализации ответов в формате BCP 47 (например, "en-US", "ru-RU"). Если не указан — используется язык по умолчанию сервиса. ETag: type: string description: > Entity Tag (ETag) для условных запросов. Уникальный идентификатор версии ресурса. Используется для оптимизации запросов к каталогам через заголовок `If-None-Match`. Формат: строка в кавычках, например `"abc123"` или слабый ETag `W/"abc123"`. Клиент должен сохранять это значение и передавать в заголовке `If-None-Match` при следующем запросе. example: '"33a64df551425fcc55e4d42a148795d9f25f89d4"' LastModified: type: string description: > Дата и время последнего изменения ресурса в формате HTTP-date (RFC 7231, Section 7.1.1.1). Используется для условных запросов через заголовок `If-Modified-Since`. Клиент может передавать это значение в заголовке `If-Modified-Since` при следующем запросе для проверки, изменился ли ресурс. example: Wed, 21 Oct 2015 07:28:00 GMT FastTrack: type: object description: | Фаст-трек. Может находиться в аэропорту, круизном порту. Услуга фаст-трека привязана к хабу (только аэропорты) required: - id - location - hub - business_hours - is_active properties: id: $ref: '#/components/schemas/FastTrackID' location: $ref: '#/components/schemas/Location' hub: $ref: '#/components/schemas/TransportHub' airside_zone: $ref: '#/components/schemas/AirsideZone' business_hours: $ref: '#/components/schemas/BusinessHours' is_active: type: boolean description: Флаг, указывающий на статус активности фаст-трека default: true required_booking_info: type: array description: Обязательная информация о гостях для бронирования items: $ref: '#/components/schemas/RequiredBookingCustomerInfo' policy: $ref: '#/components/schemas/FastTrackPolicy' Pagination: type: object properties: count: type: integer description: Количество записей в выдаче example: 1 minimum: 0 maximum: 1000 offset: type: integer description: Номер текущего отступа minimum: 0 example: 1 total: type: integer description: Общее количество записей целевого ресурса example: 100 minimum: 0 Error: type: object description: | Базовый формат ошибки API в соответствии с RFC 9457. required: - code - title - status - instance properties: code: type: string enum: - Unauthorized - Forbidden - ResourceNotFound - RateLimitExceeded - InternalServerError - AlreadyCompanyMember - ValidationError - BookingNotFound - CatalogResourceNotFound - CatalogResourceConflict - PassNotReady - PassServiceTypeMismatch - BookingAlreadyConfirmed - BookingAlreadyCanceled - IdempotencyConflict - ContractAlreadyExists - WebhookNotFound - WebhookAlreadyExists - WebhookInvalidState - InternalError - ServiceUnavailable - AmenityResourceConflict - EsimNotFound - EsimPoolExhausted - EsimTopupUnavailable - EsimResellerAlreadyLinked description: Машиночитаемый код ошибки из реестра. title: type: string description: Краткое человекочитаемое описание типа проблемы. example: Phone verification failed status: type: integer description: HTTP статус код ошибки. example: 400 minimum: 100 maximum: 599 detail: type: string description: Детальное описание проблемы для отладки и логирования (опционально). example: Phone verification failed instance: type: string format: uri-reference description: | URI, идентифицирующий конкретный экземпляр проблемы. Обычно указывает на путь запроса, который вызвал ошибку. example: /v1/identity/oauth/token details: type: object additionalProperties: true description: Дополнительная информация об ошибке (опционально). request_id: type: string description: >- Идентификатор запроса. Указан в заголовке X-Request-ID (опционально). example: 123e4567-e89b-12d3-a456-426614174000 FastTrackID: type: string description: Идентификатор услуги фаст-трека format: uuid Location: description: Локация type: object required: - city - continent - country - coordinates properties: city: type: string description: Город локации maxLength: 100 example: Москва country: type: string description: Двухбуквенный код страны по ISO 3166-1 minLength: 2 maxLength: 2 pattern: ^[A-Z]{2}$ example: RU continent: $ref: '#/components/schemas/Continent' coordinates: $ref: '#/components/schemas/GeoPoint' TransportHub: description: Транспортный хаб type: object required: - id - location - kind - name properties: id: $ref: '#/components/schemas/TransportHubId' location: $ref: '#/components/schemas/Location' timezone: type: string description: IANA time zone name (tz database), e.g. Europe/Moscow example: Europe/Moscow kind: $ref: '#/components/schemas/TransportHubType' name: type: string description: Имя транспортного хаба example: Аэропорт Домодедово meta: oneOf: - $ref: '#/components/schemas/Airport' - $ref: '#/components/schemas/Railway' discriminator: propertyName: kind mapping: Airport: $ref: '#/components/schemas/Airport' Railway: $ref: '#/components/schemas/Railway' AirsideZone: type: string description: | Уточнение стерильной зоны (если landside = false): - `International` — зал находится в международной зоне - `Domestic` — зал находится в зоне внутренних рейсов - `Any` — зал доступен как в международной, так и во внутренней зоне Используется в аэропортах, где залы делятся по зонам вылета. enum: - International - Domestic - Any BusinessHours: type: array description: | График работы, сгруппированный по дням недели. Каждый элемент описывает режим работы на конкретный день (1–7). items: $ref: '#/components/schemas/BusinessDay' RequiredBookingCustomerInfo: type: string description: | Список возможных требований для оформления бронирования. enum: - Name - Email - Phone FastTrackPolicy: type: object description: | Правила использования услуги фаст-трека. required: - booking_before_hours properties: booking_before_hours: type: string description: | Минимальное количество часов до бронирования. Формат: `PDTH` Например: `P1DT12H` - 1 день и 12 часов. example: P1DT12H Continent: type: string enum: - Europe - Asia - Africa - NorthAmerica - SouthAmerica - Oceania - Antarctica description: Континент в котором находится Локация example: Europe GeoPoint: type: object required: - latitude - longitude properties: latitude: type: number format: double description: | Географическая широта в десятичных градусах (WGS-84). Диапазон от -90 до 90 minimum: -90 maximum: 90 example: 53.467 longitude: type: number format: double description: | Географическая долгота в десятичных градусах (WGS-84). Диапазон: от -180 до 180 minimum: -180 maximum: 180 example: -2.233 TransportHubId: type: string description: Идентификатор транспортного хаба format: uuid TransportHubType: type: string enum: - Airport - Railway Airport: type: object required: - kind - iata - icao properties: kind: type: string enum: - Airport iata: type: string description: > Трехсимвольный код аэропорта по стандарту **IATA** (International Air Transport Association). Используется в авиабилетах, расписаниях и системах бронирования. Может меняться. pattern: ^[A-Z]{3}$ example: DME icao: type: string description: > Четырехсимвольный код аэропорта по стандарту **ICAO** (International Civil Aviation Organization). Используется в авиационной навигации. Может меняться, но реже чем IATA. pattern: ^[A-Z]{4}$ example: UUDD Railway: type: object description: Вокзал required: - kind properties: kind: type: string enum: - Railway uic: type: string description: > Код железнодорожной станции по стандарту **UIC** (International Union of Railways). Используется в европейских системах железнодорожной логистики. pattern: ^[0-9]{7}$ example: '9700023' esr: type: string description: > Идентификатор железнодорожной станции в системе РЖД (Российские железные дороги) и ряде стран СНГ. Он известен как код "Единой сетевой разметки" (ЕСP). pattern: ^[0-9]{6}$ example: '031812' BusinessDay: type: object required: - day - times properties: day: type: integer description: | День недели в виде числа: 1 — понедельник, 7 — воскресенье. example: 1 enum: - 1 - 2 - 3 - 4 - 5 - 6 - 7 times: type: object description: | Детализация времени работы для указанного дня. required: - type - detail example: type: SPECIAL detail: от первого рейса до последнего properties: type: type: string enum: - STANDARD - SPECIAL description: > Тип расписания: • `STANDARD` — используется стандартный формат времени, где указаны интервалы в формате HH:mm–HH:mm. • `SPECIAL` — используется текстовое описание (например, «с первого рейса до последнего»). detail: type: string description: > Детали расписания. Формат зависит от значения `type`: • Если `STANDARD`, строка содержит интервалы времени, разделённые запятыми. Пример: `08:00-12:00,14:00-20:00` • Если `SPECIAL`, строка содержит текстовое описание. Пример: `от первого рейса до последнего` example: 08:00-12:00,14:00-20:00 responses: NotModified: description: > Ресурс не был изменен с момента последнего запроса. Возвращается, когда: - Заголовок `If-None-Match` совпадает с текущим `ETag` ресурса, или - Заголовок `If-Modified-Since` указывает на дату позже или равную `Last-Modified` ресурса. Тело ответа отсутствует, что позволяет экономить трафик при повторных запросах к каталогам. headers: ETag: $ref: '#/components/headers/ETag' Last-Modified: $ref: '#/components/headers/LastModified' Unauthorized: description: | Ошибка аутентификации. Возвращается в следующих случаях: - **Отсутствует или недействителен клиентский сертификат (mTLS)**: Запрос не содержит валидный клиентский сертификат или сертификат не прошел проверку. - **Отсутствует или недействителен Bearer токен**: Заголовок `Authorization` отсутствует, имеет неверный формат, или токен истек/недействителен. - **Неверный формат токена**: Токен не является валидным JWT или имеет неверную структуру. content: application/json: schema: $ref: '#/components/schemas/Error' examples: missing_mtls: summary: Отсутствует клиентский сертификат value: code: Unauthorized title: Unauthorized status: 401 instance: / detail: Требуется клиентский сертификат для mTLS аутентификации request_id: f2c8a9f6-1234-5678-9abc-def012345678 invalid_mtls: summary: Недействительный клиентский сертификат value: code: Unauthorized title: Unauthorized status: 401 instance: / detail: Клиентский сертификат не прошел проверку request_id: f2c8a9f6-1234-5678-9abc-def012345678 missing_bearer: summary: Отсутствует Bearer токен value: code: Unauthorized title: Unauthorized status: 401 instance: / detail: Требуется Bearer токен в заголовке Authorization request_id: f2c8a9f6-1234-5678-9abc-def012345678 invalid_token: summary: Недействительный или истекший токен value: code: Unauthorized title: Unauthorized status: 401 instance: / detail: Токен истек или недействителен request_id: f2c8a9f6-1234-5678-9abc-def012345678 Forbidden: description: > Недостаточно прав для выполнения операции. Возвращается в следующих случаях: - **Отсутствует необходимый scope в токене**: Токен валиден, но не содержит требуемый scope для данной операции. Например, для операции бронирования требуется scope `booking.lounges:write`, а в токене присутствует только `catalog.lounges:read`. - **Неверный audience (aud) в токене**: Поле `aud` в JWT не соответствует ожидаемому значению для данного API. content: application/json: schema: $ref: '#/components/schemas/Error' examples: missing_scope: summary: Отсутствует необходимый scope value: code: Forbidden title: Forbidden status: 403 instance: /v2/b2b/booking/lounges detail: >- Недостаточно прав для операции (требуется scope: booking.lounges:write) details: required_scope: booking.lounges:write provided_scopes: - catalog.lounges:read request_id: f2c8a9f6-1234-5678-9abc-def012345678 invalid_audience: summary: Неверный audience в токене value: code: Forbidden title: Forbidden status: 403 instance: /v2/b2b/booking/lounges detail: Токен выдан для другого API (неверный audience) details: expected_aud: https://api.every.ru/business-lounges provided_aud: https://api.every.ru/other-service request_id: f2c8a9f6-1234-5678-9abc-def012345678 InternalError: description: Внутренняя ошибка сервиса content: application/json: schema: $ref: '#/components/schemas/Error' example: code: InternalError title: Внутренняя ошибка сервиса status: 500 instance: / detail: Внутренняя ошибка сервиса request_id: xxxx ServiceUnavailable: description: > Сервис временно недоступен. Клиент может повторить запрос позже. Рекомендуется использовать экспоненциальную задержку между повторными попытками. headers: Retry-After: $ref: '#/components/headers/RetryAfter' content: application/json: schema: $ref: '#/components/schemas/Error' example: code: ServiceUnavailable title: Сервис временно недоступен status: 503 instance: / detail: Сервис временно недоступен request_id: xxxx ````