Crearea unui receptor de callback biometric în Python, Node.js și PHP
Un receptor de callback este mica parte de cod care transformă fiecare scanare a amprentei, feței sau cardului într-o înregistrare în propriul dvs. sistem. Cams Biometrics Gateway trimite fiecare scanare verificată către serverul dvs. ca o cerere JSON, iar serverul dvs. răspunde pentru a confirma că aceasta a fost primită. Nu trebuie să scrieți acel receptor de la zero. Cams oferă AI Code Generator Prompts pentru Python, Node.js și PHP: lipiți unul într-un asistent AI, precum Claude sau ChatGPT, și veți obține un fișier complet funcțional, cu un receptor de callback, un client REST și o interfață de testare. Acest tutorial explică ce trebuie să facă un receptor, cum să generați unul pentru limbajul dvs., cum să îl configurați și cum să îl testați înainte de punerea în funcțiune.
01 · Cele șase sarcini
Ce trebuie să facă un receptor de callback
Indiferent de limbajul utilizat, fiecare receptor de callback biometric îndeplinește aceleași șase sarcini. Acestea sunt, de asemenea, lucrurile pe care trebuie să le verificați în orice cod generat.
| Sarcina | Ce înseamnă | De ce contează |
|---|---|---|
| 1. Acceptați cererea | Primiți un HTTP/HTTPS POST cu un corp JSON brut | Așa livrează Gateway fiecare eveniment |
| 2. Verificați tokenul | Verificați AuthToken în raport cu tokenul de callback așteptat | Împiedică pe oricine altcineva să trimită prezențe false către URL-ul dvs. |
| 3. Direcționați după tipul evenimentului | Verificați ce cheie se află în RealTime și procesați-o corespunzător | Nu fiecare callback este o pontare; unele raportează fotografii sau modificări ale utilizatorilor |
| 4. Ignorați duplicatele | Folosiți OperationID pentru a ignora evenimentele deja salvate | O livrare repetată nu devine niciodată o înregistrare dublă |
| 5. Stocați și înregistrați în jurnal | Salvați câmpurile de care aveți nevoie și înregistrați în jurnal fiecare callback | Creează înregistrarea pe care o vor folosi HRMS, statul de plată sau tabloul de bord |
| 6. Răspundeți cu done | Returnați {“status”:”done”} cu HTTP 200 | Îi spune Gateway că evenimentul a ajuns în siguranță |
02 · Cunoașteți-vă datele
Datele pe care le veți primi
Cel mai frecvent callback este un jurnal de pontaj, trimis de fiecare dată când cineva scanează. Salvați acest exemplu ca sample.json, deoarece îl veți folosi ulterior pentru a testa receptorul.
|
Callback API, cererea PunchLog trimisă receptorului dvs. {
"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"
}
}
|
După procesarea oricărui callback, receptorul dvs. trebuie să răspundă cu HTTP 200 și exact acest corp:
|
Callback API, răspunsul pe care receptorul dvs. trebuie să îl returneze { "status": "done" } (HTTP 200)
|
Tipurile de evenimente callback
Fiecare callback sosește în interiorul unui obiect RealTime. Receptorul dvs. decide ce are de făcut verificând care dintre aceste chei este prezentă:
| Cheia din RealTime | Ce raportează |
|---|---|
| PunchLog | O scanare de prezență: cine, intrare sau ieșire, când și cum |
| UserUpdated | Datele unui utilizator au fost actualizate pe dispozitiv |
Două detalii care îi surprind pe dezvoltatori
| Detaliu | La ce să fiți atenți |
|---|---|
| Cheia de răspuns este scrisă cu litere mici | Returnați status cu litere mici și valoarea done. Nu copiați câmpul Status scris cu majusculă din răspunsurile RESTful API |
| Formatul LogTime | LogTime arată ca 2020-09-17 07:48:22 GMT +0530. Este ora reală a scanării, cu decalajul dispozitivului. Analizați-o cu decalajul și folosiți-o ca oră a prezenței |
03 · Lăsați AI-ul să scrie codul
Generați receptorul cu AI Code Generator Prompts
Cams publică un fișier de prompt gata de utilizare pentru fiecare limbaj de server suportat. Fiecare prompt conține un rezumat al specificației Cams Web API 3.0 și instrucțiuni clare despre ce trebuie construit. Îl lipiți într-un asistent AI, iar asistentul generează o implementare completă, dintr-un singur fișier, pentru stiva dvs. tehnologică.
|
Descărcați fișierul de prompt Alegeți limbajul în secțiunea următoare și descărcați fișierul de prompt .txt corespunzător. |
|
|
Lipiți-l într-un asistent AI Deschideți Claude, ChatGPT, Copilot sau orice instrument AI de programare și lipiți întregul conținut al promptului. |
|
|
Obțineți un fișier complet funcțional AI-ul generează un singur fișier. Setați valorile de configurare, implementați-l și rulați-l. |
| Fiecare fișier generat include | Ce face |
|---|---|
| Receptor de callback | Citește corpul POST brut, validează AuthToken, direcționează după tipul evenimentului, înregistrează în jurnal fiecare callback, stochează jurnalele de pontaj, salvează fotografiile de prezență și răspunde cu done |
| Client REST | O funcție generică de cerere, plus funcții wrapper pentru toate cele 27 de operațiuni RESTful, precum AddUser, DeleteUser, ResendAllUser și UpdateAccessTime |
| Interfață HTML de testare | O pagină de browser cu câmpurile dvs. de configurare, un meniu derulant cu operațiuni, un editor JSON precompletat cu șabloane de cerere, un vizualizator de răspunsuri și o listă cu callback-urile recente |
|
Mai întâi documentația online Fiecare prompt îi cere AI-ului să citească documentația completă Cams Web API și să o trateze drept sursa autorizată pentru operațiuni, scheme JSON, nume de câmpuri și coduri de răspuns. Dacă ceva din rezumatul promptului intră în conflict cu documentația online, documentația are prioritate. |
04 · Alegeți limbajul
Prompturi pentru Python, Node.js și PHP
Fiecare prompt este ajustat pentru a produce cod idiomatic, cu dependențe minime pentru limbajul respectiv.
|
|
|
Prompturile sunt disponibile și pentru C# (.NET 8) cu Minimal API, Java cu HttpServer integrat și fără dependențe, Go cu net/http și doar biblioteca standard, și Ruby cu Sinatra și SQLite. Le puteți găsi pe toate în secțiunea AI Code Generator Prompts din documentația Cams Web API. Obțineți prompturile.
05 · Trei valori de setat
Configurarea fișierului generat
Fișierul generat are în partea de sus un bloc de configurare. În versiunea PHP arată astfel, iar celelalte limbaje folosesc aceleași trei valori:
|
Bloc de configurare, versiunea PHP $CONFIG = [
'base_url' => 'https://YOUR_RESTFUL_ENDPOINT_URL',
'stgid' => 'YOUR_SERVICE_TAG_ID',
'auth_token' => 'YOUR_AUTH_TOKEN',
];
|
| Setare | Ce să introduceți |
|---|---|
| base_url | URL-ul endpoint-ului RESTful din contul dvs. Cams API Monitor |
| stgid | ID-ul dvs. Service Tag. |
| auth_token | AuthToken-ul dvs., inclus în cererile RESTful trimise și verificat în raport cu AuthToken-ul din cererile de callback primite. |
|
Nu lăsați tokenurile în cod partajat Pentru un test rapid, introducerea valorilor direct în blocul de configurare este acceptabilă. Înainte de producție, mutați tokenurile în variabile de mediu sau într-un manager de secrete, astfel încât acestea să nu ajungă niciodată în sistemul de control al versiunilor sau într-un fișier partajat. |
Odată configurat și implementat la o adresă HTTPS publică, setați această adresă ca Callback URL în Cams Gateway. De atunci, fiecare scanare verificată ajunge în timp real la receptorul dvs.
06 · Testați înainte de a conecta dispozitivele
Testarea receptorului
Nu aveți nevoie de un dispozitiv biometric pentru a testa receptorul de callback. Trimiteți-i singur exemplul de date cu cURL, folosind un token de callback corespunzător, și verificați răspunsul.
|
Terminal, trimiteți un callback de test # Save the sample payload as sample.json, then send it to your receiver:
curl -X POST https://YOUR_SERVER/YOUR_CALLBACK_PATH \
-H "Content-Type: application/json" \
-d @sample.json
# Expected response (HTTP 200):
# {"status":"done"}
|
| Test | Ce să trimiteți | Rezultat așteptat |
|---|---|---|
| Eveniment valid | sample.json, cu AuthToken setat la auth_token-ul dvs. | HTTP 200 cu done, iar pontajul este salvat |
| Eveniment duplicat | Aceeași cerere a doua oară | HTTP 200 cu done, iar nicio a doua înregistrare nu este salvată |
| Token greșit | sample.json cu un alt AuthToken | Respins, iar nimic nu este salvat |
| Eveniment de intrare | sample.json cu Type schimbat în CheckIn | Salvat ca intrare |
| Operațiune RESTful | Folosiți interfața HTML de testare integrată pentru a trimite o operațiune | Un răspuns cu Status și StatusCode |
Interfața HTML de testare generată face partea RESTful ușor de încercat: deschideți fișierul într-un browser, alegeți o operațiune din meniul derulant, ajustați JSON-ul precompletat și trimiteți-l. Vizualizatorul de callback-uri recente din aceeași pagină confirmă că aceste callback-uri de test au fost primite.
07 · Lista de verificare pentru producție
Verificați înainte de punerea în funcțiune
Codul generat de AI este un punct de plecare rapid și fiabil, dar, ca orice cod, trebuie verificat înainte de a procesa date reale ale angajaților.
| Element | Finalizat când |
|---|---|
| Cod verificat | Un dezvoltator a citit fișierul generat și înțelege ce face fiecare secțiune |
| Doar HTTPS | Receptorul este accesibil doar prin HTTPS, cu un certificat valid |
| Tokenuri protejate | AuthTokens sunt stocate în variabile de mediu sau într-un manager de secrete |
| Duplicatele sunt gestionate | OperationID este salvat și verificat, astfel încât livrările repetate sunt ignorate |
| Stocare adecvată | Stocarea în fișier JSON este suficientă pentru configurații mici; implementările mai mari pot trece la o bază de date de producție |
| Interfață de testare protejată | Pagina HTML de testare este protejată prin parolă sau dezactivată pe serverele publice |
| Fotografii tratate cu atenție | Fotografiile de prezență salvate pe disc au acces controlat și sunt păstrate doar cât este necesar |
| Monitorizare activă | Erorile și volumele neobișnuite de callback-uri sunt înregistrate în jurnal și semnalate de propriul dvs. sistem de monitorizare |
|
Păstrați regulile de business în alt loc Sarcina receptorului este să accepte, să verifice, să direcționeze, să stocheze și să confirme. Stabilirea cine întârzie, calcularea orelor suplimentare sau trimiterea notificărilor aparține sistemelor care citesc evenimentele stocate, precum HRMS, ERP sau instrumentele dvs. de automatizare. Un receptor concentrat este mai ușor de securizat și de întreținut. |
Întrebări frecvente
|
Trebuie să scriu eu însumi cod? De obicei, nu. AI Code Generator Prompts produc un fișier complet funcțional. Setați trei valori de configurare, implementați-l și testați-l. Un dezvoltator ar trebui totuși să verifice codul înainte de producție. |
|
Ce asistenți AI funcționează cu prompturile? Orice asistent AI capabil de programare, inclusiv Claude, ChatGPT și Copilot. Lipiți întregul conținut al promptului dintr-o dată, astfel încât asistentul să aibă specificația completă. |
|
Unde găsesc URL-ul endpoint-ului RESTful și ID-ul Service Tag? Ambele provin din contul dvs. Cams API Monitor. Cererile RESTful sunt trimise la URL-ul endpoint-ului, cu ?stgid= urmat de ID-ul dvs. Service Tag. |
|
De ce să răspund cu done pentru un eveniment duplicat? Pentru că evenimentul a ajuns în siguranță, chiar dacă l-ați salvat deja. Răspunsul cu done îi spune Gateway că nu trebuie să îl trimită din nou. |
|
Pot folosi un limbaj care nu este listat? Da. Receptorul de callback trebuie doar să accepte un HTTPS POST și să returneze JSON. Prompturile sunt o scurtătură, iar aceeași API funcționează cu orice limbaj care poate face asta. |
Concluzie: de la prompt la prezență în timp real, într-o după-amiază
Un receptor de callback biometric este mic, dar este piesa care transformă fiecare scanare verificată în date live pentru HRMS, statul de plată, tablourile de bord și automatizările dvs. Cu Cams AI Code Generator Prompts, nu mai trebuie să îl construiți de la zero. Descărcați promptul pentru Python, Node.js sau PHP, lipiți-l în asistentul AI, setați trei valori și testați. Apoi verificați-l, securizați-l și lăsați datele de prezență în timp real să înceapă să curgă.
Cams Biometrics Gateway livrează evenimentele de care are nevoie receptorul dvs. Callback API trimite fiecare scanare verificată în timp real, într-un format JSON consistent, de la dispozitive din peste 15 mărci, iar RESTful API oferă 27 de operațiuni pe care clientul dvs. generat le poate apela. Toată comunicarea se desfășoară prin HTTP/HTTPS, cu validarea auth token-ului și criptare AES-256 opțională. Explorați platforma la CamsBiometrics.com și citiți documentația completă Web API, inclusiv fiecare AI Code Generator Prompt: Obțineți prompturile.