API Reference

Резервування

Тимчасове утримання квитків на 15 хвилин, поки покупець ухвалює рішення.

POST/reservations · дозвіл reservations:write

Резерв утримує місця 15 хвилин, поки покупець вводить дані. Крок необовʼязковий — можна одразу створювати платіж, — але на подіях, де квитки розбирають швидко, він рятує від ситуації «покупець заповнив форму, а місць уже немає».

Запит

cURL

curl -X POST https://aoa.com.ua/api/v1/reservations \
  -H "Authorization: Bearer aoa_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "eventId": "a1b2c3",
    "tickets": [
      { "ticketTypeId": "clx9ticket001", "quantity": 2 }
    ]
  }'

Поле	Тип	Опис
`eventId`	string	Ідентифікатор події. Обовʼязкове.
`tickets`	array	Непорожній масив позицій. Обовʼязкове.
`tickets[].ticketTypeId`	string	Тип квитка з ендпоінта ticket-types.
`tickets[].quantity`	integer	Ціле від 1 до 20 — на кожен тип окремо.

Відповідь

JSON

{
  "data": {
    "reservationId": "rsv_Xk3mQp7vR2nT8wL5yB1zC4dA",
    "eventId": "a1b2c3",
    "expiresAt": "2026-07-30T12:49:56.789Z",
    "remaining": {
      "clx9ticket001": 61
    }
  }
}

Поле	Опис
`reservationId`	Передайте його в /checkout, щоб перетворити резерв на оплату.
`expiresAt`	Коли резерв згорить. Показуйте покупцеві таймер, щоб він розумів обмеження.
`remaining`	Залишок після вашого резерву, по кожному типу квитка.

Коли місць не вистачає

Резерв або створюється повністю, або не створюється взагалі — часткових резервів не буває. Якщо квитків менше, ніж просите:

JSON

{
  "error": {
    "code": "conflict",
    "message": "Залишилось лише 1 квиток"
  }
}

Візьміть актуальні залишки з /availability і запропонуйте покупцеві меншу кількість. Повторювати той самий запит без змін немає сенсу.

Життєвий цикл резерву

Скасувати резерв вручну не можна — окремого ендпоінта немає. Якщо покупець передумав, просто не використовуйте резерв: за 15 хвилин місця повернуться самі.
Успішний /checkout з цим резервом споживає його.
Якщо оплата не створилась через сторонню причину — скажімо, невалідний промокод — резерв залишається живим. Виправте дані й спробуйте ще раз із тим самим reservationId.

Резервуйте тоді, коли треба

Резерв забирає місця в інших покупців. Створюйте його, коли покупець уже обрав квитки й переходить до оплати, а не на етапі перегляду афіші.