Партнерський 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-ключі → «Створити». Там само він вибирає, що ключу доступно і до якого моменту він працює, тому просити ключ потрібно разом із перелiком потрібних вам дій — власник позначить саме їх.

Що сказати власникові:

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

Готовий ключ він передає вам як пароль. У списку ключів він видний маскою (перші та останні чотири символи), повністю — у картці, звідки його й копіюють.

Докладніше з боку власника — у посібнику користувача SpikePC, розділ API-ключі.

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

---

2. Транспорт

POST https://spikepc.com/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 не змінюються — це роблять у панелі. Партнерові потрібно працювати з клієнтами та залом, а не переписувати налаштування клубу, і кожна така правка вимагала б своїх перевірок форми.

Списку ключів. За ключем не можна прочитати таблицю ключів: партнер побачив би ключі інших партнерів цієї ж організації.

Структуру прав панелі не віддаємо: зовнішній системі вона ні про що не говорить, а у відповіді з'являлися б назви наших внутрішніх функцій.

---

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 якнайшвидше та обробляйте подію в себе асинхронно: поки ви тримаєте з'єднання, задача черги зайнята вами.