Dla maszyn
Urządzenie rozmawia z jednym wersjonowanym adresem bazowym — /api/v1/ — przez HTTPS.
Uwierzytelnia się parą swojego poświadczenia — własnym machine_uuid
i company_uuid swojej firmy, wysyłanymi w ciele każdego żądania —
odczytuje, czym jest i co ma oferować,
wysyła to, co się wydarzyło, i trzyma własną kopię, aż serwis potwierdzi.
| Endpoint | Kierunek | Do czego służy |
POST /api/v1/machine/info |
maszyna → serwis |
Własny wiersz maszyny: gdzie stoi, jak się nazywa, jakim jest typem, jakie ma flagi in/out. Maszyna i panel zgadzają się na podstawie tego jednego wiersza. |
POST /api/v1/machine/config |
maszyna → serwis |
Ten sam wiersz plus katalog żetonów tej maszyny: jej akceptory oraz nominały i ceny jej firmy. Jedno wywołanie przy starcie i jedno na zmianę. |
POST /api/v1/machine/telemetry |
maszyna → serwis |
Paczka zdarzeń żetonowych z bieżącym wypełnieniem. Każda paczka jest archiwizowana 1:1 przed parsowaniem, więc każdy raport da się odtworzyć z danych surowych. Paczka z jednym złym zdarzeniem jest odrzucana w całości i wysyłana ponownie. |
POST /api/v1/machine/telemetry/heartbeat |
maszyna → serwis |
„Jestem tutaj.” O tym, kto jest online, decyduje serwis, a nie maszyna. |
POST /api/v1/machine/config/ping |
maszyna → serwis |
„Tyle mówi mój zegar.” Zapisywane w company_machine_ping obok chwili, w której
żądanie do nas dotarło, więc rozjechany zegar urządzenia jest widoczny, zanim jego liczniki
trafią na zły dzień. Maszyna bez czytelnego zegara nadal dostaje swój wiersz; odrzucany jest
tylko czas, którego nie da się odczytać w ogóle (422 internal_time_invalid). |
Dwa transporty, jedna umowa
Te same paczki wędrują po HTTP i po MQTT
(token/events, token/snapshot,
token/counters, token/alert, plus obecność).
MQTT wynosi z maszyn informacje o żetonach — nigdy konfigurację:
żadnej nowej maszyny, żadnego nowego nominatu, żadnej ceny, żadnego włączenia.
Zasady, na których firmware może polegać
- Inicjatywa zawsze po stronie maszyny — serwis nigdy nie dzwoni do maszyny.
- Paczki z decyzją accept/reject per element, więc jedno złe zdarzenie nigdy nie odrzuca całej paczki.
- Odpowiedzi w jednej kopercie JSON:
success, data, meta, errors ze stabilnymi kodami.
- Zmiany tylko dodające w obrębie wersji; zmiana łamiąca przenosi na
/api/v2.
Sprawdź API
Pytania o integrację — napisz do nas