← API для разработчиков

Changelog API

История изменений публичного API ROOM. Все записи ниже — аддитивные в рамках мажора /v1 (текущая ревизия 2026-10-19). Breaking changes выходили бы новым мажором (/v2) с окном 12 мес — политика на странице разработчика. Следите за заголовками Deprecation / Sunset.

2026-10-19

  • Измененоprice у тарифа, места, легенды схемы и availability — ТЕКУЩАЯ цена: ровно то, что спишет POST /orders в этот момент (с учётом цены по датам и скидки). Раньше там была базовая цена даже при активной скидке. Базовая (финальная) цена — новое поле list_price; min_price/max_price — тоже текущие.
  • ДобавленоЦена по датам: next_price и next_price_at — цена после ближайшего изменения и момент изменения (null — изменений впереди нет). next_price выше price — цена скоро вырастет.
  • ДобавленоСтол целиком: sale_unit (seat | table) у тарифа и зоны; у зоны table_price, table_list_price, table_next_price, table_next_price_at, table_available. Такой стол удерживается одним POST /seat-holds со ВСЕМИ его местами: в ответе объект table (цена за стол один раз), у мест price = 0 и sold_as_table = true. Частичный выбор мест стола или стол вместе с другими местами → 400 invalid_request (param seat_ids).
  • ДобавленоНовое значение статуса места: not_for_sale — место не продаётся (нет тарифа в продаже или организатор закрыл его). Это не «занято»: выбирать такое место нельзя.
  • ИзмененоPOST /seat-holds: не больше 12 мест за раз (seat_ids.maxItems = 12) — стол до 12 мест помещается в один холд.
  • ДобавленоСхема зала у повторяющихся событий: места продаются ПО СЕАНСАМ — у каждого сеанса свои брони и своя цена. Передавайте occurrence_id в GET /events/{id}/seating, /availability и /tiers и в POST /seat-holds (там он обязателен: без него — 400 invalid_request, param occurrence_id). Без occurrence_id /seating показывает все места повторяющегося события как not_for_sale.
  • ДобавленоGET /events/{id}/tiers?occurrence_id= — цена, остаток и is_on_sale конкретного сеанса (у сеанса может быть своя цена). В ответе новые поля occurrence_id и price_is_template: true — у повторяющегося события запрошено без сеанса, цены шаблонные. Неизвестный или неопубликованный сеанс — 404.
  • ИзмененоРевизия ROOM-Version и api_version конверта вебхуков — 2026-10-19 (была 2026-06-01). Формат вебхуков не менялся.

2026-06-26

  • ДобавленоGET /health (без ключа) — лёгкая проба доступности для аптайм-мониторинга: 200 {status:"ok"} когда приложение и база отвечают, 503 {status:"degraded"} при сбое. Новый раздел «Доступность (SLA) и /health» на странице разработчика с целевыми показателями (uptime/латентность).
  • ИзмененоУточнена семантика Idempotency-Key при создании заказа: ключ привязан к заказу на всю его жизнь (TTL нет), повтор возвращает заказ в его текущем состоянии (вкл. paid/refunded). По отменённому заказу повтор → 409 order_cancelled — нужен свежий ключ. Правило: один логический заказ = один новый ключ (поведение прежнее, теперь явно задокументировано).
  • БезопасностьВебхуки: новый эндпоинт теперь нужно подтвердить (proof-of-ownership) перед получением событий. Нажмите «Подтвердить владение» — ROOM пришлёт конверт type=endpoint.verify с data.nonce, ваш сервер должен вернуть этот nonce в 2xx-ответе. Существующие эндпоинты подтверждены автоматически. Смена URL сбрасывает подтверждение.
  • БезопасностьАнти-злоупотребление вебхуками: лимит исходящих запросов на один домен-получатель и глобально (ROOM не «долбит» чужой сервер). Превышение → доставка откладывается (не теряется).
  • БезопасностьУтёкший секретный ключ (sk_): автодетект аномального использования с большого числа разных IP за сутки → владельцу приходит уведомление (рекомендуем сразу ограничить ключ IP-allowlist или перевыпустить).
  • БезопасностьСекретные ключи (sk_) можно ограничить списком разрешённых IP/CIDR (allowedIps) в бэкстейдже — утёкший ключ бесполезен вне ваших egress-адресов. Запрос с другого IP → 403 ip_not_allowed.
  • ДобавленоНовый код ошибки ip_not_allowed (403) для sk_-ключей с IP-allowlist.
  • ИзмененоВебхуки: умнее авто-отключение мёртвых эндпоинтов (эндпоинт, который ни разу не доставил успешно, или молчит более 3 дней, отключается быстрее). Никаких изменений контракта доставки.
  • ДобавленоДокументированы гарантии порядка вебхуков: порядок доставок НЕ гарантирован — трактуйте события как состояние (status/is_paid), реконсайльте по created_at, дедуплицируйте по id конверта.

2026-06-25

  • ДобавленоРефанды через API: POST /orders/{id}/refund (sk_, orders:write) — полный возврат оплаченного TICKET-заказа; событие order.refunded приходит, когда деньги фактически дошли.
  • ДобавленоИстория доставок вебхуков и ручная переотправка через API (scope webhooks:manage).

2026-06-24

  • ДобавленоGET /ping — whoami по любому валидному ключу (id, тип, окружение, scopes, organizer_id, поддерживаемые события вебхуков).
  • ДобавленоПоиск/фильтр/сортировка событий: GET /events?q=&city=&starts_after=&scope=upcoming|past|all&sort=. Новый GET /events/by-slug/{slug}.
  • ДобавленоПолучение билетов/QR оплаченного заказа: GET /orders/{id}/tickets (sk_, orders:read).
  • ДобавленоЗаголовок ROOM-Version на каждом ответе + сниппеты верификации вебхуков на Python/PHP/Ruby/Go/C#.

2026-06-23

  • ДобавленоЗаголовок ROOM-Request-Id на каждом ответе (для саппорт-корреляции) + X-RateLimit-* на всех успешных ответах.
  • ДобавленоФильтры списка заказов (status/event_id/created_after/before), полнота полей заказа (quantity/event_id/ticket_tier_id/occurrence_tier_id), opaque-курсор пагинации + has_more.
  • ДобавленоМашиночитаемый каталог кодов ошибок и OpenAPI 3.1 (/api/public/v1/openapi.json + /developers/reference).
  • ДобавленоСимуляция оплаты в test-режиме: POST /orders/{id}/simulate-payment (sk_test) — довести тестовый заказ до paid/cancelled и проверить webhook-приёмник.