Controllere

Un controller este o instanță a aplicației mobile E-BON — un telefon sau o tabletă pe care rulează aplicația E-BON, care deține și face bridge între unul sau mai multe AMEF-uri din rețeaua locală și cloud printr-o singură conexiune WebSocket. API-ul de controllere îți permite să inspectezi și să actualizezi prezența controllerelor conectate la backend-ul e-bon pentru organizația autentificată și să înregistrezi tokenul FCM folosit pentru a trezi un controller aflat în fundal.

Intrările returnate de endpoint-ul de listare sunt citite direct din gateway-ul de controllere în memorie, deci reflectă conectivitatea live, nu starea din Firestore. Endpoint-urile de scriere a prezenței actualizează înregistrarea persistată a controllerului (legătura cu locația, versiunea aplicației, modelul dispozitivului, versiunea OS, ultimul timestamp de conectare).

Rutele sunt sub /api/v1/controllers și acceptă fie o cheie API (x-api-key / Authorization: Bearer …), fie un JWT din Portal.

GET /api/v1/controllers

Returnează lista controllerelor E-BON conectate în prezent prin WebSocket pentru organizația autentificată. Fiecare intrare include metadatele capturate la handshake-ul WebSocket (appVersion, deviceModel, osVersion, connectedAt), un controllerName rezolvat din înregistrarea controllerului — căzând înapoi pe controllerId-ul brut dacă nu este setat — și connectedDevices, id-urile dispozitivelor deținute al căror transport local este în prezent activ.

• Permisiune (scope): devices:read

Răspuns (200 OK)

{
  "instances": [
    {
      "controllerId": "ctrl_01HZ...",
      "controllerName": "Tejghea POS 1",
      "appVersion": "2.4.1",
      "deviceModel": "Samsung Galaxy Tab A8",
      "osVersion": "Android 14",
      "connectedAt": "2026-04-09T08:00:00.000Z",
      "connectedDevices": ["dev_pos_01", "dev_pos_02"]
    }
  ]
}

Exemplu

curl https://api.e-bon.ro/api/v1/controllers \
  -H "x-api-key: ebon_live_acme_corp_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6"

Coduri de eroare

• UNAUTHORIZED / FORBIDDEN — vezi Autentificare › Tratează erorile de autentificare.

Catalogul HTTP complet este pe Prezentare API › Catalogul codurilor de eroare HTTP.

POST /api/v1/controllers/:controllerId

Înregistrează (sau înlocuiește complet) înregistrarea de prezență pentru controllerul cu :controllerId-ul dat, la locația dată. Upsert idempotent — retrimiterea aceluiași body este sigură, iar înregistrarea controllerului este creată dacă nu există încă.

• Permisiune (scope): devices:write

Parametri de cale

• controllerId — id-ul controllerului (instanța aplicației).

Body-ul cererii

{
  "locationId": "loc_main_floor",
  "appVersion": "2.4.1",
  "deviceModel": "Samsung Galaxy Tab A8",
  "osVersion": "Android 14",
  "connectedAt": "2026-04-09T08:00:00.000Z"
}

• locationId (string, obligatoriu, 1–255 caractere) — obligatoriu pentru că prezența fără o legătură cu o locație nu are sens pentru rutarea traficului fiscal.
• appVersion, deviceModel, osVersion, connectedAt — opționale.

Răspuns (200 OK)

Returnează documentul controllerului actualizat, cu timestamp-urile serializate în format ISO-8601.

Exemplu

curl -X POST https://api.e-bon.ro/api/v1/controllers/ctrl_01HZ... \
  -H "x-api-key: ebon_live_acme_corp_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6" \
  -H "Content-Type: application/json" \
  -d '{"locationId":"loc_main_floor","appVersion":"2.4.1"}'

Coduri de eroare

• VALIDATION_ERROR (400) — body-ul nu se potrivește cu schema (locationId lipsă, lungimi de string în afara intervalului).
• UNAUTHORIZED / FORBIDDEN — vezi Autentificare › Tratează erorile de autentificare.

PATCH /api/v1/controllers/:controllerId

Actualizează parțial înregistrarea de prezență — de exemplu când un operator mută o tabletă între tejghele și se schimbă doar locationId.

• Permisiune (scope): devices:write

Parametri de cale

• controllerId — id-ul controllerului (instanța aplicației).

Body-ul cererii

Cel puțin un câmp trebuie furnizat. Toate câmpurile sunt individual opționale, dar body-ul nu poate fi gol.

{
  "locationId": "loc_terrace"
}

Câmpuri acceptate: locationId, appVersion, deviceModel, osVersion, connectedAt — aceeași formă și reguli de validare ca la POST.

Răspuns (200 OK)

Returnează documentul controllerului actualizat, cu timestamp-urile serializate în format ISO-8601.

Exemplu

curl -X PATCH https://api.e-bon.ro/api/v1/controllers/ctrl_01HZ... \
  -H "x-api-key: ebon_live_acme_corp_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6" \
  -H "Content-Type: application/json" \
  -d '{"locationId":"loc_terrace"}'

Coduri de eroare

• VALIDATION_ERROR (400) — body gol sau câmpuri care nu trec verificările de schemă.
• UNAUTHORIZED / FORBIDDEN — vezi Autentificare › Tratează erorile de autentificare.

POST /api/v1/controllers/:controllerId/fcm-token

Înregistrează tokenul de înregistrare Firebase Cloud Messaging pentru controller. Tokenul este folosit exclusiv drept canal de trezire: când API-ul are nevoie de un controller care nu este conectat în prezent prin WebSocket, trimite un push doar cu date pentru ca aplicația să se reconecteze și să dreneze comenzile fiscale în așteptare. Idempotent — retrimiterea unui token reîmprospătat îl suprascrie pe cel anterior. Scrie doar câmpurile fcmToken și updatedAt (upsert cu merge), lăsând câmpurile de prezență neatinse.

• Permisiune (scope): devices:write

Parametri de cale

• controllerId — id-ul controllerului (instanța aplicației).

Body-ul cererii

{
  "fcmToken": "fGc...:APA91b..."
}

• fcmToken (string, obligatoriu, 1–4096 caractere).

Răspuns (200 OK)

{ "controllerId": "ctrl_01HZ..." }

Coduri de eroare

• VALIDATION_ERROR (400) — fcmToken lipsă sau în afara intervalului.
• UNAUTHORIZED / FORBIDDEN — vezi Autentificare › Tratează erorile de autentificare.

Vezi și

• Dispozitive — gestionează dispozitivele fiscale pe care le dețin aceste controllere.
• Autentificare — catalogul de permisiuni (devices:read / devices:write sunt documentate aici).
• Prezentarea API-ului — URL de bază, plicul de eroare, limite de rată, idempotență, paginare.