Партнёрский API организации (API-ключи)

HTTP-API, по которому сторонний партнёр владельца клуба читает данные его организации: касса, система лояльности, сайт с онлайн-записью, собственная витрина сети. Ключ выдаёт владелец в панели (раздел API-ключи), он же решает, что ключу доступно и до какого момента он работает.

Это не протокол игровой станции (он работает по WebSocket) и не API мобильного приложения клиента — это отдельные контракты. Здесь нет клиентских сессий и авторизации человека: запрос приходит от программы партнёра и опознаётся ключом.

Postman. Для импорта готовы два файла:

Импортируйте оба (*Import* → перетащить файлы), выберите окружение в правом верхнем углу и впишите в него api_key. Ключ держите в окружении, а не в коллекции: коллекцию передают и экспортируют, а окружение остаётся у вас.

Дальше можно запускать Runner'ом целиком — списки запоминают id первого элемента, поэтому gs.get, product.get, session.get, order.get и chat.messages работают без ручного ввода. Папки 1–7 ждут ответа 200, то есть рассчитаны на ключ с полным доступом; ключ с урезанными правами законно ответит 403 forbidden_action на недоступные действия — что именно ему доступно, говорит meta.actions.

---

1. Где взять ключ

Ключ выдаёт владелец клуба в своей панели: раздел API-ключи → «Создать». Там же он выбирает, что ключу доступно и до какого момента он работает, поэтому просить ключ нужно вместе с перечнем нужных вам действий — владелец отметит именно их.

Что сказать владельцу:

• какие данные нужны — по действиям из §4 (например gs.status, product.list); в карточке ключа он отмечает права с теми же названиями, что подписаны рядом с действием;
• на какой срок — ключ можно выдать на день, неделю, месяц, год, до конкретной даты или бессрочно;
• нужен ли журнал обращений — если интеграцию ещё отлаживают, владелец включает галочку и видит ваши запросы (см. §8).

Готовый ключ он передаёт вам как пароль. В списке ключей он виден маской (первые и последние четыре символа), целиком — в карточке, откуда его и копируют.

Подробнее со стороны владельца — в руководстве пользователя SpikePC, раздел API-ключи.

Ключ не привязан к клубу: он действует на всю организацию, а конкретный клуб вы указываете параметром club_id.

---

2. Транспорт

POST https://spikepc.com/dev/spike_api/
X-Api-Key: 7b2d4f9a1c3e5d7f9b0a2c4e6f8a0b1d
Content-Type: application/json
 
{ "action": "gs.list", "v": 1, "data": { "club_id": 3, "limit": 50, "offset": 0 } }

Адрес указывайте со слэшем на конце (/spike_api/). Без слэша веб-сервер отвечает редиректом на адрес со слэшем, а тело POST-запроса при редиректе теряется — запрос придёт пустым и получит 400 bad_request.

Тот же обработчик доступен и по внутреннему адресу ?loc=spike_user_api_request — он остаётся рабочим, но в интеграциях используйте /spike_api/.

v — версия контракта, необязательна (сейчас 1).

---

3. Ответ

Тот же конверт, что у станции и мобильного приложения; code дублируется в HTTP-статусе:

{
  "code": 200,
  "error_key": "",
  "error_text": "",
  "action": "gs.list",
  "data": { "items": [ … ], "total": 38, "limit": 50, "offset": 0 }
}

• error_key — стабильный машинный код, на него и опирайтесь. error_text — пояснение по-английски, его формулировка может меняться.
• data всегда объект (при ошибке — {}): в объект можно добавить поле, не ломая разбор. Списки — items + total + limit/offset, одна запись — item.
• action — эхо запрошенного действия, удобно при асинхронной очереди на стороне партнёра.

Коды и ключи ошибок

---

4. Действия

Что делать — говорит поле action. Точка входа одна, поэтому добавление метода не меняет адрес и не требует правок на стороне партнёра. Право каждого действия — это имя функции панели: оно подписано в карточке ключа рядом с пунктом прав, и именно его владелец отмечает, чтобы открыть партнёру действие.

Действия этого раздела только читают. Изменяющие — в §5.

Служебные (без права)

Клуб и зал

Каталог

search у товаров ищет по названию, артикулу и штрихкоду. locale подменяет name и description переводом этой локали; нет перевода — остаётся базовое значение, пустым ответ не приходит.

club_id у товаров обязателен: цена у товара своя в каждом клубе, и без клуба пришлось бы отдавать «цену вообще» — партнёр продавал бы по чужой. Если в этом клубе цены нет, приходит price: null и available: false — товар здесь не продаётся.

Время доступности товара приходит полем hours — по строке на день недели: [{day, from_sec, to_sec}], где day 0=Пн … 6=Вс, а from_sec/to_sec — секунды от полуночи. Пустой массив означает, что товар продаётся круглосуточно. to_sec — последняя включённая секунда (окно «18:00–22:00» приходит как 64800…79259), а to_sec меньше from_sec — это окно через полночь: отмеченный день задаёт начало, конец приходится на следующие сутки. Рядом идёт готовый ответ hours_open (true/false — продаётся ли прямо сейчас): считать это самому пришлось бы и по нашей конвенции границ, и в нашем часовом поясе. На поле available расписание не влияет — оно по-прежнему про цену в клубе и активность товара.

Тарификация

Границы интервалов расписания включительные, причём time_end — последняя включённая секунда блока (час 13 → 50399 = 13:59:59). В ответе рядом с секундами идут готовые from/to, чтобы не повторять эту конвенцию у себя и не терять последний час.

Две сетки абонемента — разные: kind=sale отвечает «когда его можно купить», kind=valid — «когда купленное можно тратить». Пустая сетка действия означает «действует всегда».

У бонусной кассы balance приходит null, а не ноль: бонусы — не живые деньги в кассе.

Клиенты и деньги

search у клиентов ищет по почте, телефону, логину, имени и фамилии. Телефон в client.get ищется во всех форматах, в которых он мог сохраниться (380…, +380…, 0…, 38…) — импорт и регистрация писали его по-разному.

Служебные гостевые записи станций (гостевая постоплата) в выдачу клиентов не попадают. Заметки оператора и аватар наружу не отдаются.

Остаток абонемента считается по стенным часам: активированный абонемент горит с момента активации, поэтому remaining_seconds не покажет время, которое уже сгорело, пока клиент не играл.

Сессии, заказы, брони, чат

У активной сессии итог ещё копится, поэтому в ответе есть active: true — не принимайте промежуточную сумму за окончательную.

Заказ не списывает баланс клиента — его платят на месте персоналу, поэтому total_amount это сумма к оплате, а не проведённый платёж.

Период у броней считается по пересечению, а не по началу: бронь, начавшаяся вчера и идущая сейчас, попадает в выборку за сегодня.

У диалогов total — число диалогов, а не сообщений.

Организация

org.info не отдаёт реквизиты: ни доступов к БД, ни SMTP, ни токенов Telegram, ни gs_token станций, ни баланса организации. Право «просмотр настроек» выдаётся сотруднику внутри панели, а здесь ответ уходит третьей стороне.

event.list не отдаёт снимки «до/после»: в них попадают поля целиком, включая пароли Windows клуба. Остаётся кто, когда, в каком разделе и над чем.

analytics.daily считает ночной крон в часовом поясе организации, поэтому текущий день обычно пуст — это не потеря данных: за сегодня берите живые gs.status, transaction.list, order.list. Период по умолчанию — последние 30 дней.

Страницы и фильтры

• limit — 50 по умолчанию, максимум 200; offset — с нуля. В ответе возвращаются оба.
• date_from / date_to — YYYY-MM-DD либо YYYY-MM-DD HH:MM:SS. Дата без времени в date_to означает сутки целиком, иначе 2026-10-01 отрезал бы весь день, оставив полночь.
• Значения фильтров-перечислений (status, type, kind) сверяются с белым списком: чужое значение — 422 bad_params, а не тихо проигнорированный фильтр.

Пример: живое состояние зала

→ { "action": "gs.status", "data": { "club_id": 3 } }
 
← { "code": 200, …, "data": { "items": [
      { "gs_id": 587, "club_id": 3, "number": "2",
        "online": true, "mode": "active",
        "busy": true, "client_id": 1402, "started_at": "2026-10-01 14:05:11",
        "time_left": { "seconds": 4260, "text": "1:11", "unlimited": false } }
    ], "total": 38, "server_time": "2026-10-01 16:10:59" } }

time_left и online считаются тем же кодом, что и карта клуба, поэтому партнёр и оператор видят одну и ту же цифру.

---

5. Запись

Эти действия меняют данные клуба: принимают деньги, продают абонемент, двигают заказ, создают бронь, выдают скидку и кредит, шлют команду станции. Права у них свои — владелец отмечает их в карточке ключа отдельно от просмотра, поэтому «посмотреть» и «изменить» не выдаются одной галочкой.

Правила те же, что у оператора в панели: без открытой кассовой смены деньги не принимаются, абонемент сверх лимита организации не продаётся, бронь в закрытые часы не создаётся. Это не «похожие проверки» — обе стороны зовут один и тот же код, поэтому партнёр не может то, что запрещено оператору.

Деньги

Касса обязательна (payment_method_id), и список её берут из payment_method.list. Для бонусной кассы обязателен comment — бонус без пояснения не принимаем, иначе на вопрос «за что начислено» ответить нечем. Если касса общая для организации, а клубов несколько, нужен club_id: без него операция потерялась бы для отчётов клуба.

Нужна открытая кассовая смена в этом клубе, иначе 409 no_shift. Смену открывает кассир в панели — это не обходится по API: деньги должны принадлежать чьей-то смене.

Возврат (transaction.refund) возможен только для пополнения и только один раз; списание разрешено «в минус» — деньги вернули из кассы, значит с баланса они уходят целиком.

Продажа абонемента списывает с баланса клиента, учитывая его перманентную скидку (если абонемент её допускает). Пакет кладётся в запас: часы стартуют при активации на станции, а не при продаже, иначе купленный впрок абонемент сгорел бы до прихода клиента.

Зал

Скидка: за станцией клиент — процент идёт снимком в его сессию (справочник потом правят, а человек доигрывает на обещанном); станция свободна — заявка ждёт того, кто сядет, 30 минут.

Кредит — разрешённая глубина минуса до конца сессии, а не зачисление денег: клиент доигрывает в долг и гасит его обычным пополнением. Нужна активная клиентская сессия.

Команды: разрешены только message, poweroff, poweron и session_end. Режимы станции, золотые образы и прочее управление залом остаются оператору — ими распоряжается клуб, а не внешняя система. В ответе delivery: done/delivered — станция приняла, offline — не на связи, timeout — не ответила за отведённое время.

Коды отказа записи

---

6. Права ключа

Область доступа ключа выбирает владелец:

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

Право каждого действия — это имя функции панели, и оно подписано в карточке ключа рядом с пунктом прав. То есть владелец видит ровно то, что сверяется при запросе: если партнёр получает forbidden_action на gs.list, в карточке ключа нужно отметить пункт с правом spike_gs_list.

Срок действия ключа проверяется на сервере: истёк — любой запрос отвечает key_expired (401), даже если партнёр об этом не знает.

---

7. Частота запросов

Лимит — 120 запросов в минуту на ключ (значение меняет администратор системы). При превышении приходит 429 rate_limited и заголовок Retry-After: 60.

Опрос состояния зала раз в 2–5 секунд в лимит укладывается с запасом. Если нужно чаще — попросите владельца клуба поднять лимит, а не обходите его несколькими ключами: лимит считается на ключ именно для того, чтобы один партнёр не мешал другим.

---

8. Журнал обращений

Владелец может включить в карточке ключа журнал обращений: тогда каждый вызов по этому ключу хранится 7 дней — действие, код ответа, длительность, IP и тело запроса (ключ из тела вырезается). Это инструмент разбора «у партнёра не работает»: постоянно журнал не нужен.

Если ваш запрос получает отказ, а причина непонятна, попросите владельца включить журнал и повторите запрос — в журнале будет видно и действие, и код, и то, что именно вы прислали.

---

9. Чего в этом API нет

Правки справочников. Тарифы, абонементы, товары, клубы, станции, сотрудники, права, настройки организации по API не меняются — это делают в панели. Партнёру нужно работать с клиентами и залом, а не переписывать настройки клуба, и каждая такая правка требовала бы своих проверок формы.

Список ключей. По ключу нельзя прочитать spike_apikeys: партнёр увидел бы ключи других партнёров этой же организации.

Структуру прав панели (access_groups_list) не отдаём: внешней системе она ни о чём не говорит, а в ответе появлялись бы имена наших внутренних функций.

Чувствительные поля вырезаны даже там, где право на раздел есть: реквизиты БД, SMTP и токены ботов (org.info), пароли Windows клуба и снимки «до/после» (event.list), заметки оператора о клиенте (client.*), пароли сотрудников (staff.list). Из персональных данных gs.status отдаёт только client_id — без имени, телефона и почты.

---

10. Вебхуки: события сами приходят к вам

Чтобы не опрашивать API в поисках нового заказа, укажите владельцу клуба свой адрес — и события будут приходить на него сами. Настраивается в панели организации (карточка «Клиенты и заказы»): адрес, выключатель, ключ подписи и список событий.

Запрос: POST <ваш адрес>, тело — JSON:

{ "event": "order.new",
  "org_id": 11,
  "sent_at": "2026-10-08T12:46:08+03:00",
  "data": { "order_id": 42, "club_id": 1, "gs_id": 11, "client_id": 35839,
            "total": 320.00, "items": 3 } }

Заголовки: X-Spike-Event (имя события), X-Spike-Org (организация) и X-Spike-Signature — подпись тела.

События

Организация может подписаться на часть событий — тогда придут только они.

Подпись: проверяйте её

X-Spike-Signature: sha256=<hex> — это HMAC-SHA256 от тела запроса целиком на ключе, который владелец клуба задал в настройках. Считайте подпись сами и сравнивайте с заголовком: без этой проверки на ваш адрес сможет писать кто угодно, выдавая себя за нас. Ключ не задан — заголовка не будет; просить владельца задать его стоит в любом случае.

# пример проверки (bash)
calc=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $2}')
[ "sha256=$calc" = "$SIG" ] || exit 1

Доставка

Отправку делает очередь, а не веб-запрос оператора: панель и сокет-сервис никогда не ждут ваш сервер. Отсюда правила, на которые стоит рассчитывать:

• таймауты — 5 секунд на соединение и 10 на весь обмен;
• три попытки с паузами (сразу, через 2 и через 5 секунд), пока ответ не 2xx;
• ответ 4xx (кроме 408 и 429) повторять не будем — считаем, что запрос отвергнут;
• редиректы не выполняются: Location игнорируется, POST по другому адресу не уйдёт;
• порядок событий не гарантирован, доставка как минимум один раз не гарантируется — если ваш сервер лежал все три попытки, событие потеряется. Критичное сверяйте чтением API: в нём есть и заказы, и сессии, и операции.

Отвечайте 200 как можно быстрее и обрабатывайте событие у себя асинхронно: пока вы держите соединение, задача очереди занята вами.