Support Hub/API & Integrations/Creare un ricevitore di callback biometrico in Python,…
Translated from the English article and reviewed by a person. Read the English original
Developer

Creare un ricevitore di callback biometrico in Python, Node.js e PHP

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.

1

Scarica il file del prompt

Scegli il tuo linguaggio nella sezione successiva e scarica il relativo file di prompt in formato .txt.

2

Incollalo in un assistente AI

Apri Claude, ChatGPT, Copilot o qualsiasi strumento di programmazione con AI e incolla l'intero contenuto del prompt.

3

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.

Python

Flask, SQLite, solo libreria standard

Scarica il prompt Python

Node.js

Express, archivio JSON su file

Scarica il prompt Node.js

PHP

PHP puro, SQLite, senza Composer

Scarica il prompt PHP

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.

 

Was this article helpful?