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.

Riferimento API

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

Riferimento API

Campi comuni

Tutte le richieste — sia di callback sia RESTful — condividono questi campi di primo livello.

AuthTokenString. Token di 32 caratteri che identifica e autentica le richieste di un dispositivo specifico. Configurato nel portale API Monitor. Validalo a ogni callback in ingresso.

OperationIDString. Identificatore univoco di questa istanza di operazione (ad es. "j95xfejt3vr1"). Le risposte RESTful restituiscono lo stesso OperationID così puoi associare richieste e risposte.

TimeString. Timestamp UTC dell’elaborazione dell’evento, nel formato YYYY-MM-DD HH:mm:ss GMT +0000. I timestamp locali del dispositivo nel payload possono usare un fuso orario diverso.

stgid (parametro di query)String. Service Tag ID — identifica il dispositivo di destinazione per le chiamate API RESTful. Da passare come parametro di query nell’URL dell’endpoint disponibile nel tuo account API Monitor: 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:

Comportamento di unione dei template — importante per i gestori di callback
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 0
Non 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`

Riferimento API

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.

Informazioni aggiuntive

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.

HTTPS consigliato. Usa HTTPS con un certificato SSL valido in produzione. Assicurati che il rinnovo automatico avvenga senza riavviare il server.

Informazioni aggiuntive

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:

Questa paginaOgni sezione di operazione sopra include JSON di richiesta e risposta pronti da copiare, con dati di esempio.

Pagina di esempi precedentebiometric-web-api-sample-request-response.html — selettore a tendina per ogni operazione.

Informazioni aggiuntive

Crittografia

È possibile attivare la crittografia AES-256 opzionale per tutti i dati scambiati tra il Cams Protocol Engine e il tuo server.

AlgoritmoAES-256 in modalità ECB con padding PKCS5 (AES/ECB/PKCS5PADDING).

Configurazione della chiaveImposta la tua chiave come Security Key nell’API Monitor. Una volta configurata, tutti i payload JSON grezzi vengono crittografati.

CodificaI payload crittografati sono codificati in Base64 per un trasporto HTTP sicuro.

Esempio Java

Cifratura / Decifratura (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");

Importante: quando la crittografia è attiva, decifra i payload di callback in ingresso e cifra i corpi delle richieste RESTful in uscita con la stessa chiave.