Referință API: arhitectură, câmpuri și coduri de stare

Elementele comune tuturor operațiunilor: fluxul cererilor, câmpurile JSON comune, tipurile de șabloane, codurile de stare, porturile și criptarea payload-ului.

Referință API

Arhitectura API

Proprietate	Callback API	RESTful API
Inițiator	Dispozitiv / Biometric Gateway	Serverul dumneavoastră
Direcție	Dispozitiv → Serverul dumneavoastră	Serverul dumneavoastră → Dispozitiv
Latență	În timp real (milisecunde)	~15 secunde
Declanșator	Eveniment biometric pe dispozitiv	HTTP POST din codul dumneavoastră
Rolul dumneavoastră	Primiți & confirmați	Trimiteți comanda & interogați/așteptați răspunsul
Corpul răspunsului	`{"status":"done"}`	`{"Status":"done","OperationID":"…","StatusCode":0}`
Comportament offline	Păstrat în cache de motor; livrat când serverul revine online	Pus în coadă de motor; livrat când dispozitivul se reconectează

Referință API

Câmpuri comune

Toate cererile — atât Callback, cât și RESTful — au în comun aceste câmpuri de nivel superior.

AuthTokenString. Un token de 32 de caractere care identifică și autentifică cererile de la un anumit dispozitiv. Se configurează în portalul API Monitor. Validați-l la fiecare callback primit.

OperationIDString. Un identificator unic pentru această instanță a operațiunii (de ex. "j95xfejt3vr1"). Răspunsurile RESTful returnează același OperationID, astfel încât să puteți asocia cererile cu răspunsurile.

TimeString. Marcaj temporal UTC al momentului în care evenimentul a fost procesat, în formatul YYYY-MM-DD HH:mm:ss GMT +0000. Marcajele temporale locale ale dispozitivului din payload pot folosi un alt decalaj de fus orar.

stgid (parametru de interogare)String. Service Tag ID — identifică dispozitivul țintă pentru apelurile RESTful API. Transmiteți-l ca parametru de interogare URL către endpoint-ul din contul dumneavoastră API Monitor: POST https://<your-endpoint>?stgid=YOUR_TAG_ID.

Tipuri de șabloane

Datele biometrice și de identificare sunt transportate într-o matrice Template. Fiecare element are un câmp Type:

Comportamentul de îmbinare a șabloanelor — important pentru handler-ele de callback
Când datele utilizatorului sunt trimise de pe dispozitiv (operațiunile Callback #3–#9), șabloanele pot sosi pe rând sau în grupuri, prin mai multe callback-uri. Fiecare callback nu conține setul complet de șabloane al utilizatorului — transportă doar șabloanele adăugate sau modificate.

Serverul dumneavoastră trebuie să îmbine șabloanele primite cu șabloanele deja stocate pentru acel utilizator. Cheia unică a fiecărui șablon este Type + Index. De exemplu:
• Callback 1 sosește cu Fingerprint Index 0 → stocați-l
• Callback 2 sosește cu Face Index 0 + Card → îmbinați, nu suprascrieți amprenta
• Callback 3 sosește cu Fingerprint Index 0 (date noi) → actualizați amprenta existentă de la Index 0
Nu înlocuiți niciodată toate șabloanele la un callback — faceți întotdeauna upsert după Type + Index.

Tip	Descriere	Câmpuri suplimentare cheie
`Card`	Număr de card RFID / de proximitate	`Data` (șir cu numărul cardului)
`Password`	PIN numeric	`Data` (șir cu PIN-ul)
`Fingerprint`	Șablon de amprentă — binar codificat Base64	`Index` (indexul degetului 0–9), `Size`, `Data`
`Face`	Șablon facial — JPEG sau binar codificat Base64	`Index`, `Size`, `Data`
`Palm`	Șablon al venelor palmei — binar codificat Base64	`Index`, `Data`
`UserPhoto`	Fotografia de profil a utilizatorului — JPEG codificat Base64	`Data`

Referință API

Coduri de stare ale răspunsului

Răspunsurile RESTful API includ un StatusCode numeric. Răspunsurile Callback API folosesc întotdeauna forma simplă {"status":"done"}, indiferent de rezultat.

Cod	Stare	Descriere
`0`	Succes	Operațiunea s-a finalizat cu succes.
`1`	Date de cerere nevalide	Corpul JSON este malformat sau conține valori nevalide.
`2`	Service Tag ID nevalid	Parametrul de interogare `stgid` nu corespunde niciunui dispozitiv înregistrat.
`3`	Cerere nevalidă	Structura cererii nu corespunde formatului așteptat al operațiunii.
`4`	Criptare nevalidă	Payload-ul criptat (AES-256) nu a putut fi decriptat. Verificați cheia de criptare.
`5`	Dispozitiv offline	Dispozitivul țintă nu este conectat în prezent la Biometric Gateway.
`6`	Expirarea operațiunii	Dispozitivul nu a confirmat comanda în intervalul de timp permis.
`7`	Auth Token nevalid	`AuthToken` din cerere nu corespunde token-ului configurat pentru dispozitiv.
`8`	Utilizatorul există deja	A fost încercată o operațiune Add pentru un UserID care există deja pe dispozitiv.
`9`	Utilizator negăsit	UserID-ul specificat nu există pe dispozitiv.
`10`	Eroare de șablon	Datele șablonului biometric sunt corupte sau au un format neacceptat.
`11`	Memoria dispozitivului este plină	Dispozitivul a atins capacitatea maximă de utilizatori sau de șabloane.
`13`	Cheie de securitate nevalidă	Cheia de securitate configurată în API Monitor nu corespunde.
`15`	Funcție neacceptată	Operațiunea solicitată nu este acceptată de acest model de dispozitiv sau de acest mod de comunicare.
`999`	Eroare necunoscută	A apărut o eroare neașteptată. Contactați suportul Cams, indicând OperationID.

Informații suplimentare

Porturi acceptate

Pentru a primi informații de pontaj în timp real, serverul dumneavoastră trebuie să expună un endpoint HTTP(S) care poate fi accesat de Cams Protocol Engine.

Port	Protocol	Utilizare
`80`	HTTP	Producție. Asociați callback URL-ul dumneavoastră cu portul 80. Se configurează în API Monitor și este apelat automat la pontări.
`443`	HTTPS	Producție (securizat). HTTPS cu certificat SSL valid. Recomandat pentru producție.
`8123`	HTTP	Doar pentru testare. Port nestandard disponibil temporar în timpul dezvoltării.

HTTPS recomandat. Folosiți HTTPS cu un certificat SSL valid în producție. Asigurați reînnoirea automată fără repornirea serverului.

Informații suplimentare

Date de exemplu

Exemple de payload-uri de cerere și răspuns pentru toate cele 38 de operațiuni sunt documentate mai sus, în secțiunea fiecărei operațiuni. Pentru o vedere consolidată:

Această paginăFiecare secțiune de operațiune de mai sus include JSON de cerere și răspuns gata de copiat, cu date de exemplu.

Pagină de exemple vechebiometric-web-api-sample-request-response.html — selector derulant pentru fiecare operațiune.

Informații suplimentare

Criptare

Criptarea AES-256 opțională poate fi activată pentru toate datele schimbate între Cams Protocol Engine și serverul dumneavoastră.

AlgoritmAES-256 în modul ECB cu padding PKCS5 (AES/ECB/PKCS5PADDING).

Configurarea cheiiSetați cheia ca Security Key în API Monitor. Odată configurată, toate payload-urile JSON brute sunt criptate.

CodificarePayload-urile criptate sunt codificate Base64 pentru transport HTTP sigur.

Exemplu Java

Criptare / decriptare (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");

Important: Când criptarea este activată, decriptați payload-urile Callback primite și criptați corpurile cererilor RESTful trimise folosind aceeași cheie.