Вступ

API AOA дає доступ до опублікованих подій і дозволяє продавати на них квитки зі свого застосунку, бота чи AI-агента. Пошук подій і перегляд цін відкриті без ключа — ключ потрібен лише для резервування місць і оплати.

Базовий URL: https://aoa.com.ua/api/v1

Перший запит

Список найближчих подій у Києві. Ключ не потрібен:

curl https://aoa.com.ua/api/v1/events?city=Київ&limit=10

Формат відповіді

Усі відповіді мають однакову структуру. Успіх повертає обʼєкт із полем data, а списки додають meta:

{
  "data": [ … ],
  "meta": { "count": 10, "total": 42, "limit": 10 }
}

Помилка завжди приходить у полі error зі стабільним кодом:

{
  "error": {
    "code": "not_found",
    "message": "Event not found"
  }
}

Перевіряйте наявність error, а не HTTP-статус — так обробка не зміниться, якщо статус колись уточнять. Перелік кодів — на сторінці Помилки.

Що можна робити

Типовий сценарій продажу

1. Знаходите подію через GET /events і показуєте покупцеві ціни з ticket-types.
2. Поки покупець вводить дані, тримаєте місця через POST /reservations — крок необовʼязковий, але без нього популярні квитки можуть розібрати.
3. Створюєте платіж через POST /checkout і ведете покупця на paymentUrl.
4. Опитуєте GET /orders/{paymentId} раз на 5–10 секунд, доки статус не стане SUCCESS.

Квиток покупцеві надсилаємо ми: після успішної оплати лист із квитком іде на вказану пошту автоматично.

Про що варто знати одразу

• Час скрізь — ISO 8601 в UTC (2026-08-15T18:00:00.000Z).
• Гроші — цілі копійки в priceMinor. Поле priceDecimal дано для показу, рахувати завжди краще на копійках.
• id події у відповідях — це короткий публічний ідентифікатор, той самий, що в посиланні на сторінку події.

Специфікація OpenAPI

Машинно-зчитуваний опис доступний за адресою https://aoa.com.ua/api/v1/openapi.json — його можна згодувати генератору клієнтів або підключити до AI-агента. Ця документація описує поведінку точніше за специфікацію, тож у розбіжностях орієнтуйтесь на неї.