API Reference

Вступ

Публічний API AOA для пошуку закладів і подій, бронювання столиків та продажу квитків: базовий URL і формат відповідей.

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

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

Перший запит

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

cURL

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

Перевірити бронювання, оплату квитків і вебхуки, нічого не створивши насправді, можна в пісочниці: ті самі ендпоінти на тестових даних, тестовий ключ придумуєте самі.

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

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

JSON

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

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

JSON

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

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

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

Дія	Ендпоінт	Потрібен ключ
Знайти заклади	GET`/locations`	Ні
Перевірити вільний час	GET`/locations/{locationId}/availability`	Ні
Забронювати столик після підтвердження	POST`/table-reservations`	Так
Знайти події	GET`/events`	Ні
Деталі події	GET`/events/{eventId}`	Ні
Типи квитків і ціни	GET`/events/{eventId}/ticket-types`	Ні
Скільки лишилось місць	GET`/events/{eventId}/availability`	Ні
Притримати квитки на 15 хвилин	POST`/reservations`	Так
Створити платіж	POST`/checkout`	Так
Статус замовлення	GET`/orders/{paymentId}`	Так

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

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

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

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

Це server-to-server API

Ендпоінти не віддають CORS-заголовків, тому викликати їх напряму з браузерної сторінки не вийде. Ключ і так не можна показувати на клієнті — тримайте виклики на своєму сервері.

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

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

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

SDK і Agent Skills

Офіційні SDK для TypeScript, Python і Go, скіли для AI-агентів і конфіги для асистентів розробки (AGENTS.md, plugin.json) лежать у відкритому репозиторії github.com/aoa-ua/aoa-agent-kit. SDK згенеровані з цієї специфікації й оновлюються разом з нею.

TypeScript: npm install @aoa-ua/sdk (npm)
Python: pip install aoa-sdk (PyPI)
Go: go get github.com/aoa-ua/aoa-agent-kit/sdk/go

Версіонування

Версіонування: версія в шляху (/api/v1). Зміни, що ламають сумісність, виходять лише в новій версії. Кожна відповідь API несе заголовок Link з rel="deprecation" і rel="sunset", який веде на сторінку цієї політики. Застарілий ендпоінт додатково позначається заголовками Deprecation і Sunset (RFC 9745, RFC 8594) щонайменше за 90 днів до вимкнення, а дата вимкнення дублюється в документації.