Creare un ricevitore di callback biometrico in Python, Node.js e PHP
Un ricevitore di callback è il piccolo componente di codice che trasforma ogni scansione di impronta, volto o badge in un record nel tuo sistema. Cams Biometrics Gateway invia ogni scansione verificata al tuo server come richiesta JSON, e il tuo server risponde per confermare la ricezione. Non è necessario scrivere questo ricevitore da zero. Cams mette a disposizione i Prompt per la generazione di codice con AI per Python, Node.js e PHP: incolla uno di questi prompt in un assistente AI come Claude o ChatGPT e otterrai un file completo e funzionante, con un ricevitore di callback, un client REST e un'interfaccia di test. Questa guida spiega cosa deve fare un ricevitore, come generarne uno per il tuo linguaggio, come configurarlo e come testarlo prima di andare in produzione.
01 · Le sei funzioni
Cosa deve fare un ricevitore di callback
Indipendentemente dal linguaggio utilizzato, ogni ricevitore di callback biometrico svolge le stesse sei funzioni. Sono anche i punti da verificare in qualsiasi codice generato.
| Funzione | Cosa significa | Perché è importante |
|---|---|---|
| 1. Accettare la richiesta | Ricevere una POST HTTP/HTTPS con un corpo JSON non elaborato | È così che il Gateway consegna ogni evento |
| 2. Verificare il token | Controllare che l'AuthToken corrisponda al token di callback atteso | Impedisce a terzi di inviare presenze false al tuo URL |
| 3. Instradare per tipo di evento | Verificare quale chiave è presente all'interno di RealTime e gestirla di conseguenza | Non tutti i callback sono timbrature; alcuni riportano foto o modifiche agli utenti |
| 4. Saltare i duplicati | Usare OperationID per ignorare gli eventi già salvati | Una consegna ripetuta non genera mai un record doppio |
| 5. Salvare e registrare | Salvare i campi necessari e registrare ogni callback | Crea il record che useranno il tuo HRMS, la paghe o la dashboard |
| 6. Rispondere con done | Restituire {“status”:”done”} con HTTP 200 | Comunica al Gateway che l'evento è arrivato correttamente |
02 · Conosci i tuoi dati
Il payload che riceverai
Il callback più comune è un registro di timbratura, inviato ogni volta che una persona effettua una scansione. Salva questo esempio come sample.json, perché lo userai più avanti per testare il ricevitore.
|
Callback API, richiesta PunchLog inviata al ricevitore {
"RealTime": {
"OperationID": "9nu1wak5616p",
"LabelName": "Burj Khalifa",
"SerialNumber": "ZHM11xxxxxxxx",
"PunchLog": {
"Type": "CheckOut",
"Temperature": "36.8",
"FaceMask": false,
"InputType": "Fingerprint",
"UserId": "2",
"LogTime": "2020-09-17 07:48:22 GMT +0530"
},
"AuthToken": "COJJ7eiIPBGUfmIQPvh2PJWWDLX7OuKs",
"Time": "2020-09-17 04:19:03 GMT +0000"
}
}
|
Dopo aver gestito qualsiasi callback, il ricevitore deve rispondere con HTTP 200 e esattamente questo corpo:
|
Callback API, risposta che il ricevitore deve restituire { "status": "done" } (HTTP 200)
|
Tipi di evento di callback
Ogni callback arriva all'interno di un oggetto RealTime. Il ricevitore decide cosa fare controllando quale di queste chiavi è presente:
| Chiave all'interno di RealTime | Cosa riporta |
|---|---|
| PunchLog | Una scansione di presenza: chi, entrata o uscita, quando e come |
| UserUpdated | I dati di un utente sono stati aggiornati sul dispositivo |
Due dettagli che spesso sfuggono agli sviluppatori
| Dettaglio | Su cosa prestare attenzione |
|---|---|
| La chiave della risposta è in minuscolo | Restituire status in minuscolo con il valore done. Non copiare il campo Status con la maiuscola dalle risposte delle RESTful API |
| Il formato di LogTime | LogTime ha un formato come 2020-09-17 07:48:22 GMT +0530. È l'orario reale della scansione con lo scostamento del dispositivo. Analizzalo tenendo conto dello scostamento e usalo come orario di presenza |
03 · Lascia che l'AI scriva il codice
Genera il tuo ricevitore con i Prompt per la generazione di codice AI
Cams pubblica un file di prompt pronto all'uso per ogni linguaggio server supportato. Ogni prompt contiene un riepilogo della specifica Cams Web API 3.0 e istruzioni chiare su cosa costruire. Lo incolli in un assistente AI e l'assistente genera un'implementazione completa in un singolo file per il tuo stack.
|
Scarica il file del prompt Scegli il tuo linguaggio nella sezione successiva e scarica il relativo file di prompt in formato .txt. |
|
|
Incollalo in un assistente AI Apri Claude, ChatGPT, Copilot o qualsiasi strumento di programmazione con AI e incolla l'intero contenuto del prompt. |
|
|
Ottieni un file completo e funzionante L'AI genera un singolo file. Imposta i valori di configurazione, distribuiscilo ed eseguilo. |
| Ogni file generato include | Cosa fa |
|---|---|
| Ricevitore di callback | Legge il corpo POST non elaborato, convalida l'AuthToken, instrada per tipo di evento, registra ogni callback, salva i registri di timbratura, salva le foto di presenza e risponde con done |
| Client REST | Una funzione generica di richiesta e funzioni wrapper per tutte le 27 operazioni RESTful, come AddUser, DeleteUser, ResendAllUser e UpdateAccessTime |
| Interfaccia di test HTML | Una pagina del browser con i campi di configurazione, un menu a tendina delle operazioni, un editor JSON precompilato con modelli di richiesta, un visualizzatore delle risposte e un elenco dei callback recenti |
|
Prima di tutto la documentazione online Ogni prompt indica all'AI di leggere l'intera documentazione di Cams Web API e di considerarla come fonte di riferimento per operazioni, schemi JSON, nomi dei campi e codici di risposta. Se qualcosa nel riepilogo del prompt non corrisponde alla documentazione online, prevale la documentazione. |
04 · Scegli il tuo linguaggio
Prompt per Python, Node.js e PHP
Ogni prompt è ottimizzato per produrre codice idiomatico con dipendenze minime per il proprio linguaggio.
|
|
|
I prompt sono disponibili anche per C# (.NET 8) con Minimal API, Java con il server HttpServer integrato e senza dipendenze, Go con net/http e solo la libreria standard, e Ruby con Sinatra e SQLite. Li trovi tutti nella sezione Prompt per la generazione di codice AI della documentazione di Cams Web API. Ottieni i prompt.
05 · Tre valori da impostare
Configurazione del file generato
Il file generato ha un blocco di configurazione in cima. Nella versione PHP appare così, mentre gli altri linguaggi usano gli stessi tre valori:
|
Blocco di configurazione, versione PHP $CONFIG = [
'base_url' => 'https://YOUR_RESTFUL_ENDPOINT_URL',
'stgid' => 'YOUR_SERVICE_TAG_ID',
'auth_token' => 'YOUR_AUTH_TOKEN',
];
|
| Impostazione | Cosa inserire |
|---|---|
| base_url | L'URL dell'endpoint RESTful dal tuo account Cams API Monitor |
| stgid | Il tuo Service Tag ID. |
| auth_token | Il tuo AuthToken, incluso nelle richieste RESTful in uscita e verificato rispetto all'AuthToken presente nelle richieste di callback in entrata. |
|
Tieni i token fuori dal codice condiviso Per un test rapido, inserire i valori direttamente nel blocco di configurazione va bene. Prima della produzione, sposta i token in variabili d'ambiente o in un gestore di segreti, così non finiranno mai nel controllo di versione o in un file condiviso. |
Una volta configurato e distribuito a un indirizzo HTTPS pubblico, imposta questo indirizzo come URL di callback in Cams Gateway. Da quel momento, ogni scansione verificata raggiungerà il tuo ricevitore in tempo reale.
06 · Testa prima di collegare i dispositivi
Test del ricevitore
Non serve un dispositivo biometrico per testare il ricevitore di callback. Invia tu stesso il payload di esempio con cURL, usando un token di callback corrispondente, e verifica la risposta.
|
Terminale, invia un callback di test # Salva il payload di esempio come sample.json, poi invialo al ricevitore:
curl -X POST https://YOUR_SERVER/YOUR_CALLBACK_PATH \
-H "Content-Type: application/json" \
-d @sample.json
# Risposta attesa (HTTP 200):
# {"status":"done"}
|
| Test | Cosa inviare | Risultato atteso |
|---|---|---|
| Evento valido | sample.json, con AuthToken impostato sul tuo auth_token | HTTP 200 con done, e la timbratura viene salvata |
| Evento duplicato | La stessa richiesta una seconda volta | HTTP 200 con done, e non viene salvato alcun secondo record |
| Token errato | sample.json con un AuthToken diverso | Rifiutata, e non viene salvato nulla |
| Evento di entrata | sample.json con Type modificato in CheckIn | Salvato come entrata |
| Operazione RESTful | Usa l'interfaccia di test HTML integrata per inviare un'operazione | Una risposta con Status e StatusCode |
L'interfaccia di test HTML generata rende facile provare la parte RESTful: apri il file in un browser, scegli un'operazione dal menu a tendina, modifica il JSON precompilato e invialo. Il visualizzatore dei callback recenti nella stessa pagina conferma che i callback di test sono stati ricevuti.
07 · Checklist per la produzione
Verifica prima di andare online
Il codice generato dall'AI è un punto di partenza rapido e affidabile, ma come ogni codice va verificato prima di gestire dati reali dei dipendenti.
| Voce | Completato quando |
|---|---|
| Codice verificato | Uno sviluppatore ha letto il file generato e comprende la funzione di ogni sezione |
| Solo HTTPS | Il ricevitore è raggiungibile solo tramite HTTPS con un certificato valido |
| Token protetti | Gli AuthToken sono conservati in variabili d'ambiente o in un gestore di segreti |
| Duplicati gestiti | OperationID viene memorizzato e verificato, così le consegne ripetute vengono ignorate |
| Archiviazione adeguata | L'archivio JSON su file va bene per installazioni piccole; le implementazioni più grandi possono passare a un database di produzione |
| Interfaccia di test protetta | La pagina di test HTML è protetta da password o disattivata sui server pubblici |
| Foto gestite con cura | Le foto di presenza salvate su disco hanno accessi controllati e vengono conservate solo per il tempo necessario |
| Monitoraggio attivo | Errori e volumi anomali di callback vengono registrati e segnalati dal tuo sistema di monitoraggio |
|
Tieni le regole di business altrove Il compito del ricevitore è accettare, verificare, instradare, salvare e confermare. Decidere chi è in ritardo, calcolare gli straordinari o inviare comunicazioni spetta ai sistemi che leggono gli eventi salvati, come il tuo HRMS, l'ERP o gli strumenti di automazione. Un ricevitore essenziale è più facile da proteggere e manutenere. |
Domande frequenti
|
Devo scrivere io stesso del codice? Di solito no. I Prompt per la generazione di codice AI producono un file completo e funzionante. Imposti tre valori di configurazione, lo distribuisci e lo testi. Uno sviluppatore dovrebbe comunque verificare il codice prima della produzione. |
|
Quali assistenti AI funzionano con i prompt? Qualsiasi assistente di programmazione AI valido, inclusi Claude, ChatGPT e Copilot. Incolla l'intero contenuto del prompt in una sola volta, così l'assistente disporrà della specifica completa. |
|
Dove trovo l'URL dell'endpoint RESTful e il Service Tag ID? Entrambi provengono dal tuo account Cams API Monitor. Le richieste RESTful vengono inviate all'URL dell'endpoint con ?stgid= seguito dal tuo Service Tag ID. |
|
Perché rispondere con done per un evento duplicato? Perché l'evento è effettivamente arrivato correttamente, anche se lo avevi già salvato. Rispondere con done comunica al Gateway che non deve inviarlo di nuovo. |
|
Posso usare un linguaggio non elencato? Sì. Il ricevitore di callback deve solo accettare una POST HTTPS e restituire JSON. I prompt sono una scorciatoia, e la stessa API funziona con qualsiasi linguaggio in grado di farlo. |
Conclusione: dal prompt alla presenza in tempo reale in un pomeriggio
Un ricevitore di callback biometrico è un componente piccolo, ma è quello che trasforma ogni scansione verificata in dati in tempo reale per il tuo HRMS, la paghe, le dashboard e le automazioni. Con i Prompt per la generazione di codice AI di Cams, non devi più costruirlo partendo da zero. Scarica il prompt per Python, Node.js o PHP, incollalo nel tuo assistente AI, imposta tre valori e testa. Poi verificalo, proteggilo e lascia che i dati di presenza in tempo reale inizino a fluire.
Cams Biometrics Gateway fornisce gli eventi di cui il tuo ricevitore ha bisogno. La sua Callback API invia ogni scansione verificata in tempo reale, in un unico formato JSON coerente, da dispositivi di oltre 15 marchi, e la sua RESTful API offre 27 operazioni che il client generato può richiamare. Tutte le comunicazioni avvengono tramite HTTP/HTTPS con validazione del token di autenticazione e crittografia AES-256 opzionale. Scopri la piattaforma su CamsBiometrics.com e leggi la documentazione completa di Web API, inclusi tutti i Prompt per la generazione di codice AI: Ottieni i prompt.