Публічний API подій

Пʼять запитів від ключа до штрихкода квитка. Приклади нижче налаштовані на тестове середовище — починайте з нього. Повний опис усіх методів — в інтерактивній документації, вона живе на тому ж хості, що й API.

Базовий URL
Префікс методів: /api/v2
Авторизація: Bearer JWT, 24 год
Пагінація: page · itemsPerPage ≤ 100

Два середовища

Набір методів, формати й поведінка однакові. Відрізняються адреса, дані та ключ.

Тест · почніть тут

Стейдж

https://st-pa.tbx.pp.ua

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

Документація стейджу →

Бій · після тестів

Прод

https://api.ticketcrm.net

Реальні події, реальні продажі. Переходите сюди, коли інтеграція пройшла перевірку на стейджі.

Документація проду →

Ключ у кожного середовища свій. Для бойового API ми видамо окремий, новий API Key — стейджевий там не працює. Перехід на прод — це рівно дві зміни: інша адреса в базовому URL і новий ключ. Код, структури відповідей і логіка лишаються ті самі.

Підставте свої значення

Усі приклади нижче оновляться. Нічого не зберігається і нікуди не надсилається — значення живуть лише у вашій вкладці.

API key

JWT-токен

id події

id місця

id тарифу

id замовлення

Токен ви отримаєте на кроці 1, id події та тарифу — на кроках 2 і 3, id замовлення — на кроці 4. Повертайтесь сюди й підставляйте їх по ходу. Адресу в усіх прикладах міняє селект «Базовий URL» вгорі сторінки; ключ для кожного середовища теж свій.

Смоук-тест за пʼять кроків

Порядок обовʼязковий: кожен крок дає ідентифікатор для наступного.

Отримати токен

Ключ обмінюється на JWT. Токен живе 24 години — кешуйте його, а не запитуйте перед кожним викликом. Ключ від стейджу працює тільки на стейджі; для проду буде виданий окремий.

curl -X POST "https://st-pa.tbx.pp.ua/api/v2/token" \
  -H "Content-Type: application/json" \
  -d '{"apiKey": "ВАШ_КЛЮЧ"}'

У відповіді: {"token": "eyJ0eXAiOiJKV1Qi…"}. Далі він іде заголовком Authorization: Bearer … у кожен запит.

Забрати каталог подій

Головний ендпоінт інтеграції. Під вашим ключем видно тільки ті події, які вам відкрили, і тільки ті, де продаж ще триває.

curl "https://st-pa.tbx.pp.ua/api/v2/event-points?itemsPerPage=20&order[dateStarted]=asc" \
  -H "Authorization: Bearer ТОКЕН" \
  -H "X-API-Language: uk"

# фільтри, які знадобляться на бою:
#   dateStarted[after]=2026-10-01&dateStarted[before]=2026-10-31
#   city.id[]=1&categories.id[]=3&genres.id[]=7&venueHall.id=42

Візьміть звідси: id події для наступного кроку. Довідники /cities, /countries, /venues, /venue-halls, /categories, /genres вивантажте окремо один раз і кешуйте.

Подивитись сектори і місця

Найважчий за обсягом блок — запитуйте його на відкритті конкретної події, а не по всьому каталогу.

curl "https://st-pa.tbx.pp.ua/api/v2/event-points/{eventPointId}/sectors" \
  -H "Authorization: Bearer ТОКЕН"

curl "https://st-pa.tbx.pp.ua/api/v2/event-points/{eventPointId}/places?itemsPerPage=100" \
  -H "Authorization: Bearer ТОКЕН"

Візьміть звідси: id вільного місця та id з його priceCategories — це тариф, який ви назвете в замовленні.

Створити замовлення

Замовлення одразу стає в статус reserved_to_time. Резерв за замовчуванням — 15 хвилин.

curl -X POST "https://st-pa.tbx.pp.ua/api/v2/orders" \
  -H "Authorization: Bearer ТОКЕН" \
  -H "Content-Type: application/json" \
  -d '{
    "eventPoint": "{eventPointId}",
    "places": ["{placeId}"],
    "priceCategory": "{priceCategoryId}",
    "reservedMinutes": 15
  }'

У відповіді: id замовлення, status, reservedToDate і totalPrice. Продовжити резерв — PUT /orders/{id}/reserve, дозбирати кошик — PUT /orders/{id}/add-place.

Оплатити і забрати штрихкоди

Оплату ви приймаєте у себе, а нам повідомляєте результат одним запитом: переводите замовлення в paid. Окремий запит за штрихкодами після цього не потрібен — вони вже у відповіді.

curl -X PUT "https://st-pa.tbx.pp.ua/api/v2/orders/{orderId}/status" \
  -H "Authorization: Bearer ТОКЕН" \
  -H "Content-Type: application/json" \
  -d '{"toStatus": "paid"}'

У відповіді — усе замовлення: status, totalPrice, totalDiscount і tickets, де кожен квиток має ticketId, barcode, placeId, placeName, sectorName, rowName, price і discountPrice. Цього вистачає, щоб зібрати свій бланк квитка.

Поза потоком: ще два ендпоінти

Обидва є в API, але в партнерському потоці вище не потрібні — не закладайте їх у свою інтеграцію без потреби.

GET /orders/{id}/payment-data: Дані платіжної системи для оплати на нашому боці: type і набір полів форми. Якщо оплату приймаєте ви — цей виклик пропускаєте.
GET /event-points/{id}/barcodes: Масове вивантаження всіх штрихкодів події — проданих у будь-якому каналі й непроданих. Працює лише для подій, де організатор — ваша компанія; на подіях, які ви продаєте як партнер, відповідає 403. Свої штрихкоди партнер бере з відповіді на оплату або з GET /orders/{id}.

curl "https://st-pa.tbx.pp.ua/api/v2/event-points/{eventPointId}/barcodes" \
  -H "Authorization: Bearer ТОКЕН"

У відповіді вивантаження: barcode, placeId, placeName, sectorId, sectorName — по одному запису на квиток.

Статуси замовлення

Через PUT /orders/{id}/status можна попросити тільки три з них.

created→reserved_to_time→paid→refund·expired — виставляє система

Де спотикаються найчастіше

Шість речей, через які інтеграція виглядає зламаною, хоча все працює як задумано.

порожня видача

Список подій приходить порожнім

Ключ бачить лише події, привʼязані до вашої компанії, і лише ті, де dateEndOfSale ще не минув. Завершені — окремим ендпоінтом /event-points-archived. Якщо очікуваної події немає — напишіть нам, це налаштування доступу.

availableCount

Розпродане місце не зникає

Воно залишається у відповіді з availableCount: 0, щоб ви могли закрити його у себе, а не показувати застарілу пропозицію. Орієнтуйтесь саме на це поле, а не на присутність місця у списку.

id ≠ eventId

Подія і сеанс — різні речі

id — це конкретний сеанс, ним ходять усі запити. eventId — спільний ідентифікатор події для всіх її дат: саме за ним групуйте «подія → розклад».

422

Ліміти задаємо ми

Максимум квитків в одному замовленні й максимум одночасно зарезервованих квитків на весь ваш акаунт налаштовані на нашому боці. Не зашивайте свої константи, ловіть 422 і читайте тіло відповіді. Непотрібні резерви краще знімати одразу — поки вони живі, вони зʼїдають ваш ліміт.

формат id

Ідентифікатори — числові рядки

У тілі запиту очікуються "places": ["456", "765"], а не URL-посилання на ресурси. Те саме для eventPoint і priceCategory.

401 · 429

Токен і темп запитів

401 означає, що 24 години минули — перезапросіть токен і повторіть виклик. 429 означає, що запитів забагато: потрібен backoff, а не цикл ретраїв.

Поля події, на які дивитись

Решта полів у документації; цих вистачає, щоб побудувати афішу і картку події.

id: Ідентифікатор сеансу — ним ходять усі інші запити
eventId: Спільний id події для всіх її дат
eventName · description: Назва й опис, у мові з X-API-Language
poster · media: Афіша та решта зображень
dateStarted · dateEnd: Початок і кінець сеансу
dateEndOfSale: Коли зупиняється продаж — після цієї дати подія йде в архів
venue · venueHall: Майданчик і конкретний зал
city · country: Для географічних фільтрів вашої вітрини
categories · genres: Рубрикація — мапиться на ваші довідники
minPrice · maxPrice: Діапазон цін: { amount, currency }
countAvailableTickets: Скільки квитків лишилось — достатньо для списку, без схеми залу
minAgeLimit · maxAgeLimit: Вікові обмеження
widgetHash: Ідентифікатор нашого віджета продажу для цієї події

Довідник ендпоінтів

Усі шляхи — від https://st-pa.tbx.pp.ua/api/v2.

Каталог
GET /event-points	Список подій: фільтри за датою, містом, країною, категорією, жанром, залом
GET /event-points/{id}	Одна подія
GET /event-points-archived	Події, у яких продаж уже завершився
Схема залу
GET /event-points/{id}/sectors	Сектори події
GET /event-points/{id}/sectors/{sectorId}/places	Місця одного сектора
GET /event-points/{id}/places	Усі місця події з цінами, тарифами й наявністю
Замовлення
POST /orders	Створити замовлення й зарезервувати місця
GET /orders/{id}	Стан замовлення, сума, знижка, дедлайн резерву; після оплати — квитки зі штрихкодами
PUT /orders/{id}/add-place	Додати місце до вже створеного замовлення
PUT /orders/{id}/tickets/{ticketId}/remove	Прибрати квиток із замовлення
PUT /orders/{id}/reserve	Продовжити час резерву
GET /orders/{id}/payment-data	Дані для оплати від платіжної системи — потрібні, лише якщо оплата йде через нас
PUT /orders/{id}/status	Змінити статус замовлення
PUT /orders/{id}/tickets/{ticketId}/status	Змінити статус окремого квитка
GET /event-points/{id}/orders	Ваші замовлення по події, без квитків; фільтри status і payAt[after]
GET /event-points/{id}/barcodes	Усі штрихкоди події, продані й непродані — лише для подій вашої компанії-організатора
Довідники
GET /countries · /cities	Географія
GET /venues · /venue-halls	Майданчики й зали
GET /categories · /genres	Рубрикація подій
GET /promocodes	Промокоди, доступні вашій компанії
Продажі через наш віджет
GET /widget-orders	Замовлення, зроблені у віджеті на вашому сайті
GET /widget-orders-refunds	Повернення по таких замовленнях

Коли смоук-тест пройшов

Перехід на бойове API. Змінюються дві речі: базовий URL на https://api.ticketcrm.net і новий API Key, який ми видамо окремо. Стейджевий ключ на проді не працює, решта коду лишається без змін.
Синхронізація. Робочий мінімум: каталог — раз на 5–15 хвилин, довідники — раз на добу, місця — на вимогу користувача.
Вебхуки замість полінгу. Якщо потрібен майже real-time — нова подія, оновлення події, продаж, повернення — дайте нам URL, ми налаштуємо відправку. Полінг тоді лишається як підстраховка.
Якщо щось не сходиться. Надішліть ендпоінт, час запиту й тіло відповіді — подивимось у себе. Адреса: support@ticketsbox.com.