Riferimento API: architettura, campi e codici di stato
Gli elementi comuni a tutte le operazioni: flusso delle richieste, campi JSON comuni, tipi di template, codici di stato, porte e crittografia dei payload.
Risposte rapide
Quali sono i due flussi API?
L’API di callback invia eventi dal dispositivo (tramite Cams Biometric Gateway) al tuo server in tempo reale. L’API RESTful permette al tuo server di inviare comandi a un dispositivo, e la risposta arriva in circa 15 secondi. Se il tuo server è offline, il motore mette in cache i callback; i comandi REST restano in coda finché il dispositivo non si riconnette.
Quali codici di stato restituisce l’API RESTful?
Un StatusCode numerico: 0 successo, 1 dati della richiesta non validi, 2 Service Tag ID non valido, 3 richiesta non valida, 4 crittografia non valida, 5 dispositivo offline, 6 timeout dell’operazione, 7 token di autenticazione non valido, 8 utente già esistente, 9 utente non trovato, 10 errore del template, 11 memoria del dispositivo piena, 13 chiave di sicurezza non valida, 15 funzionalità non supportata, 999 errore sconosciuto. Le risposte ai callback usano sempre {"status":"done"}.
Che cosa significa il codice di stato 5 (dispositivo offline)?
Il dispositivo di destinazione non è attualmente connesso al Biometric Gateway. Vedi il codice di stato 5.
Come autentico le richieste?
Ogni richiesta contiene un AuthToken, un token di 32 caratteri che identifica un dispositivo e viene impostato nel portale API Monitor. Convalidalo a ogni callback in ingresso. Le chiamate REST indicano il dispositivo anche tramite il parametro di query stgid (Service Tag ID). Vedi Campi comuni.
Di quali porte ha bisogno il mio server?
Porta 80 (HTTP) o 443 (HTTPS) in produzione; si consiglia HTTPS con un certificato valido. La porta 8123 (HTTP) è solo per i test. Vedi Porte supportate.
Come viene crittografato il payload?
La crittografia è facoltativa. Se attivata, i payload usano AES-256 in modalità ECB con padding PKCS5 (AES/ECB/PKCS5PADDING), con la chiave di sicurezza impostata in API Monitor, e sono codificati in Base64 per il trasporto HTTP. Decifra i callback in ingresso e cifra i corpi REST in uscita con la stessa chiave. Vedi Crittografia.
Come gestisco i template che arrivano in più callback?
Uniscili. Ogni callback contiene solo i template aggiunti o modificati. La chiave univoca di un template è Type + Index, quindi esegui l’upsert per quella coppia e non sostituire mai l’intero set di template di un utente. Vedi Tipi di template.
Quali tipi di template esistono?
Card, Password, Fingerprint, Face, Palm e UserPhoto. I template Fingerprint, Face e Palm sono codificati in Base64, e l’indice delle impronte va da 0–9.
Architettura dell’API
| Proprietà | API di callback | API RESTful |
|---|---|---|
| Iniziatore | Dispositivo / Biometric Gateway | Il tuo server |
| Direzione | Dispositivo → Il tuo server | Il tuo server → Dispositivo |
| Latenza | Tempo reale (millisecondi) | ~15 secondi |
| Trigger | Evento biometrico sul dispositivo | HTTP POST dal tuo codice |
| Il tuo ruolo | Ricevere & confermare | Inviare il comando & interrogare/attendere la risposta |
| Corpo della risposta | {"status":"done"} | {"Status":"done","OperationID":"…","StatusCode":0} |
| Comportamento offline | Messo in cache dal motore; consegnato quando il server torna online | Messo in coda dal motore; consegnato quando il dispositivo si riconnette |
Campi comuni
Tutte le richieste — sia di callback sia RESTful — condividono questi campi di primo livello.
"j95xfejt3vr1"). Le risposte RESTful restituiscono lo stesso OperationID così puoi associare richieste e risposte.YYYY-MM-DD HH:mm:ss GMT +0000. I timestamp locali del dispositivo nel payload possono usare un fuso orario diverso.POST https://<your-endpoint>?stgid=YOUR_TAG_ID.Tipi di template
I dati biometrici e delle credenziali sono trasportati in un array Template. Ogni elemento ha un campo Type:
Quando i dati utente vengono inviati dal dispositivo (operazioni di callback n. 3–9), i template possono arrivare uno alla volta o in gruppi, su più callback. Ogni callback non contiene l’intero set di template dell’utente — trasporta solo i template aggiunti o modificati.
Il tuo server deve unire i template in arrivo con quelli già salvati per quell’utente. La chiave univoca di ogni template è
Type + Index. Ad esempio:• Il callback 1 arriva con
Fingerprint Index 0 → salvalo• Il callback 2 arriva con
Face Index 0 + Card → unisci, non sovrascrivere l’impronta• Il callback 3 arriva con
Fingerprint Index 0 (nuovi dati) → aggiorna l’impronta esistente all’Index 0Non sostituire mai tutti i template in un callback — esegui sempre un upsert per
Type + Index.
| Type | Descrizione | Campi aggiuntivi principali |
|---|---|---|
Card | Numero del badge RFID / di prossimità | Data (stringa del numero del badge) |
Password | PIN numerico | Data (stringa del PIN) |
Fingerprint | Template di impronta digitale — binario codificato Base64 | Index (indice del dito 0–9), Size, Data |
Face | Template del volto — JPEG o binario codificato Base64 | Index, Size, Data |
Palm | Template delle vene del palmo — binario codificato Base64 | Index, Data |
UserPhoto | Foto del profilo utente — JPEG codificato Base64 | Data |
Codici di stato della risposta
Le risposte delle API RESTful includono uno StatusCode numerico. Le risposte delle API di callback usano sempre la forma semplice {"status":"done"}, indipendentemente dall’esito.
| Codice | Stato | Descrizione |
|---|---|---|
0 | Successo | Operazione completata con successo. |
1 | Dati della richiesta non validi | Il corpo JSON è malformato o contiene valori non validi. |
2 | Service Tag ID non valido | Il parametro di query stgid non corrisponde ad alcun dispositivo registrato. |
3 | Richiesta non valida | La struttura della richiesta non corrisponde al formato di operazione previsto. |
4 | Crittografia non valida | Non è stato possibile decifrare il payload crittografato (AES-256). Controlla la tua chiave di crittografia. |
5 | Dispositivo offline | Il dispositivo di destinazione non è attualmente connesso alla Biometric Gateway. |
6 | Timeout dell’operazione | Il dispositivo non ha confermato il comando entro il tempo limite. |
7 | Token di autenticazione non valido | L’AuthToken nella richiesta non corrisponde al token configurato per il dispositivo. |
8 | Utente già esistente | È stata tentata un’operazione di aggiunta per un UserID già presente sul dispositivo. |
9 | Utente non trovato | L’UserID specificato non esiste sul dispositivo. |
10 | Errore del template | I dati del template biometrico sono corrotti o in un formato non supportato. |
11 | Memoria del dispositivo piena | Il dispositivo ha raggiunto la capacità massima di utenti o template. |
13 | Chiave di sicurezza non valida | La chiave di sicurezza configurata nell’API Monitor non corrisponde. |
15 | Funzionalità non supportata | L’operazione richiesta non è supportata da questo modello di dispositivo o da questa modalità di comunicazione. |
999 | Errore sconosciuto | Si è verificato un errore imprevisto. Contatta il supporto Cams indicando l’OperationID. |
Porte supportate
Per ricevere le informazioni di presenza in tempo reale, il tuo server deve esporre un endpoint HTTP(S) raggiungibile dal Cams Protocol Engine.
| Porta | Protocollo | Utilizzo |
|---|---|---|
80 | HTTP | Produzione. Associa il tuo URL di callback alla porta 80. Configurato nell’API Monitor e chiamato automaticamente a ogni timbratura. |
443 | HTTPS | Produzione (sicuro). HTTPS con certificato SSL valido. Consigliato per la produzione. |
8123 | HTTP | Solo per test. Porta non standard disponibile temporaneamente durante lo sviluppo. |
Dati di esempio
Esempi di payload di richiesta e risposta per tutte le 38 operazioni sono documentati sopra in ciascuna sezione di operazione. Per una vista consolidata:
Crittografia
È possibile attivare la crittografia AES-256 opzionale per tutti i dati scambiati tra il Cams Protocol Engine e il tuo server.
AES/ECB/PKCS5PADDING).Esempio Java
// Encryption
Cipher cipher = Cipher.getInstance("AES/ECB/PKCS5PADDING");
SecretKeySpec keySpec = new SecretKeySpec(securityKey.getBytes("UTF-8"), "AES");
cipher.init(Cipher.ENCRYPT_MODE, keySpec);
String encrypted = Base64.getEncoder().encodeToString(cipher.doFinal(rawJson.getBytes("UTF-8")));
// Decryption
cipher.init(Cipher.DECRYPT_MODE, keySpec);
byte[] decoded = Base64.getDecoder().decode(encryptedPayload);
String decrypted = new String(cipher.doFinal(decoded), "UTF-8");