---
title: "Вступ · API Reference: документація AOA API"
description: "Публічний API AOA для пошуку закладів і подій, бронювання столиків та продажу квитків: базовий URL і формат відповідей."
canonical: "https://aoa.com.ua/docs/api-reference/introduction"
---

# Вступ

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

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

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

## Перший запит

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

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

Перевірити бронювання, оплату квитків і вебхуки, нічого не створивши насправді, можна в [пісочниці](https://aoa.com.ua/docs/api-reference/sandbox): ті самі ендпоінти на тестових даних, тестовий ключ придумуєте самі.

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

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

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

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

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

Перевіряйте наявність `error`, а не HTTP-статус — так обробка не зміниться, якщо статус колись уточнять. Перелік кодів — на сторінці [Помилки](https://aoa.com.ua/docs/api-reference/errors).

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

| Дія | Ендпоінт | Потрібен ключ |
| --- | --- | --- |
| Знайти заклади | **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}` | Так |

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

1. Знаходите подію через **GET** `/events` і показуєте покупцеві ціни з `ticket-types`.
2. Поки покупець вводить дані, тримаєте місця через **POST** `/reservations` — крок необовʼязковий, але без нього популярні квитки можуть розібрати.
3. Створюєте платіж через **POST** `/checkout` і ведете покупця на `paymentUrl`.
4. Опитуєте **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](https://github.com/aoa-ua/aoa-agent-kit). SDK згенеровані з цієї специфікації й оновлюються разом з нею.

- TypeScript: `npm install @aoa-ua/sdk` ([npm](https://www.npmjs.com/package/@aoa-ua/sdk))
- Python: `pip install aoa-sdk` ([PyPI](https://pypi.org/project/aoa-sdk/))
- 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 днів до вимкнення, а дата вимкнення дублюється в документації.