/
Экскурсии с набором опций: API v2 для получения опций и создания заказа

Экскурсии с набором опций: API v2 для получения опций и создания заказа

С мая 2026 года на Tripster появилась поддержка опций в заказе - это позволяет более гибко работать с дополнительными услугами. Для создания заказа с опциями мы подготовили новую версию API (v2).

1. Зачем нужен API v2

У части экскурсий цена теперь может складываться из нескольких опций (например, взрослый / ребёнок, доп. услуги с отдельной ценой и лимитами количества). В карточке такой экскурсии в поле pricing_model приходит значение composite. Для корректного бронирования необходимо получить список опций, показать их пользователю и передать выбранный состав при создании заказа.

Добавлены два метода под префиксом /api/partners/v2/:

Метод

Путь

Метод

Путь

GET

/api/partners/v2/<partner_name>/experiences/<id>/

GET

/api/partners/v2/<partner_name>/experiences/<id>/options/

 

Здесь <partner_name> — имя партнёра из URL вашего действующего партнёрского API, <id> — числовой ID экскурсии из каталога партнёра (как в предыдущей версии API).

Авторизация такая же, как для остальных ручек партнёрского API.

2. Как получить опции

  • Детальная информация (.../experiences/<id>/) — описание и цены в привычном формате, также массив options со списком опций.

  • Только опции (.../experiences/<id>/options/) — массив тех же объектов опции, без остальных полей карточки.

У каждой опции есть поле id — строка с UUID опции. Его нужно сохранять и подставлять в заказ (см. ниже). Ранее подобным образом использовались категории билетов.

3. Структура одной опции в ответе

Каждый элемент options (или каждый элемент ответа .../options/) содержит:

  • id — строка с уникальным идентификатором опции (UUID). Его нужно сохранять и передавать при создании заказа (см. раздел 5).

  • title, при необходимости description, category — для отображения пользователю.

  • kind — тип опции в терминах продукта (услуга, доп. опция и т.п.).

  • price и при наличии price_without_discount — объект с value (строкой с суммой) и currency (код валюты).

  • quantity — ограничения по количеству: минимум, максимум, значение по умолчанию, вид ограничения (например, флажок «да/нет» или счётчик).

  • display — уже отформатированные строки для UI (цена, единица и т.д.).

Число участников и допустимые комбинации опций могут дополнительно проверяться при создании заказа — ориентируйтесь на quantity и текст ошибок API, если состав не допустим.

4. Параметры запроса (важно для цены опций)

Опциональные query-параметры влияют на расчёт цен опций в ответе:

  • date_start, date_end — границы периода в формате YYYY-MM-DD. Неверный формат или случай date_start > date_end дают ошибку запроса.

  • price_format — влияет на то, как в карточке формируются строковые представления общей цены (детали — в вашей OpenAPI / схеме партнёров).

Некорректный формат дат или интервал при date_start > date_end даёт ошибку валидации запроса.

5. Получение цены заказа

Метод получения цены (/api/partners/<partner_name>/experiences/<id>/price/) теперь принимает параметр order_items в формате [{"id": "019df8c5-b266-74d3-99e5-6f5cdbdaf92a", "count": 3}, {“id“: “…“}]. Для экскурсий с композитной ценовой моделью необходимо передавать в него опции и их количество для получения корректной цены.

"order_items": [ { "id": "<значение options[].id — UUID строкой>", "count": <целое, не меньше 1> }, ... ]

Пример запроса цены:

/api/partners/<partner_name>/experiences/83305/price?persons_count=2&order_items=[{"id":"019df9ac-33a9-7104-84b1-dc5ba51bdffc","count":1},{"id":"019df9ac-33a9-7104-84b1-dc5ca322c3ee","count”:1}]&date=2026-07-31

6. Создание заказа (внешний заказ партнёра)

Создание внешнего заказа по-прежнему выполняется не через v2, а через существующий метод, например:

POST /api/partners/<partner_name>/external_orders/

Обязательно:

  • контакты путешественника: name, email, phone;

  • experience, date, time, persons_count;

  • для экскурсий с pricing_model = composite — состав заказа по опциям (см. ниже).

Опционально: expected_price (целое число, ожидаемая итоговая цена в рублях) — при несовпадении с фактической ценой заказа сервер вернёт ошибку и не зафиксирует заказ.

7. Как передать состав по опциям

Рекомендуемый способ — поле items в теле запроса: массив объектов

"items": [ { "id": "<значение options[].id — UUID строкой>", "count": <целое, не меньше 1> }, ... ]

  • id — тот идентификатор, что пришёл в options[].id при GET из раздела 2.

  • count — сколько единиц этой опции заказывается.

 

Альтернатива — старый формат tickets с числовым идентификатором, который вычисляется из строки UUID опции. Проще и надёжнее использовать items с UUID из ответа выше.

Альтернативный вариант tickets перестанет поддерживаться в октябре 2026, пожалуйста используйте рекомендуемый формат.

Итоговое persons_count должно быть согласовано с переданными опциями (в том числе со счётчиками участников, если они заданы отдельными опциями). При несоответствии или недопустимом наборе API вернёт ошибку с пояснением.

8. Краткий сценарий для партнёра

  1. Взять ID экскурсии из партнёрского каталога.

  2. Вызвать GET …/api/partners/v2/.../experiences/<id>/ или GET …/options/, при необходимости с date_start/date_end, чтобы показать актуальные цены опций.

  3. Если в карточке pricing_model = composite, использовать массив options для выбора тарифов.

  4. Запросить цену с передачей опций: GET …/api/partners/v2/.../experiences/<id>/price/

  5. Отправить POST …/external_orders/ с items, контактами, датой, временем, persons_count, expected_price