Skip to main content

Registrazione Dispositivi e Operatori

Panoramica​

Ogni dispositivo POS (cassa, cameriere, stock app) deve essere registrato sulla piattaforma prima di poter operare. La registrazione avviene tramite un codice OTP generato dall'amministratore. Dopo l'enrollment, gli operatori accedono al dispositivo con un PIN numerico.

Flusso di Registrazione Dispositivo​

Il flusso coinvolge due attori: l'amministratore (admin console) e il dispositivo (app Flutter).

1. Generazione OTP (Admin Console)​

L'amministratore genera un codice OTP dalla admin console:

curl -X POST "https://api.example.com/api/licensing/otp/generate" \
  -H "Authorization: Bearer <ADMIN_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "tenantId": "ristorante-roma",
    "deviceName": "Cassa 1",
    "licenseLevel": "standard"
  }'

Risposta: { "otp": "AB-1234", "qrCode": "<JWT_PAYLOAD>", "expiresIn": 300 }.

L'OTP ha validita di 5 minuti ed e salvato in Redis. Il campo qrCode contiene un JWT firmato utilizzabile per scansione QR.

2. Enrollment Dispositivo (App Flutter)​

Al primo avvio, l'app mostra una schermata di attivazione. L'operatore inserisce il codice OTP oppure scansiona il QR code:

curl -X POST "https://api.example.com/api/licensing/enroll" \
  -H "Content-Type: application/json" \
  -d '{
    "otp": "AB-1234",
    "deviceInfo": {
      "uuid": "550e8400-e29b-41d4-a716-446655440000",
      "platform": "windows",
      "model": "Surface Pro 9",
      "name": "Cassa 1"
    }
  }'

L'endpoint e pubblico (non richiede autenticazione). Il backend valida l'OTP, registra il dispositivo nella collezione devices e ritorna un Device Token JWT HS256 con validita di 1 anno, insieme alla configurazione del tenant (URL server, credenziali NATS, feature flags).

3. Rinnovo Token​

Il token dispositivo puo essere rinnovato tramite POST /licensing/refresh senza bisogno di un nuovo OTP, purche il dispositivo sia ancora registrato e attivo.

Creazione Operatori​

Gli operatori sono utenti di cassa che accedono tramite PIN numerico. Vengono gestiti dal servizio operator-management.

Creazione Operatore (Admin Console)​

curl -X POST "https://api.example.com/api/operator-management" \
  -H "Authorization: Bearer <ADMIN_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "operatorCode": "OP001",
    "firstName": "Mario",
    "lastName": "Rossi",
    "pin": "1234",
    "operatorRole": "cassiere",
    "permissions": ["orders.create", "orders.complete", "cash.movements"]
  }'

Il PIN viene hashato con SHA-256 prima del salvataggio. La lunghezza minima predefinita e 4 cifre, massima 8.

Login Operatore (App Flutter)​

L'operatore inserisce il PIN sulla schermata di login del dispositivo gia registrato:

curl -X POST "https://api.example.com/api/operators/login" \
  -H "Authorization: Bearer <DEVICE_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{ "pin": "1234", "deviceId": "550e8400-...", "clockIn": true }'

Il backend genera un Operator Token JWT HS256 con validita di 8 ore. Se clockIn: true, viene creata automaticamente una sessione operatore per il tracciamento presenze.

Livelli di Licenza​

Il campo licenseLevel determina le funzionalita disponibili sul dispositivo:

LivelloFunzionalita
basicOrdini, pagamenti, stampa
standardBasic + gestione tavoli, camerieri, magazzino
premiumStandard + analytics, fidelity, kiosk

FAQ​

D: Cosa succede se l'OTP scade prima che il dispositivo lo inserisca? R: L'OTP viene rimosso da Redis dopo 5 minuti. L'amministratore deve generarne uno nuovo dalla admin console.

D: Un dispositivo puo essere registrato su piu tenant? R: No. Ogni dispositivo e associato a un singolo tenant. Per cambiare tenant, il dispositivo deve essere de-registrato e ri-registrato con un nuovo OTP.

D: Come disattivo un operatore? R: Impostare isActive: false tramite l'admin console. Il login via PIN verra rifiutato immediatamente, anche se l'operatore ha un token ancora valido.

Vedi Anche​

Questa pagina ti è stata utile?