FAQ, SDK e costi
Le domande più frequenti degli integratori, oltre al funzionamento di SDK e prezzi dell’API.
Informazioni aggiuntive
Domande frequenti
Domande comuni sull’integrazione con la Web API 3.0 di Cams Biometrics.
Generale
Q: Cos’è la Cams Biometric Gateway e la sua API biometrica?
La Cams Biometric Gateway è una piattaforma cloud universale che espone un’API biometrica che consente a qualsiasi applicazione web di comunicare in tempo reale con dispositivi biometrici di rilevazione presenze e controllo accessi. Supporta 38 operazioni tra API di callback (in ingresso) e RESTful (in uscita) — senza richiedere alcun SDK del dispositivo né un IP statico.
La Cams Biometric Gateway è una piattaforma cloud universale che espone un’API biometrica che consente a qualsiasi applicazione web di comunicare in tempo reale con dispositivi biometrici di rilevazione presenze e controllo accessi. Supporta 38 operazioni tra API di callback (in ingresso) e RESTful (in uscita) — senza richiedere alcun SDK del dispositivo né un IP statico.
Q: Mi serve un SDK per integrare?
No. Cams non fornisce né richiede alcun SDK. Tutta la comunicazione usa richieste HTTP/HTTPS POST standard con payload JSON. Va bene qualsiasi linguaggio in grado di effettuare chiamate HTTP.
No. Cams non fornisce né richiede alcun SDK. Tutta la comunicazione usa richieste HTTP/HTTPS POST standard con payload JSON. Va bene qualsiasi linguaggio in grado di effettuare chiamate HTTP.
Q: Quali linguaggi di programmazione sono supportati?
Qualsiasi linguaggio in grado di inviare/ricevere HTTP POST con JSON — PHP, Python, Java, C#, Node.js, Go, Ruby e altri. Forniamo prompt IA per generare codice per 7 linguaggi.
Qualsiasi linguaggio in grado di inviare/ricevere HTTP POST con JSON — PHP, Python, Java, C#, Node.js, Go, Ruby e altri. Forniamo prompt IA per generare codice per 7 linguaggi.
Q: Cos’è il Cams Protocol Engine?
È il middleware cloud che si trova tra i dispositivi biometrici e il tuo server. Gestisce la traduzione dei protocolli, la normalizzazione dei dati, la cache offline e offre un’API JSON coerente indipendentemente dalla marca o dal modello del dispositivo.
È il middleware cloud che si trova tra i dispositivi biometrici e il tuo server. Gestisce la traduzione dei protocolli, la normalizzazione dei dati, la cache offline e offre un’API JSON coerente indipendentemente dalla marca o dal modello del dispositivo.
Q: Cos’è l’API Monitor?
L’API Monitor è il tuo portale di amministrazione dove configuri gli URL di callback, gestisci gli AuthToken, imposti le Security Key, consulti lo stato dei dispositivi e accedi all’URL del tuo endpoint RESTful e ai Service Tag ID.
L’API Monitor è il tuo portale di amministrazione dove configuri gli URL di callback, gestisci gli AuthToken, imposti le Security Key, consulti lo stato dei dispositivi e accedi all’URL del tuo endpoint RESTful e ai Service Tag ID.
Compatibilità dei dispositivi
Q: Quali dispositivi biometrici sono supportati?
Tutti i dispositivi Cams Biometrics (elencati su camsbiometrics.com/product) supportano l’API completa con Native Push. Anche i dispositivi verificati su developer.camsbiometrics.com hanno il pieno supporto Native Push.
Tutti i dispositivi Cams Biometrics (elencati su camsbiometrics.com/product) supportano l’API completa con Native Push. Anche i dispositivi verificati su developer.camsbiometrics.com hanno il pieno supporto Native Push.
Q: I dispositivi non Cams (ZkTeco, eSSL, BioMax, ecc.) possono usare questa API?
Sì, con un Protocol Update. I dispositivi non Cams e non verificati funzionano tramite Hybrid Push. Alcune funzionalità possono essere limitate a seconda della modalità di connessione e delle capacità hardware.
Sì, con un Protocol Update. I dispositivi non Cams e non verificati funzionano tramite Hybrid Push. Alcune funzionalità possono essere limitate a seconda della modalità di connessione e delle capacità hardware.
Q: Qual è la differenza tra Native Push e Hybrid Push?
Native Push: supporto API completo senza limitazioni — tutte le 38 operazioni funzionano. Disponibile per i dispositivi Cams e quelli verificati.
Hybrid Push: per i dispositivi non Cams/non verificati. La disponibilità delle funzionalità dipende dalla modalità di comunicazione (SDK, lettura del database o elaborazione di file). Vedi Modalità di connessione.
Native Push: supporto API completo senza limitazioni — tutte le 38 operazioni funzionano. Disponibile per i dispositivi Cams e quelli verificati.
Hybrid Push: per i dispositivi non Cams/non verificati. La disponibilità delle funzionalità dipende dalla modalità di comunicazione (SDK, lettura del database o elaborazione di file). Vedi Modalità di connessione.
Q: Quali metodi biometrici sono supportati?
Impronta digitale, riconoscimento facciale, vene del palmo, badge RFID/di prossimità, PIN/password numerico, scansione dell’iride e misurazione della temperatura corporea (a seconda del dispositivo).
Impronta digitale, riconoscimento facciale, vene del palmo, badge RFID/di prossimità, PIN/password numerico, scansione dell’iride e misurazione della temperatura corporea (a seconda del dispositivo).
Q: Alcune funzionalità dell’API non funzionano con il mio dispositivo. Perché?
Dipende (a) dalla modalità di connessione — le modalità lettura del database ed elaborazione di file supportano solo l’invio delle presenze, non le API RESTful, e (b) dai limiti hardware — alcuni modelli di dispositivo potrebbero non supportare funzioni specifiche a livello di firmware. Testa con il tuo hardware e contatta il supporto Cams per assistenza.
Dipende (a) dalla modalità di connessione — le modalità lettura del database ed elaborazione di file supportano solo l’invio delle presenze, non le API RESTful, e (b) dai limiti hardware — alcuni modelli di dispositivo potrebbero non supportare funzioni specifiche a livello di firmware. Testa con il tuo hardware e contatta il supporto Cams per assistenza.
API di callback (Dispositivo → Server)
Q: Cos’è l’API di callback?
L’API di callback consegna in tempo reale al tuo server gli eventi dei dispositivi biometrici. Quando avviene una timbratura o un utente viene modificato sul dispositivo, il Cams Protocol Engine invia immediatamente (POST) un payload JSON al tuo URL di callback configurato.
L’API di callback consegna in tempo reale al tuo server gli eventi dei dispositivi biometrici. Quando avviene una timbratura o un utente viene modificato sul dispositivo, il Cams Protocol Engine invia immediatamente (POST) un payload JSON al tuo URL di callback configurato.
Q: Cosa deve rispondere il mio server?
Restituisci sempre
Restituisci sempre
{"status":"done"} con stato HTTP 200 — anche se l’elaborazione interna fallisce. Non bloccare mai il Cams Protocol Engine. Metti in coda le elaborazioni pesanti per l’esecuzione asincrona.Q: Cosa succede se il mio server è offline quando avviene una timbratura?
La Biometric Gateway mette in cache tutti gli eventi e li consegna automaticamente non appena il tuo server torna online. Nessun dato viene perso.
La Biometric Gateway mette in cache tutti gli eventi e li consegna automaticamente non appena il tuo server torna online. Nessun dato viene perso.
Q: Come gestisco le timbrature duplicate?
Implementa sul tuo server una logica di rilevamento dei duplicati usando la combinazione
Implementa sul tuo server una logica di rilevamento dei duplicati usando la combinazione
UserID + LogTime. La stessa timbratura può essere reinviata durante il recupero dopo un periodo offline o nei tentativi di rete.Q: Quali tipi di timbratura sono supportati?
CheckIn, CheckOut, BreakOut, BreakIn, OverTimeIn, OverTimeOut, MealIn, MealOut. Il campo InputType indica il metodo biometrico usato: Fingerprint, Face, Palm, Card o Password.Q: Come funzionano i template utente nei callback?
Quando un utente viene aggiornato sul dispositivo (operazioni n. 3–9), i template possono arrivare uno alla volta o in gruppi su più callback. Ogni callback trasporta solo i template modificati — non l’intero set. Il tuo server deve eseguire un merge/upsert usando
Quando un utente viene aggiornato sul dispositivo (operazioni n. 3–9), i template possono arrivare uno alla volta o in gruppi su più callback. Ogni callback trasporta solo i template modificati — non l’intero set. Il tuo server deve eseguire un merge/upsert usando
Type + Index come chiave univoca. Non sovrascrivere mai tutti i template con un singolo callback.Q: Posso ricevere le foto di presenza?
Sì. L’operazione n. 10 RealTimeAttendancePhoto consegna un’istantanea JPEG codificata Base64 acquisita al momento della timbratura. È separata dal callback del log di timbratura (n. 11) e disponibile sui dispositivi con fotocamera.
Sì. L’operazione n. 10 RealTimeAttendancePhoto consegna un’istantanea JPEG codificata Base64 acquisita al momento della timbratura. È separata dal callback del log di timbratura (n. 11) e disponibile sui dispositivi con fotocamera.
Q: Il callback include temperatura e rilevamento della mascherina?
Sì, se il dispositivo lo supporta. L’oggetto
Sì, se il dispositivo lo supporta. L’oggetto
PunchLog include Temperature (lettura della temperatura corporea) e FaceMask (booleano — indica se è stata rilevata una mascherina).API RESTful (Server → Dispositivo)
Q: Cos’è l’API RESTful?
L’API RESTful consente al tuo server di inviare comandi ai dispositivi biometrici — aggiunta/eliminazione di utenti, caricamento dei log, registrazione di dati biometrici e controllo degli accessi. Invii (POST) JSON all’URL dell’endpoint disponibile nel tuo account API Monitor.
L’API RESTful consente al tuo server di inviare comandi ai dispositivi biometrici — aggiunta/eliminazione di utenti, caricamento dei log, registrazione di dati biometrici e controllo degli accessi. Invii (POST) JSON all’URL dell’endpoint disponibile nel tuo account API Monitor.
Q: Dove trovo l’URL del mio endpoint RESTful?
Accedi al tuo account API Monitor. L’URL del tuo endpoint RESTful e i Service Tag ID (
Accedi al tuo account API Monitor. L’URL del tuo endpoint RESTful e i Service Tag ID (
stgid) sono elencati lì.Q: Qual è la latenza dei comandi RESTful?
Circa 15 secondi. La Biometric Gateway mette in coda il comando e lo consegna al dispositivo alla sua connessione successiva (quasi continua per i dispositivi online).
Circa 15 secondi. La Biometric Gateway mette in coda il comando e lo consegna al dispositivo alla sua connessione successiva (quasi continua per i dispositivi online).
Q: Qual è l’intervallo di date massimo per LoadLog?
Il massimo consigliato è 30 giorni per richiesta. Per intervalli più ampi, effettua più richieste con finestre temporali consecutive.
Il massimo consigliato è 30 giorni per richiesta. Per intervalli più ampi, effettua più richieste con finestre temporali consecutive.
Q: Posso aggiungere un utente con più template biometrici in una sola volta?
Sì. L’array Template accetta più voci. Ad esempio, l’operazione n. 27 aggiunge un utente con Badge + Impronta + Password + Volto + Palmo + UserPhoto in un’unica richiesta.
Sì. L’array Template accetta più voci. Ad esempio, l’operazione n. 27 aggiunge un utente con Badge + Impronta + Password + Volto + Palmo + UserPhoto in un’unica richiesta.
Q: Cosa succede se il dispositivo è offline quando invio un comando RESTful?
La Biometric Gateway mette il comando in coda e lo consegna automaticamente quando il dispositivo si riconnette. Riceverai il codice di stato
La Biometric Gateway mette il comando in coda e lo consegna automaticamente quando il dispositivo si riconnette. Riceverai il codice di stato
5 (Dispositivo offline) se il dispositivo non risponde entro il tempo limite.Q: Come verifico il risultato di un comando?
Le risposte RESTful includono un campo
Le risposte RESTful includono un campo
StatusCode. Il codice 0 significa successo. Vedi i codici di stato della risposta per l’elenco completo dei codici di errore e del loro significato.Q: Posso avviare da remoto la registrazione di un’impronta digitale?
Sì. L’operazione n. 35 EnrollFingerPrint avvia una sessione di registrazione sul dispositivo. Tuttavia, l’utente deve essere fisicamente presente davanti al dispositivo per scansionare il dito.
Sì. L’operazione n. 35 EnrollFingerPrint avvia una sessione di registrazione sul dispositivo. Tuttavia, l’utente deve essere fisicamente presente davanti al dispositivo per scansionare il dito.
Sicurezza & rete
Q: Posso usare HTTPS per i callback?
Sì. HTTPS con un certificato SSL valido sulla porta 443 è pienamente supportato e consigliato per la produzione.
Sì. HTTPS con un certificato SSL valido sulla porta 443 è pienamente supportato e consigliato per la produzione.
Q: La crittografia è obbligatoria?
No. La crittografia AES-256 è opzionale. Per attivarla, configura una Security Key nell’API Monitor. Una volta attiva, tutti i payload JSON vengono cifrati/decifrati con AES/ECB/PKCS5PADDING e codifica Base64.
No. La crittografia AES-256 è opzionale. Per attivarla, configura una Security Key nell’API Monitor. Una volta attiva, tutti i payload JSON vengono cifrati/decifrati con AES/ECB/PKCS5PADDING e codifica Base64.
Q: Come verifico che un callback provenga davvero da Cams?
Ogni callback include un campo
Ogni callback include un campo
AuthToken. Confrontalo con il token configurato nel tuo API Monitor. Rifiuta qualsiasi richiesta con un token non corrispondente.Q: Quali porte devo aprire?
La porta
La porta
80 (HTTP) o 443 (HTTPS) per la produzione. La porta 8123 è disponibile solo per i test. Vedi Porte supportate.Q: Come testo in locale senza distribuire su un server?
Usa un IP pubblico con port forwarding, oppure uno strumento di tunneling come ngrok. Vedi Test in locale per una guida passo passo.
Usa un IP pubblico con port forwarding, oppure uno strumento di tunneling come ngrok. Vedi Test in locale per una guida passo passo.
Dati & considerazioni di progettazione
Q: Quale formato di dati usa l’API?
Tutte le richieste e risposte sono JSON grezzo con codifica UTF-8. Usa l’header
Tutte le richieste e risposte sono JSON grezzo con codifica UTF-8. Usa l’header
Content-Type: application/json. Nessuna codifica da form.Q: Quale formato di timestamp viene usato?
YYYY-MM-DD HH:mm:ss GMT +OFFSET (ad es. 2020-09-17 07:48:22 GMT +0530). Il campo Time è in UTC; i timestamp locali del dispositivo (come LogTime, OperationTime) possono usare un fuso orario diverso.Q: Come gestisco le timbrature offline e i dati retroattivi?
Progetta la tua applicazione in modo che accetti timbrature che arrivano fuori ordine cronologico. Quando un dispositivo era offline, invierà le timbrature in cache una volta riconnesso. Potrebbe essere necessario aggiornare retroattivamente lo stato di presenza (ad es. portare da «assente» a «presente» un utente mostrato come assente).
Progetta la tua applicazione in modo che accetti timbrature che arrivano fuori ordine cronologico. Quando un dispositivo era offline, invierà le timbrature in cache una volta riconnesso. Potrebbe essere necessario aggiornare retroattivamente lo stato di presenza (ad es. portare da «assente» a «presente» un utente mostrato come assente).
Q: Come determino ENTRATA/USCITA quando un utente ha più dispositivi?
Ordina tutte le timbrature di un utente per
Ordina tutte le timbrature di un utente per
LogTime su tutti i dispositivi, poi applica la tua logica di business. Non fare affidamento solo sul campo Type (CheckIn/CheckOut) di un singolo dispositivo se l’utente timbra su macchine diverse.Q: Cos’è l’OperationID e come devo usarlo?
Un identificatore univoco in forma di stringa per ogni operazione. Per i callback in ingresso è generato dalla Biometric Gateway. Per le richieste RESTful in uscita, devi generarne uno univoco per ogni richiesta (UUID o basato sul timestamp). La risposta lo restituisce così puoi correlare le coppie richiesta/risposta.
Un identificatore univoco in forma di stringa per ogni operazione. Per i callback in ingresso è generato dalla Biometric Gateway. Per le richieste RESTful in uscita, devi generarne uno univoco per ogni richiesta (UUID o basato sul timestamp). La risposta lo restituisce così puoi correlare le coppie richiesta/risposta.
Q: Come vengono memorizzati e trasmessi i template biometrici?
I dati biometrici (impronta digitale, volto, palmo, foto utente) sono codificati in Base64 nel campo
I dati biometrici (impronta digitale, volto, palmo, foto utente) sono codificati in Base64 nel campo
Data dell’oggetto Template. I template di impronta e volto includono anche Size (lunghezza in byte) e Index (numero della posizione). I numeri dei badge e i PIN sono semplici stringhe.Prezzi & licenze
Q: Come viene concessa in licenza l’API?
Per dispositivo biometrico. Il primo anno richiede l’attivazione dell’API + la licenza annuale. Gli anni successivi richiedono solo il rinnovo della licenza annuale. Vedi Costo dell’API per i prezzi.
Per dispositivo biometrico. Il primo anno richiede l’attivazione dell’API + la licenza annuale. Gli anni successivi richiedono solo il rinnovo della licenza annuale. Vedi Costo dell’API per i prezzi.
Q: Cosa succede se la mia licenza API scade?
La comunicazione API per quel dispositivo si interrompe fino al rinnovo della licenza. I tuoi dati esistenti non sono interessati, ma non verrà elaborato alcun nuovo callback né comando RESTful.
La comunicazione API per quel dispositivo si interrompe fino al rinnovo della licenza. I tuoi dati esistenti non sono interessati, ma non verrà elaborato alcun nuovo callback né comando RESTful.
Q: Esiste un’opzione on-premise?
Sì. Il Protocol Engine Lite può essere installato sul tuo server (Windows/Linux) per ambienti solo LAN o self-hosted. Contatta sales@camsbiometrics.com per i dettagli.
Sì. Il Protocol Engine Lite può essere installato sul tuo server (Windows/Linux) per ambienti solo LAN o self-hosted. Contatta sales@camsbiometrics.com per i dettagli.
Informazioni aggiuntive
SDK per presenze biometriche
Cams non fornisce un SDK tradizionale. Tutte le operazioni usano le API HTTP di callback e RESTful standard — nessuna installazione di librerie necessaria.
Nessun SDK necessario. La comunicazione è gestita interamente tramite il Cams Protocol Engine usando URL di callback ed endpoint HTTP RESTful.
Questo rende l’integrazione semplice con qualsiasi piattaforma web:
OpenERPERPNextZoho PeopleSAPTallyHRAPPOdooApplicazioni web su misura
Informazioni aggiuntive
Costo dell’API
Le licenze API sono fatturate per dispositivo biometrico. Primo anno = attivazione + licenza; anni successivi = solo rinnovo della licenza.
| Servizio | USD | Note |
|---|---|---|
| Native Push — Dispositivi Cams & verificati | ||
| Attivazione API | $120 | Una tantum per dispositivo. |
| Licenza API annuale | $60 – $120 | Rinnovo annuale richiesto. |
| Protocol Update (non Cams) | $120 – $280 | Una tantum. Abilita il protocollo Cams sui dispositivi non Cams. |
| Hybrid Push — ZKTeco, eSSL & tutte le marche di terze parti | ||
| Attivazione API | $150 | Una tantum per dispositivo. |
| Licenza API annuale | $90 – $150 | Rinnovo annuale richiesto. |
| Hybrid Connector (non verificato) | $150 – $300 | Una tantum. Richiesto per i dispositivi non verificati che usano Hybrid Push. |
| Hardware & altro | ||
| Hardware | $220 – $720 | Varia in base al modello. |
Protocol Engine Lite (on-premise) — Per ambienti solo LAN o self-hosted. Costo: $500–$10,000. Contatta le vendite per i dettagli.