Caso pratico: accesso a una persona alla volta con Server Approval
Il requisito
Un cliente che gestiva un locale ad accesso limitato (ad es. una sala server, un caveau o un laboratorio) aveva bisogno di una regola semplice ma rigorosa, applicata direttamente alla porta:
Nel locale può trovarsi una sola persona alla volta. La persona successiva non deve poter entrare finché quella presente non ha registrato l’uscita.
Il dispositivo Cams si occupa della verifica dell’identità, e Server Approval la estende permettendo al vostro software di aggiungere la logica “c’è già qualcuno dentro?” , decidendo in tempo reale se un utente verificato debba davvero poter entrare.
Perché Server Approval è adatto
Per impostazione predefinita (Server Approval disattivato), il dispositivo concede l’accesso non appena verifica l’utente in locale , il vostro software lo scopre solo dopo. Va bene per un semplice log, ma non può impedire l’ingresso.
Con Server Approval attivato, il dispositivo si ferma dopo la verifica locale e attende che il vostro software confermi la timbratura prima di aprire la porta. È questo scambio di andata e ritorno a consentire di inserire la logica di business , come “c’è già qualcuno dentro?” , nella decisione di accesso stessa, invece di limitarsi a registrarla a cose fatte.
Come funziona il flusso
- Un utente timbra sul dispositivo.
- Il dispositivo lo verifica in locale, poi invia una richiesta JSON all’URL di callback registrato.
- Il vostro software controlla il proprio stato di occupazione e risponde:
{"status": "done"}→ il dispositivo accetta la timbratura e apre la porta.{"status": "reject"}→ il dispositivo nega l’accesso e tiene la porta chiusa.
- All’uscita, il vostro software aggiorna lo stato di occupazione in modo che il check-in successivo venga valutato correttamente.
Esempio con due utenti
L’utente X effettua il check-in. Il dispositivo verifica X, invia il callback, il vostro software trova il locale vuoto e restituisce done. X entra. Il vostro software segna il locale come occupato.
L’utente Y tenta il check-in mentre X è ancora dentro. Il dispositivo verifica Y e invia il callback , come per qualsiasi altra timbratura. Il vostro software vede che il locale è ancora occupato e restituisce reject. Il dispositivo nega l’accesso a Y e la porta resta chiusa. Y non entra finché il vostro software non dice diversamente.
X effettua il check-out. Il vostro software registra l’uscita e azzera il flag di occupazione.
Y riprova. Stesso flusso di callback, ma questa volta il vostro software vede il locale libero e restituisce done. Y entra.
Il ruolo del dispositivo non cambia mai , verifica sempre la persona e chiede al vostro software cosa fare dopo. L’unica cosa che cambia tra “reject” e “done” è ciò che il vostro software sa su chi si trova attualmente all’interno.
Note di implementazione
- Il controllo dell’occupazione è interamente a carico del vostro software , il dispositivo non ha memoria di chi si trovi dentro. Per un locale a occupazione singola basta un semplice flag o record per locale; per configurazioni con più locali o più posti serve una piccola tabella di stato indicizzata per locale/dispositivo.
- Assicuratevi che gli eventi di check-out vengano acquisiti in modo affidabile, perché un check-out mancato bloccherà il locale in modo permanente anche dopo che l’utente è uscito.
- Provate il percorso del callback in locale prima di andare in produzione , consultate la nostra guida complementare su come testare in locale i callback dell’API Cams con strumenti di tunneling per configurare ngrok/Cloudflare Tunnel/localhost.run sul vostro ambiente di sviluppo.
Cosa pianificare: connettività e risposte del callback
Server Approval dipende da uno scambio in tempo reale tra il dispositivo e il vostro server, e dal fatto che il server risponda sempre correttamente. Vale la pena progettare tenendo conto di due condizioni:
Il dispositivo è offline. Non può inviare il callback di verifica in tempo reale, quindi il vostro software non ha modo di rispondere done o reject. Il dispositivo mostra il messaggio “Disconnected” e rifiuta del tutto la timbratura , non ripiega su un accesso solo locale.
Il vostro callback restituisce qualcosa di diverso da {"status": "done"} o {"status": "reject"}. Una risposta non valida o inattesa rimane bloccata nella coda e il dispositivo non invierà al vostro callback alcun dato di timbratura successivo finché non viene risolta , quindi la porta resta chiusa, non solo per quell’utente ma per tutti quelli che seguono, finché il vostro callback non torna a rispondere correttamente.
In altre parole, la garanzia di una sola persona alla volta è solida quanto la connessione di rete del dispositivo e l’affidabilità delle risposte del vostro callback. Nelle installazioni di produzione, tenete conto di entrambi i fattori , ad es. collegamenti cablati invece del Wi-Fi o avvisi in caso di periodi offline prolungati, e una validazione rigorosa che garantisca che il callback restituisca sempre una risposta done/reject ben formata, anche nei percorsi di errore.
Risultato
Con Server Approval attivato e un semplice flag di occupazione nel software del cliente, il requisito di una sola persona alla volta è stato applicato interamente con le funzionalità già presenti nel dispositivo , senza hardware aggiuntivo e senza modifiche sul dispositivo oltre a un’impostazione di configurazione.