Viewer

Elenco dei viewer

Recupera tutti i viewer associati a un'organizzazione, incluso il loro stato online (interrogato in tempo reale dal server controller) e il modello attualmente assegnato.

Parametri del percorso

Esempio di richiesta

GET https://api.spectraholo.it/v1/organization/42/viewers

Risposta200

{
  "success": true,
  "viewers": [
    {
      "id": 1,
      "serial": "VIEWER-ABC123",
      "name": "North Display",
      "online": true,
      "currentModel": {
        "id": 42,
        "name": "Hologram-v1",
        "description": "High-resolution model"
      },
      "pairedAt": "2026-06-15T10:30:00.000Z"
    },
    {
      "id": 2,
      "serial": "VIEWER-XYZ789",
      "name": null,
      "online": false,
      "currentModel": null,
      "pairedAt": "2026-06-14T15:45:00.000Z"
    }
  ]
}

Errori

• 401Backend API key valida o token di sessione mancanti
• 403Token di sessione valido ma livello di authority dell'utente insufficiente (< 0)
• 502Il server di autenticazione è irraggiungibile o non è riuscito a validare la sessione

Dettaglio di un viewer

Recupera informazioni dettagliate su un viewer specifico (device di display olografico) di un'organizzazione, inclusi numero di serie, nome, stato online (recuperato in tempo reale dal server controller), modello assegnato e timestamp di pairing.

Parametri del percorso

Esempio di richiesta

GET https://api.spectraholo.it/v1/organization/42/viewers/7

Risposta200

{
  "success": true,
  "viewer": {
    "id": 42,
    "serial": "VIEWER-001",
    "name": "North Display",
    "online": true,
    "currentModel": {
      "id": 15,
      "name": "Product Model X",
      "description": "High-resolution 3D model"
    },
    "pairedAt": "2025-06-10T14:30:00.000Z"
  }
}

Errori

• 401Token di sessione mancante o non valido; backend API key non valida o mancante quando l'header x-backend-api-key è presente
• 403Token di sessione valido ma livello di authority inferiore a 0 (non accade mai per questo endpoint, ma il framework potrebbe restituirlo)
• 404Viewer non trovato nell'organizzazione indicata
• 502Server di autenticazione irraggiungibile durante la validazione delle credenziali; server controller irraggiungibile nel recuperare lo stato online (in tal caso il campo online sarà null se è giù solo il controller)

Completa il pairing di un viewer

Completa il processo di pairing di un device viewer, associandolo all'organizzazione. Il viewer deve trovarsi in una sessione di pairing attiva sul server di pairing. Registra il viewer localmente (genera id e timestamp pairedAt), emette un token di device sul server di autenticazione e consegna le credenziali org+token al device tramite il server di pairing. Il token viene consegnato solo al device, mai nella risposta dell'API.

Parametri del percorso

Corpo della richiesta · application/json

Esempio di corpo (JSON)

{
  "serial": "VIEWER-001",
  "code": "48217390",
  "name": "Vetrina Nord"
}

Risposta201

{
  "viewer": {
    "id": 42,
    "serial": "VIEWER-001",
    "name": "North Display",
    "organizationId": 5,
    "pairedAt": "2026-06-15T14:32:09.000Z"
  }
}

Errori

• 400Corpo JSON non valido, campi malformati, oppure serial e code forniti contemporaneamente. Anche quando il formato di serial/code non è valido (serial: non ASCII o con spazi; code: non esattamente 8 cifre).
• 404L'ID dell'organizzazione non esiste, oppure (usando il codice di pairing) il codice non viene trovato sul server di pairing (il codice ruota periodicamente).
• 409Il viewer non è in una sessione di pairing attiva sul server di pairing, il serial è già associato a un'altra organizzazione, l'organizzazione ha raggiunto il limite massimo di viewer, oppure il device si è disconnesso dal server di pairing durante l'handshake.
• 502Il server di autenticazione, il server di pairing, o entrambi sono irraggiungibili o hanno restituito errori durante l'emissione del token o il completamento del pairing.

Rimuovi un viewer (disconnetti)

Rimuove definitivamente un viewer da un'organizzazione e revoca il suo token di autenticazione sul server di autenticazione. Il device torna in modalità pairing e può essere riassociato alla stessa o a un'altra organizzazione. È l'azione 'Disconnetti' del pannello di controllo. Atomicità: l'eliminazione del viewer e la revoca del token avvengono nella stessa transazione; la revoca del token avviene prima del commit. Dopo il commit, al server controller viene inviato un comando di logout in best-effort.

Parametri del percorso

Esempio di richiesta

DELETE https://api.spectraholo.it/v1/organization/42/viewers/7

Risposta200

{
  "success": true,
  "viewerId": 42,
  "serial": "VIEWER-001",
  "delivered": true
}

Errori

• 401Token di sessione mancante o non valido; backend API key non valida o mancante quando l'header x-backend-api-key è presente
• 403Token di sessione valido ma livello di authority inferiore a 2 (AUTHORITY_MANAGE insufficiente)
• 404Viewer non trovato nell'organizzazione indicata
• 502Server di autenticazione irraggiungibile: la revoca del token non può essere confermata, quindi l'intera eliminazione viene annullata e il viewer resta registrato

Assegna e mostra un modello

Assegna un modello 3D a un viewer e, se il viewer è online, lo mostra in tempo reale. Lo stato desiderato viene persistito nel database locale (fonte di verità) e poi inviato al viewer tramite il server controller. Se il viewer è offline, lo stato viene comunque salvato con `delivered: false` e il device lo recupererà al prossimo avvio tramite GET .../viewers/display. Se il server controller non è disponibile (502), lo stato viene annullato e il client può riprovare.

Parametri del percorso

Corpo della richiesta · application/json

Esempio di corpo (JSON)

{
  "modelId": 42
}

Risposta200

{
  "success": true,
  "viewerId": 42,
  "serial": "DEVICE-001",
  "model": {
    "id": 10,
    "name": "Hologram Model",
    "description": "A detailed holographic display"
  },
  "delivered": true
}

Errori

• 400Corpo della richiesta non valido (modelId mancante o non positivo)
• 401Autenticazione mancante o non valida (né Bearer token valido né backend API key valida fornita)
• 403Sessione valida ma livello di authority insufficiente (inferiore a DISPLAY livello 1)
• 404Viewer non trovato nell'organizzazione oppure modello non trovato nell'organizzazione
• 502Server controller irraggiungibile o non è riuscito a consegnare il comando al viewer

Svuota il display di un viewer

Rimuove il modello attualmente assegnato a un viewer e gli ordina di non mostrare nulla. Lo stato viene prima persistito nel database locale, poi il viewer viene notificato in tempo reale se è online. Se è offline, lo stato viene salvato e il device si allineerà al prossimo avvio. L'operazione segue la stessa semantica transazionale della POST (il cambio di stato è atomico rispetto al controller).

Parametri del percorso

Esempio di richiesta

DELETE https://api.spectraholo.it/v1/organization/42/viewers/7/display

Risposta200

{
  "success": true,
  "viewerId": 42,
  "serial": "DEVICE-001",
  "model": null,
  "delivered": true
}

Errori

• 401Autenticazione mancante o non valida (né Bearer token valido né backend API key valida fornita)
• 403Sessione valida ma livello di authority insufficiente (inferiore a DISPLAY livello 1)
• 404Viewer non trovato nell'organizzazione
• 502Server controller irraggiungibile o non è riuscito a consegnare il comando al viewer

Stato di display di un viewer

Recupera lo stato di display corrente di un viewer (il modello che deve mostrare, oppure null se nessuno). Usato dai device viewer all'avvio per sincronizzare lo stato dopo periodi offline o comandi live persi. Supporta tre modalità di autenticazione: (1) credenziali del device tramite header x-serial + token, (2) sessione di un membro dell'organizzazione con AUTHORITY_VIEW, oppure (3) backend API key. Con l'autenticazione del device (header x-serial presente) il device legge solo il proprio stato. Con autenticazione di sessione o backend, occorre indicare il serial del viewer di destinazione tramite parametro di query.

Parametri del percorso

Parametri query

Esempio di richiesta

GET https://api.spectraholo.it/v1/organization/42/viewers/display?serial=VIEWER-001

Risposta200

{
  "serial": "VIEWER-001",
  "model": {
    "id": 42,
    "name": "Tesla Model 3",
    "description": "Premium sports sedan"
  }
}

Errori

• 400Header x-serial presente ma x-token e Authorization Bearer assenti; oppure x-serial assente e il parametro di query serial mancante o vuoto
• 401Credenziali del device (x-serial + token) non valide o scadute; oppure token di sessione non valido/scaduto; oppure l'utente non possiede AUTHORITY_VIEW (authority < 0)
• 404L'organizzazione non esiste; oppure nessun viewer con il serial indicato è registrato nell'organizzazione
• 502Il server di autenticazione è temporaneamente irraggiungibile (validazione delle credenziali fallita). Applicabile solo alla modalità di autenticazione del device; il retry è sicuro.