API dla partnerów organizacji (klucze API)

HTTP-API, którym zewnętrzny partner właściciela klubu czyta dane jego organizacji: kasa, system lojalnościowy, strona z rezerwacją online, własna witryna sieci. Klucz wydaje właściciel w panelu (sekcja Klucze API), on też decyduje, co klucz może i do kiedy działa.

To nie protokół stanowiska do gry (ten działa po WebSocket) ani API aplikacji mobilnej klienta — to osobne kontrakty. Nie ma tu sesji klienta ani logowania człowieka: żądanie przychodzi od programu partnera i jest rozpoznawane po kluczu.

Postman. Do importu gotowe są dwa pliki:

Zaimportuj oba (*Import* → przeciągnij pliki), wybierz środowisko w prawym górnym rogu i wpisz w nim api_key. Klucz trzymaj w środowisku, a nie w kolekcji: kolekcje się przekazuje i eksportuje, środowisko zostaje u ciebie.

Dalej całość można uruchomić Runnerem — listy pamiętają id pierwszego elementu, więc gs.get, product.get, session.get, order.get i chat.messages działają bez ręcznego wpisywania. Foldery 1–7 oczekują odpowiedzi 200, czyli liczą na klucz z pełnym dostępem; klucz z ograniczonymi uprawnieniami zgodnie z zasadami odpowiada 403 forbidden_action na niedostępne akcje — co dokładnie jest dla niego dostępne, mówi meta.actions.

---

1. Skąd wziąć klucz

Klucz wydaje właściciel klubu w swoim panelu: sekcja Klucze API → „Utwórz”. Tam też wybiera, co kluczowi wolno i do kiedy działa, dlatego o klucz proś razem z listą potrzebnych ci akcji — właściciel zaznaczy właśnie je.

Co powiedzieć właścicielowi:

• jakie dane są potrzebne — po akcjach z §4 (np. gs.status, product.list); w karcie klucza zaznacza uprawnienia o tych samych nazwach, które podpisane są przy akcji;
• na jaki okres — klucz można wydać na dzień, tydzień, miesiąc, rok, do konkretnej daty albo bez terminu;
• czy potrzebny jest dziennik żądań — gdy integracja jest jeszcze dopracowywana, właściciel włącza pole wyboru i widzi twoje żądania (patrz §8).

Gotowy klucz przekazuje ci jak hasło. Na liście kluczy widać go w masce (pierwsze i ostatnie cztery znaki), w całości — tylko w karcie, skąd się go kopiuje.

Więcej od strony właściciela jest w podręczniku użytkownika SpikePC, w sekcji Klucze API.

Klucz nie jest przypisany do klubu: działa na całą organizację, a konkretny klub wskazujesz parametrem club_id.

---

2. Transport

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 } }

Adres podawaj z ukośnikiem na końcu (/spike_api/). Bez niego serwer odpowiada przekierowaniem na adres z ukośnikiem, a treść żądania POST przy przekierowaniu ginie — żądanie przyjdzie puste i dostanie 400 bad_request.

Ten sam handler jest dostępny też pod wewnętrznym adresem ?loc=spike_user_api_request — on nadal działa, ale w integracjach używaj /spike_api/.

v to wersja kontraktu, opcjonalna (obecnie 1).

---

3. Odpowiedź

Ta sama koperta, co u stanowiska i aplikacji mobilnej; code powtarza się w statusie HTTP:

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

• error_key to stabilny kod maszynowy — na nim się opieraj. error_text to wyjaśnienie po angielsku, jego brzmienie może się zmieniać.
• data to zawsze obiekt (przy błędzie {}): do obiektu można dodać pole, nie psując parsera. Listy to items + total + limit/offset, pojedynczy rekord to item.
• action to echo zamówionej akcji, przydatne, gdy po twojej stronie działa kolejka asynchroniczna.

Kody i klucze błędów

---

4. Akcje

Co zrobić, mówi pole action. Punkt wejścia jest jeden, więc dodanie metody nie zmienia adresu i nie wymaga zmian po twojej stronie. Uprawnienie każdej akcji to nazwa funkcji w panelu: jest podpisana w karcie klucza obok pozycji uprawnień i właśnie ją właściciel zaznacza, żeby otworzyć partnerowi akcję.

Akcje w tej sekcji tylko czytają. Te, które zmieniają dane, są w §5.

Serwisowe (bez uprawnienia)

Klub i sala

Katalog

search w towarach szuka po nazwie, kodzie artykułu i kodzie kreskowym. locale podmienia name i description tłumaczeniem tej lokalizacji; nie ma tłumaczenia — zostaje wartość bazowa, więc odpowiedź nigdy nie przychodzi pusta.

club_id przy towarach jest wymagany: towar ma własną cenę w każdym klubie, a bez klubu trzeba by zwracać „cenę w ogóle” — partner sprzedawałby po obcej. Jeśli w tym klubie ceny nie ma, przychodzi price: null i available: false — tutaj towar nie jest sprzedawany.

Godziny dostępności towaru przychodzą w polu hours — po jednym wierszu na dzień tygodnia: [{day, from_sec, to_sec}], gdzie day to 0=pon … 6=niedz, a from_sec/to_sec — sekundy od północy. Pusta tablica oznacza sprzedaż całodobową. to_sec to ostatnia wliczona sekunda (okno „18:00–22:00” przychodzi jako 64800…79259), a to_sec mniejszy od from_sec to okno przez północ: zaznaczony dzień wyznacza początek, koniec wypada następnej doby. Obok przychodzi gotowa odpowiedź hours_open (true/false — czy towar jest w sprzedaży właśnie teraz): samodzielne wyliczenie wymagałoby naszej konwencji granic i naszej strefy czasowej. Na pole available harmonogram nie wpływa — nadal dotyczy ceny w klubie i aktywności towaru.

Taryfy i abonamenty

Granice przedziałów harmonogramu są włączne, przy czym time_end to ostatnia włączona sekunda bloku (godzina 13 → 50399 = 13:59:59). W odpowiedzi obok sekund idą gotowe from/to, żebyś nie powtarzał tej konwencji u siebie i nie tracił ostatniej godziny.

Dwie siatki abonamentu to różne rzeczy: kind=sale odpowiada „kiedy można go kupić”, kind=valid — „kiedy kupione można wykorzystać”. Pusta siatka ważności znaczy „działa zawsze”.

Przy kasie bonusowej balance przychodzi jako null, a nie zero: bonusy to nie realne pieniądze w kasie.

Klienci i pieniądze

search w klientach szuka po mailu, telefonie, loginie, imieniu i nazwisku. Telefon w client.get jest szukany we wszystkich formatach, w jakich mógł zostać zapisany (380…, +380…, 0…, 38…) — import i rejestracja zapisywały go inaczej.

Serwisowe wpisy gościnne stanowisk (gościnna płatność po grze) nie trafiają do listy klientów. Notatki operatora i awatar nie są wydawane.

Pozostały czas abonamentu liczy się po zegarze ściennym: aktywowany abonament wypala się od momentu aktywacji, więc remaining_seconds nie pokaże czasu, który już się wypalił, gdy klienta nie było.

Sesje, zamówienia, rezerwacje, czat

Aktywna sesja wciąż zbiera swój wynik, dlatego w odpowiedzi jest active: true — nie bierz sumy pośredniej za ostateczną.

Zamówienie nie obciąża salda klienta — płaci się je na miejscu personelowi, więc total_amount to kwota do zapłaty, a nie zrealizowana płatność.

Okres przy rezerwacjach liczy się po przecięciu, a nie po początku: rezerwacja, która zaczęła się wczoraj i trwa teraz, trafia do wyboru za dziś.

Przy rozmowach total to liczba rozmów, a nie wiadomości.

Organizacja

org.info nie wydaje danych dostępowych: ani do bazy, ani SMTP, ani tokenów Telegrama, ani gs_token stanowisk, ani salda organizacji. Uprawnienie „podgląd ustawień” dostaje pracownik wewnątrz panelu, a tutaj odpowiedź idzie do strony trzeciej.

event.list nie wydaje zrzutów „przed/po”: trafiają do nich całe pola, w tym hasła Windows klubu. Zostaje kto, kiedy, w jakiej sekcji i nad czym.

analytics.daily wylicza nocne zadanie w strefie czasowej organizacji, dlatego bieżący dzień zwykle jest pusty — to nie utrata danych: za dziś bierz żywe gs.status, transaction.list, order.list. Okres domyślny to ostatnie 30 dni.

Strony i filtry

• limit — 50 domyślnie, maksymalnie 200; offset liczy się od zera. Oba wracają w odpowiedzi.
• date_from / date_to — YYYY-MM-DD albo YYYY-MM-DD HH:MM:SS. Data bez czasu w date_to znaczy całą dobę, inaczej 2026-10-01 odciąłby cały dzień, zostawiając północ.
• Wartości filtrów wyliczeniowych (status, type, kind) są sprawdzane z białą listą: obca wartość daje 422 bad_params, a nie cicho zignorowany filtr.

Przykład: stan sali na żywo

→ { "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 i online liczy ten sam kod, co mapa klubu, dlatego partner i operator widzą tę samą liczbę.

---

5. Zapis

Te akcje zmieniają dane klubu: przyjmują pieniądze, sprzedają abonament, przesuwają zamówienie, tworzą rezerwację, przyznają rabat i kredyt, wysyłają polecenie do stanowiska. Ich uprawnienia są osobne — właściciel zaznacza je w karcie klucza niezależnie od podglądu, więc „obejrzeć" i „zmienić" nigdy nie idą w jednym polu wyboru.

Zasady są te same, co u operatora w panelu: bez otwartej zmiany kasowej pieniądze nie są przyjmowane, abonament ponad limit organizacji nie jest sprzedawany, rezerwacja w zamkniętych godzinach nie powstaje. To nie „podobne sprawdzenia" — obie strony wywołują ten sam kod, więc partner nie może tego, czego nie wolno operatorowi.

Pieniądze

Kasa jest wymagana (payment_method_id), listę podaje payment_method.list. Przy kasie bonusowej wymagany jest comment — bonusu bez wyjaśnienia nie przyjmujemy, inaczej nie ma czym odpowiedzieć na pytanie „za co naliczono". Jeśli kasa jest wspólna dla organizacji, a klubów jest kilka, potrzebny jest club_id: bez niego operacja zginęłaby dla raportów klubu.

Potrzebna jest otwarta zmiana kasowa w tym klubie, inaczej 409 no_shift. Zmianę otwiera kasjer w panelu i przez API się tego nie obejdzie: pieniądze muszą należeć do czyjejś zmiany.

Zwrot (transaction.refund) jest możliwy tylko dla doładowania i tylko raz; saldo może zejść na minus — pieniądze oddano z kasy, więc schodzą z salda w całości.

Sprzedaż abonamentu obciąża saldo klienta z uwzględnieniem jego stałego rabatu (jeśli abonament rabaty dopuszcza). Abonament trafia do zapasu: zegar startuje przy aktywacji na stanowisku, a nie przy sprzedaży, inaczej kupiony z wyprzedzeniem wypaliłby się przed przyjściem klienta.

Sala

Rabat: jeśli przy stanowisku jest klient, procent idzie zrzutem do jego sesji (lista może być później zmieniona, a człowiek dogrywa na tym, co obiecano); jeśli stanowisko jest wolne, zgłoszenie czeka na tego, kto usiądzie, 30 minut.

Kredyt to dozwolona głębokość minusa do końca sesji, a nie wpłata: klient dogrywa na kredyt i spłaca go zwykłym doładowaniem. Potrzebna jest aktywna sesja klienta.

Polecenia: dozwolone są tylko message, poweroff, poweron i session_end. Tryby stanowiska, złote obrazy i reszta zarządzania salą zostają przy operatorze — to sprawa klubu, nie systemu zewnętrznego. W odpowiedzi jest delivery: done/delivered — stanowisko przyjęło, offline — nie jest połączone, timeout — nie odpowiedziało w czasie.

Klucze odmowy przy zapisie

---

6. Uprawnienia klucza

Tryb dostępu klucza wybiera właściciel:

• Pełny dostęp — klucz może wszystko, co właściciel organizacji;
• Grupa dostępu — uprawnienia wybranej grupy, jak u pracownika;
• Własny zestaw — tylko zaznaczone funkcje.

Uprawnienie każdej akcji to nazwa funkcji w panelu i jest ona podpisana w karcie klucza obok pozycji uprawnień. Właściciel widzi więc dokładnie to, co jest sprawdzane przy żądaniu: jeśli partner dostaje forbidden_action na gs.list, w karcie klucza trzeba zaznaczyć pozycję z uprawnieniem spike_gs_list.

Termin klucza sprawdza serwer: po jego upływie każde żądanie odpowiada key_expired (401), nawet jeśli partner o tym nie wie.

---

7. Częstotliwość żądań

Limit to 120 żądań na minutę na klucz (wartość zmienia administrator systemu). Po przekroczeniu przychodzi 429 rate_limited i nagłówek Retry-After: 60.

Odpytywanie stanu sali raz na 2–5 sekund mieści się w limicie z zapasem. Jeśli trzeba częściej — poproś właściciela klubu o podniesienie limitu, a nie obchodź go kilkoma kluczami: limit liczy się na klucz właśnie po to, by jeden partner nie przeszkadzał innym.

---

8. Dziennik żądań

W karcie klucza właściciel może włączyć dziennik żądań: wtedy każde wywołanie tym kluczem jest przechowywane 7 dni — akcja, kod odpowiedzi, czas trwania, IP i treść żądania (klucz jest z niej wycinany). To narzędzie do rozwiązywania „u partnera nie działa”: na stałe dziennik nie jest potrzebny.

Jeśli twoje żądanie dostaje odmowę, a powód jest niejasny, poproś właściciela o włączenie dziennika i powtórz żądanie — w dzienniku będzie widać akcję, kod i to, co dokładnie przysłałeś.

---

9. Czego w tym API nie ma

Edycji danych słownikowych. Taryfy, abonamenty, towary, kluby, stanowiska, pracownicy, uprawnienia i ustawienia organizacji nie zmieniają się przez API — to robi się w panelu. Partner ma pracować z klientami i salą, a nie przepisywać ustawienia klubu, a każda taka zmiana wymagałaby własnych sprawdzeń formularza.

Listy kluczy. Kluczem nie można odczytać tabeli kluczy: partner zobaczyłby klucze innych partnerów tej samej organizacji.

Struktury uprawnień panelu nie wydajemy: zewnętrznemu systemowi nic nie mówi, a w odpowiedzi pojawiałyby się nazwy naszych wewnętrznych funkcji.

---

10. Webhooki: zdarzenia same przychodzą do Ciebie

Aby nie odpytywać API w poszukiwaniu nowego zamówienia, podaj właścicielowi klubu swój adres — zdarzenia będą trafiać na niego same. Ustawia się to w panelu organizacji (karta „Klienci i zamówienia”): adres, wyłącznik, klucz podpisu i lista zdarzeń.

Żądanie: POST <Twój adres>, treść to 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 } }

Nagłówki: X-Spike-Event (nazwa zdarzenia), X-Spike-Org (organizacja) oraz X-Spike-Signature — podpis treści.

Zdarzenia

Organizacja może zapisać się na część zdarzeń — wtedy przyjdą tylko one.

Podpis: sprawdzaj go

X-Spike-Signature: sha256=<hex> to HMAC-SHA256 z całej treści żądania na kluczu, który właściciel klubu ustawił w ustawieniach. Policz podpis samodzielnie i porównaj z nagłówkiem: bez tej weryfikacji na Twój adres będzie mógł pisać każdy, podając się za nas. Jeśli klucz nie jest ustawiony, nagłówka nie będzie; i tak warto poprosić właściciela, żeby go ustawił.

# przykład weryfikacji (bash)
calc=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "$SECRET" | awk '{print $2}')
[ "sha256=$calc" = "$SIG" ] || exit 1

Dostarczanie

Wysyła kolejka, a nie żądanie operatora: panel i serwis socketowy nigdy nie czekają na Twój serwer. Stąd zasady, na które możesz liczyć:

• limity czasu — 5 sekund na połączenie i 10 na całą wymianę;
• trzy próby z przerwami (od razu, po 2 i po 5 sekundach), dopóki odpowiedź nie jest 2xx;
• odpowiedzi 4xx (poza 408 i 429) nie powtarzamy — uznajemy żądanie za odrzucone;
• przekierowania nie są wykonywane: Location jest ignorowany, POST nie pójdzie dalej;
• kolejność zdarzeń nie jest gwarantowana, a dostarczenie co najmniej raz nie jest zapewnione — jeśli Twój serwer nie działał przy wszystkich trzech próbach, zdarzenie przepadnie. Rzeczy krytyczne uzgadniaj czytając API: są w nim zamówienia, sesje i operacje.

Odpowiadaj 200 jak najszybciej i przetwarzaj zdarzenie u siebie asynchronicznie: dopóki trzymasz połączenie, zadanie kolejki jest zajęte Tobą.