Тема

Общие соглашения ​

Формат успешного ответа ​

Успешный ответ всегда содержит объект или массив в поле data:

json
{
  "data": { "id": 1978, "name": "..." }
}

Списковые методы дополнительно возвращают pagination:

json
{
  "data": [ ... ],
  "pagination": {
    "limit": 100,
    "page": 1,
    "count": 37,
    "total": 37
  }
}

Формат ошибки ​

json
{
  "error": {
    "code": "seat_unavailable",
    "message": "some seats are not available",
    "details": { "seats": [101] }
  },
  "request_id": "9f2c4e7a1b3d5f60718293a4b5c6d7e8"
}
  • code — машиночитаемый код. Ориентируйтесь на него, а не на текст message.
  • message — описание на английском для логов и отладки. Текст может меняться.
  • details — дополнительные данные; присутствует не всегда.

Полный список кодов — в разделе Ошибки.

Пагинация ​

Методы GET /events и GET /events/{eventID}/items поддерживают постраничную загрузку.

ПараметрПо умолчаниюОписание
limit100Размер страницы. Максимум 500 — бо́льшие значения молча уменьшаются до 500
page1Номер страницы, начиная с 1

Поля pagination в ответе:

ПолеОписание
limitПрименённый размер страницы
pageНомер текущей страницы
countСколько элементов на этой странице
totalСколько элементов всего

Неположительные или нечисловые limit и page дают 400 invalid_pagination.

Пример обхода всех страниц:

js
let page = 1
const all = []
while (true) {
  const res = await fetch(`https://gateway.ticket.kg/api/v1/events?limit=100&page=${page}`, {
    headers: { 'X-API-Key': KEY }
  }).then(r => r.json())
  all.push(...res.data)
  if (page * res.pagination.limit >= res.pagination.total) break
  page++
}

Даты и время ​

  • Все даты — в формате RFC 3339 с часовым поясом Кыргызстана: 2026-11-15T19:00:00+06:00.
  • В Кыргызстане нет перехода на летнее время, смещение всегда +06:00.
  • Даты в параметрах отчёта о продажах передаются как YYYY-MM-DD и тоже трактуются по времени Бишкека.

Деньги ​

  • Все суммы — целые числа в сомах, валюта KGS.
  • Комиссия и сумма к перечислению в отчёте — дробные числа с точностью до двух знаков.

Идентификаторы ​

СущностьТипПример
Мероприятие, сеанс, категория, место, зона, цена, билетцелое число2505
Заказ (order.id)строка UUID"3f6c2a1e-8b4d-4c7a-9e2f-1a2b3c4d5e6f"
Ваш номер заказа (partner_order_id)строка до 255 символов"ORD-1001"

Request ID ​

Каждый ответ содержит заголовок X-Request-ID. Вы можете передать свой X-Request-ID в запросе — шлюз вернёт его же. Иначе шлюз сгенерирует случайный.

В ответах с ошибкой request_id дублируется в теле. Указывайте его, когда обращаетесь в поддержку — по нему мы найдём запрос в логах.

Кэширование каталога ​

Ответы методов GET /categories, GET /events и GET /events/{eventID} кэшируются на стороне шлюза до 10 минут. Ответ из кэша помечается заголовком X-Cache: HIT.

Это значит, что новое мероприятие или изменение описания может появиться в API с задержкой до 10 минут.

Методы, от которых зависит продажа, не кэшируются и всегда возвращают актуальные данные:

  • GET /events/{eventID}/items — сеансы;
  • GET /event-items/{eventItemID}/seats — места, зоны, остатки;
  • все методы заказов и отчётов.

TIP

Перед бронированием всегда запрашивайте /event-items/{id}/seats, а не полагайтесь на данные каталога: сеанс мог закрыться с момента загрузки списка мероприятий.

Таймауты ​

Шлюз обрабатывает запрос не дольше 5 секунд. Рекомендуем ставить таймаут клиента 10–15 секунд и при сетевой ошибке повторять запрос. Для создания заказа повтор безопасен благодаря partner_order_id.

Ticket.kg • © 2026