FlipperService

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.

EndpointKierunekDo 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