API: Totem delle presenze

In questa pagina vengono descritte le API del totem delle presenze.

Generare il token di autenticazione

Per generare il token di autenticazione sono necessari i seguenti permessi: visualizzareMakerSpace, visualizzareTotem, gestireTotem.

Dalla pagina principale Gestione:

1. aprire l'elenco dei Maker Space (cliccando su Apri Gestione Maker Space);
2. aprire il Maker Space per il quale si vuole generare il token;
3. nella sezione Gestione totem inserire il nome del nuovo totem (consiglio di dare un nome significativo, se nello stesso Maker Space si vogliono utilizzare più totem è importante poterli riconoscere) e cliccare su Aggiungi;
4. nella tabella copiare il token del totem appena creato.

N.B. Il token deve rimanere segreto. Se il token viene conosciuto dagli utenti è necessario cliccare sul bottone Revoca token per generare un nuovo token e revocare quello precedente (altrimenti gli utenti possono aggiungersi autonomamente le presenze).

Aggiunta della presenza

Per aggiungere la presenza è necessario inviare una richiesta POST all'indirizzo [URL DELLA TUA INSTALLAZIONE]/api/v1/totem/presenze.php(sostituendo [URL DELLA TUA INSTALLAZIONE]con l'url del server su cui hai installato questo CMS, es. https://portale.example.org). Il corpo della richiesta deve essere nel formato application/www-x-form-urlencoded e deve contenere i campi descritti nella seguente tabella.

Campo	Descrizione	Obbligatorio	Default
token	Token di autenticazione del totem (compresi i -, è case sensitive).	Sì
rfid	ID di dieci cifre del badge RFID.	Sì
timestamp	Unix Time Stamp (Wikipedia) di quando il totem ha registrato il passaggio del badge. Lo sfasamento consentito rispetto all'orario attuale è di -12 ore e +5 minuti.	No	Unix Time Stamp al momento della ricezione della richiesta.

Lo sfasamento negativo è molto ampio perché in caso di problemi di connessione ad internet o del server di destinazione, il totem dovrebbe essere in grado di salvare la presenza in locale e ritentare l'invio successivamente.

Il server risponde in formato JSON. Se la risposta è un oggetto vuoto, la richiesta è stata accettata. In caso di errore l'oggetto conterrà una proprietà errore valorizzata a true e se disponibile un messaggio di errore nella proprietà msg.

Esempio di risposta in caso di successo:

{}

Esempio di risposta in caso di errore senza un motivo specificato:

{
  "errore": true
}

Esempio di risposta in caso di errore con un motivo specificato:

{
  "errore": true,
  "msg": "Timestamp non valido!"
}

In generale, nei casi di errore, il server risponde sempre con un messaggio.