API Reference
API-ключі AOA: як отримати, як передавати в запиті, які scopes існують і що вони відкривають.
Пошук закладів і подій, деталі, вільний час і залишки квитків безкоштовні й працюють без реєстрації та API-ключа: 60 запитів на хвилину з IP. Ключ потрібен лише для дій, що змінюють стан: резервування, оплата, вебхуки.
Ключ передається у заголовку Authorization зі схемою Bearer. Усі ключі починаються з aoa_live_.
curl https://aoa.com.ua/api/v1/events \
-H "Authorization: Bearer aoa_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"Самостійної видачі ключів поки немає. Напишіть нам, розкажіть, що плануєте будувати, — ми створимо ключ і надішлемо його вам. Одразу оберемо потрібні дозволи: якщо інтеграція лише показує афішу, доступ до оплати їй не потрібен.
Поки ключа немає, інтеграцію повністю збирають у пісочниці: там працюють ті самі запити, а тестовий ключ aoa_test_… ви придумуєте самі, без звернення до нас.
Ключ показується один раз
Ми зберігаємо лише хеш, тож відновити ключ неможливо — якщо він загубився, ми відкликаємо старий і видаємо новий. Зберігайте його як пароль: у змінних середовища, ніколи в репозиторії чи в коді клієнта.Кожен ключ має набір дозволів. Ендпоінт перевіряє свій дозвіл окремо, тож ключ для показу афіші не зможе провести оплату.
| Дозвіл | Що відкриває |
|---|---|
events:read | Читання подій. Позначає намір інтеграції — самі ці ендпоінти відкриті й без ключа. |
reservations:write | POST/reservations — тимчасове утримання квитків; POST/table-reservations — підтверджене бронювання столика |
checkout:write | POST/checkout і GET/orders/{paymentId} |
Для повного циклу продажу потрібні reservations:write та checkout:write.
Кожен партнерський ключ привʼязаний до однієї організації. Це визначає, чиї дані ви отримуєте: вебхуки надходять лише про події та продажі вашої організації, а замовлення, створені вашим ключем, бачите тільки ви.
Дані інших організаторів через ваш ключ недоступні — ані їхні продажі, ані суми, ані скасування. Якщо працюєте з кількома організаціями, візьміть окремий ключ на кожну.
Читання подій — публічне
Ендпоінти афіші показують усі опубліковані події платформи, а не лише вашої організації: це та сама інформація, що на сайті. Привʼязка до організації обмежує саме приватні дані — вебхуки й замовлення.Ендпоінти подій працюють без ключа. Але ключ у запиті піднімає ліміт з 60 до 600 запитів на хвилину, тому надсилати його варто завжди — див. Ліміти запитів.
Запити на резервування, оплату й статус замовлення без ключа не проходять.
Невірний, відкликаний або відсутній там, де він потрібен, ключ дає 401:
{
"error": {
"code": "unauthorized",
"message": "Invalid API key"
}
}Якщо ключ дійсний, але не має потрібного дозволу — 403 із точною назвою того, чого бракує:
{
"error": {
"code": "forbidden",
"message": "Missing required scope: checkout:write"
}
}Різниця істотна: 401 означає проблему з самим ключем і повторювати запит немає сенсу, 403 — що ключ живий, але йому треба розширити дозволи. Напишіть нам, і ми це зробимо.