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

Changelog API

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

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-приёмник.