Авторизация

Каждый запрос к /api/v1/* должен содержать API-ключ партнёра в заголовке X-API-Key:

curl https://gateway.ticket.kg/api/v1/categories \
  -H "X-API-Key: ваш-ключ"

Методы /health и /ready доступны без ключа.

Как получить ключ

Ключ выдаёт менеджер Ticket.kg. Вместе с ключом согласуются:

• Комиссия партнёра — процент от продаж, который учитывается в отчёте о продажах.
• Список разрешённых IP-адресов (whitelist) — необязательно, но рекомендуется.
• Срок действия ключа — необязательно.

У одного партнёра может быть несколько ключей, например для тестовой и рабочей среды или для разных серверов.

Храните ключ в секрете

Ключ даёт полный доступ к бронированию, продаже и возврату билетов от имени вашей компании. Не передавайте его в браузер или мобильное приложение — обращайтесь к API только со своего сервера.

Как проверяется ключ

При каждом запросе шлюз проверяет:

1. Ключ существует и активен.
2. Срок действия ключа (если задан) ещё не истёк.
3. Партнёр, которому принадлежит ключ, активен.
4. IP-адрес клиента входит в whitelist ключа.

Результат	HTTP	error.code
Ключ не передан, не найден, отключён или истёк; партнёр отключён	401	unauthorized
IP-адрес не входит в whitelist ключа	403	forbidden

{
  "error": {
    "code": "unauthorized",
    "message": "invalid API key"
  },
  "request_id": "9f2c4e7a1b3d5f60718293a4b5c6d7e8"
}

Whitelist IP-адресов

Whitelist может содержать отдельные IP-адреса (IPv4 и IPv6) и подсети в формате CIDR:

203.0.113.10
203.0.113.0/24
2001:db8::/32

• Пустой whitelist разрешает запросы с любого IP.
• Если whitelist задан, запросы с других адресов получают 403 forbidden.
• Учитывается адрес, с которого запрос пришёл на наш балансировщик. Заголовок X-Forwarded-For, который вы передаёте сами, игнорируется — подделать IP через него нельзя.

Отключение и смена ключа

Результат проверки ключа кэшируется на стороне шлюза примерно на 1 минуту. Поэтому:

• отключённый или удалённый ключ перестаёт работать не мгновенно, а в течение минуты;
• изменение whitelist тоже вступает в силу в течение минуты.

Чтобы сменить ключ без простоя:

1. Попросите менеджера выпустить новый ключ.
2. Переключите свои серверы на новый ключ.
3. Попросите отключить старый ключ.

Изоляция данных партнёров

Каталог (категории, мероприятия, схемы залов) одинаков для всех партнёров. А заказы видны только партнёру, который их создал: запрос чужого заказа по id вернёт 404 not_found, как будто заказа не существует.