Întrebări frecvente, SDK și costuri
Întrebări frecvente ale integratorilor, plus modul în care funcționează SDK-ul și prețurile API.
Informații suplimentare
Întrebări frecvente
Întrebări frecvente despre integrarea cu Cams Biometrics Web API 3.0.
General
Î: Ce este Cams Biometric Gateway și Biometric API-ul său?
Cams Biometric Gateway este o platformă cloud universală care expune un Biometric API ce permite oricărei aplicații web să comunice în timp real cu dispozitivele biometrice de pontaj și de control al accesului. Acceptă 38 de operațiuni, prin Callback API (de intrare) și RESTful API (de ieșire) — fără a necesita vreun SDK de dispozitiv sau IP static.
Cams Biometric Gateway este o platformă cloud universală care expune un Biometric API ce permite oricărei aplicații web să comunice în timp real cu dispozitivele biometrice de pontaj și de control al accesului. Acceptă 38 de operațiuni, prin Callback API (de intrare) și RESTful API (de ieșire) — fără a necesita vreun SDK de dispozitiv sau IP static.
Î: Am nevoie de un SDK pentru integrare?
Nu. Cams nu oferă și nu necesită un SDK. Toată comunicarea folosește cereri HTTP/HTTPS POST standard cu payload-uri JSON. Funcționează orice limbaj care poate efectua apeluri HTTP.
Nu. Cams nu oferă și nu necesită un SDK. Toată comunicarea folosește cereri HTTP/HTTPS POST standard cu payload-uri JSON. Funcționează orice limbaj care poate efectua apeluri HTTP.
Î: Ce limbaje de programare sunt acceptate?
Orice limbaj care poate trimite/primi HTTP POST cu JSON — PHP, Python, Java, C#, Node.js, Go, Ruby și altele. Oferim prompturi pentru generatoare de cod AI pentru 7 limbaje.
Orice limbaj care poate trimite/primi HTTP POST cu JSON — PHP, Python, Java, C#, Node.js, Go, Ruby și altele. Oferim prompturi pentru generatoare de cod AI pentru 7 limbaje.
Î: Ce este Cams Protocol Engine?
Este middleware-ul cloud aflat între dispozitivele biometrice și serverul dumneavoastră. Se ocupă de translarea protocoalelor, normalizarea datelor și cache-ul offline și oferă un API JSON consecvent, indiferent de marca sau modelul dispozitivului.
Este middleware-ul cloud aflat între dispozitivele biometrice și serverul dumneavoastră. Se ocupă de translarea protocoalelor, normalizarea datelor și cache-ul offline și oferă un API JSON consecvent, indiferent de marca sau modelul dispozitivului.
Î: Ce este API Monitor?
API Monitor este portalul dumneavoastră de administrare, în care configurați Callback URL-urile, gestionați AuthToken-urile, setați Security Key, vedeți starea dispozitivelor și accesați URL-ul endpoint-ului RESTful și Service Tag ID-urile.
API Monitor este portalul dumneavoastră de administrare, în care configurați Callback URL-urile, gestionați AuthToken-urile, setați Security Key, vedeți starea dispozitivelor și accesați URL-ul endpoint-ului RESTful și Service Tag ID-urile.
Compatibilitatea dispozitivelor
Î: Ce dispozitive biometrice sunt acceptate?
Toate dispozitivele Cams Biometrics (listate pe camsbiometrics.com/product) acceptă API-ul complet cu Native Push. Dispozitivele verificate pe developer.camsbiometrics.com au, de asemenea, suport complet Native Push.
Toate dispozitivele Cams Biometrics (listate pe camsbiometrics.com/product) acceptă API-ul complet cu Native Push. Dispozitivele verificate pe developer.camsbiometrics.com au, de asemenea, suport complet Native Push.
Î: Pot dispozitivele non-Cams (ZkTeco, eSSL, BioMax etc.) să folosească acest API?
Da, cu un Protocol Update. Dispozitivele non-Cams și neverificate funcționează prin Hybrid Push. Unele funcții pot fi limitate în funcție de modul de conectare și de capacitățile hardware.
Da, cu un Protocol Update. Dispozitivele non-Cams și neverificate funcționează prin Hybrid Push. Unele funcții pot fi limitate în funcție de modul de conectare și de capacitățile hardware.
Î: Care este diferența dintre Native Push și Hybrid Push?
Native Push: suport API complet, fără limitări — toate cele 38 de operațiuni funcționează. Disponibil pentru dispozitivele Cams și cele verificate.
Hybrid Push: pentru dispozitive non-Cams/neverificate. Disponibilitatea funcțiilor depinde de modul de comunicare (SDK, DB Pull sau procesarea fișierelor). Vezi Moduri de conectare.
Native Push: suport API complet, fără limitări — toate cele 38 de operațiuni funcționează. Disponibil pentru dispozitivele Cams și cele verificate.
Hybrid Push: pentru dispozitive non-Cams/neverificate. Disponibilitatea funcțiilor depinde de modul de comunicare (SDK, DB Pull sau procesarea fișierelor). Vezi Moduri de conectare.
Î: Ce metode biometrice sunt acceptate?
Amprentă, recunoaștere facială, venele palmei, card RFID/de proximitate, PIN/parolă numerică, scanarea irisului și măsurarea temperaturii corporale (în funcție de dispozitiv).
Amprentă, recunoaștere facială, venele palmei, card RFID/de proximitate, PIN/parolă numerică, scanarea irisului și măsurarea temperaturii corporale (în funcție de dispozitiv).
Î: Unele funcții API nu funcționează cu dispozitivul meu. De ce?
Depinde de (a) modul de conectare — modurile DB Pull și Procesarea fișierelor acceptă doar trimiterea pontajului, nu și RESTful API, și (b) limitările hardware — unele modele de dispozitive pot să nu accepte anumite funcții la nivel de firmware. Testați cu echipamentul dumneavoastră și contactați suportul Cams pentru asistență.
Depinde de (a) modul de conectare — modurile DB Pull și Procesarea fișierelor acceptă doar trimiterea pontajului, nu și RESTful API, și (b) limitările hardware — unele modele de dispozitive pot să nu accepte anumite funcții la nivel de firmware. Testați cu echipamentul dumneavoastră și contactați suportul Cams pentru asistență.
Callback API (dispozitiv → server)
Î: Ce este Callback API?
Callback API livrează evenimente în timp real de la dispozitivele biometrice către serverul dumneavoastră. Când are loc o pontare sau un utilizator este modificat pe dispozitiv, Cams Protocol Engine trimite imediat prin POST un payload JSON către Callback URL-ul configurat.
Callback API livrează evenimente în timp real de la dispozitivele biometrice către serverul dumneavoastră. Când are loc o pontare sau un utilizator este modificat pe dispozitiv, Cams Protocol Engine trimite imediat prin POST un payload JSON către Callback URL-ul configurat.
Î: Cu ce trebuie să răspundă serverul meu?
Returnați întotdeauna
Returnați întotdeauna
{"status":"done"} cu starea HTTP 200 — chiar dacă procesarea dumneavoastră internă eșuează. Nu blocați niciodată Cams Protocol Engine. Puneți procesările grele în coadă pentru execuție asincronă.Î: Ce se întâmplă dacă serverul meu este offline când are loc o pontare?
Biometric Gateway păstrează în cache toate evenimentele și le livrează automat imediat ce serverul dumneavoastră revine online. Nu se pierd date.
Biometric Gateway păstrează în cache toate evenimentele și le livrează automat imediat ce serverul dumneavoastră revine online. Nu se pierd date.
Î: Cum tratez pontările duplicate?
Implementați pe serverul dumneavoastră o logică de detectare a duplicatelor, folosind combinația
Implementați pe serverul dumneavoastră o logică de detectare a duplicatelor, folosind combinația
UserID + LogTime. Aceeași pontare poate fi retrimisă în timpul recuperării după o perioadă offline sau la reîncercări de rețea.Î: Ce tipuri de pontare sunt acceptate?
CheckIn, CheckOut, BreakOut, BreakIn, OverTimeIn, OverTimeOut, MealIn, MealOut. Câmpul InputType indică metoda biometrică folosită: Fingerprint, Face, Palm, Card sau Password.Î: Cum funcționează șabloanele utilizatorilor în callback-uri?
Când un utilizator este actualizat pe dispozitiv (operațiunile #3–#9), șabloanele pot sosi pe rând sau în grupuri, prin mai multe callback-uri. Fiecare callback transportă doar șabloanele modificate — nu setul complet. Serverul dumneavoastră trebuie să îmbine/facă upsert folosind
Când un utilizator este actualizat pe dispozitiv (operațiunile #3–#9), șabloanele pot sosi pe rând sau în grupuri, prin mai multe callback-uri. Fiecare callback transportă doar șabloanele modificate — nu setul complet. Serverul dumneavoastră trebuie să îmbine/facă upsert folosind
Type + Index drept cheie unică. Nu suprascrieți niciodată toate șabloanele la un singur callback.Î: Pot primi fotografii de pontaj?
Da. Operațiunea #10 RealTimeAttendancePhoto livrează un instantaneu JPEG codificat Base64, capturat în momentul pontării. Este separată de callback-ul jurnalului de pontare (#11) și disponibilă pe dispozitivele cu cameră.
Da. Operațiunea #10 RealTimeAttendancePhoto livrează un instantaneu JPEG codificat Base64, capturat în momentul pontării. Este separată de callback-ul jurnalului de pontare (#11) și disponibilă pe dispozitivele cu cameră.
Î: Include Callback temperatura și detectarea măștii?
Da, dacă dispozitivul o acceptă. Obiectul
Da, dacă dispozitivul o acceptă. Obiectul
PunchLog include Temperature (citirea temperaturii corporale) și FaceMask (boolean — dacă a fost detectată o mască facială).RESTful API (server → dispozitiv)
Î: Ce este RESTful API?
RESTful API permite serverului dumneavoastră să trimită comenzi către dispozitivele biometrice — adăugare/ștergere utilizatori, încărcare jurnale, înrolare date biometrice și controlul accesului. Trimiteți JSON prin POST către URL-ul endpoint-ului din contul dumneavoastră API Monitor.
RESTful API permite serverului dumneavoastră să trimită comenzi către dispozitivele biometrice — adăugare/ștergere utilizatori, încărcare jurnale, înrolare date biometrice și controlul accesului. Trimiteți JSON prin POST către URL-ul endpoint-ului din contul dumneavoastră API Monitor.
Î: Unde găsesc URL-ul endpoint-ului meu RESTful?
Autentificați-vă în contul API Monitor. URL-ul endpoint-ului RESTful și Service Tag ID-urile (
Autentificați-vă în contul API Monitor. URL-ul endpoint-ului RESTful și Service Tag ID-urile (
stgid) sunt listate acolo.Î: Care este latența comenzilor RESTful?
Aproximativ 15 secunde. Biometric Gateway pune comanda în coadă și o livrează dispozitivului la următoarea conectare a acestuia (aproape continuă pentru dispozitivele online).
Aproximativ 15 secunde. Biometric Gateway pune comanda în coadă și o livrează dispozitivului la următoarea conectare a acestuia (aproape continuă pentru dispozitivele online).
Î: Care este intervalul maxim de date pentru LoadLog?
Maximul recomandat este de 30 de zile per cerere. Pentru intervale mai mari, efectuați mai multe cereri cu ferestre de timp consecutive.
Maximul recomandat este de 30 de zile per cerere. Pentru intervale mai mari, efectuați mai multe cereri cu ferestre de timp consecutive.
Î: Pot adăuga un utilizator cu mai multe șabloane biometrice deodată?
Da. Matricea Template acceptă mai multe intrări. De exemplu, operațiunea #27 adaugă un utilizator cu Card + amprentă + parolă + față + palmă + UserPhoto, toate într-o singură cerere.
Da. Matricea Template acceptă mai multe intrări. De exemplu, operațiunea #27 adaugă un utilizator cu Card + amprentă + parolă + față + palmă + UserPhoto, toate într-o singură cerere.
Î: Ce se întâmplă dacă dispozitivul este offline când trimit o comandă RESTful?
Biometric Gateway pune comanda în coadă și o livrează automat când dispozitivul se reconectează. Veți primi codul de stare
Biometric Gateway pune comanda în coadă și o livrează automat când dispozitivul se reconectează. Veți primi codul de stare
5 (Device Offline) dacă dispozitivul nu răspunde în intervalul de timp permis.Î: Cum verific rezultatul comenzii?
Răspunsurile RESTful includ un câmp
Răspunsurile RESTful includ un câmp
StatusCode. Codul 0 înseamnă succes. Consultați Codurile de stare ale răspunsului pentru lista completă a codurilor de eroare și semnificațiile lor.Î: Pot declanșa de la distanță înrolarea amprentei?
Da. Operațiunea #35 EnrollFingerPrint declanșează o sesiune de înrolare pe dispozitiv. Totuși, utilizatorul trebuie să fie prezent fizic la dispozitiv pentru a-și scana degetul.
Da. Operațiunea #35 EnrollFingerPrint declanșează o sesiune de înrolare pe dispozitiv. Totuși, utilizatorul trebuie să fie prezent fizic la dispozitiv pentru a-și scana degetul.
Securitate & rețea
Î: Pot folosi HTTPS pentru callback-uri?
Da. HTTPS cu un certificat SSL valid pe portul 443 este pe deplin acceptat și recomandat pentru producție.
Da. HTTPS cu un certificat SSL valid pe portul 443 este pe deplin acceptat și recomandat pentru producție.
Î: Este criptarea obligatorie?
Nu. Criptarea AES-256 este opțională. Pentru a o activa, configurați un Security Key în API Monitor. Când este activată, toate payload-urile JSON sunt criptate/decriptate folosind AES/ECB/PKCS5PADDING cu codificare Base64.
Nu. Criptarea AES-256 este opțională. Pentru a o activa, configurați un Security Key în API Monitor. Când este activată, toate payload-urile JSON sunt criptate/decriptate folosind AES/ECB/PKCS5PADDING cu codificare Base64.
Î: Cum validez că un callback provine cu adevărat de la Cams?
Fiecare callback include un câmp
Fiecare callback include un câmp
AuthToken. Comparați-l cu token-ul configurat în API Monitor. Respingeți orice cerere cu un token necorespunzător.Î: Ce porturi ar trebui să deschid?
Portul
Portul
80 (HTTP) sau 443 (HTTPS) pentru producție. Portul 8123 este disponibil doar pentru testare. Vezi Porturi acceptate.Î: Cum testez local, fără implementare pe un server?
Folosiți un IP public cu redirecționare de porturi sau un instrument de tunelare precum ngrok. Vezi Testare locală pentru un ghid pas cu pas.
Folosiți un IP public cu redirecționare de porturi sau un instrument de tunelare precum ngrok. Vezi Testare locală pentru un ghid pas cu pas.
Date & considerații de proiectare
Î: Ce format de date folosește API-ul?
Toate cererile și răspunsurile sunt JSON brut cu codificare UTF-8. Folosiți antetul
Toate cererile și răspunsurile sunt JSON brut cu codificare UTF-8. Folosiți antetul
Content-Type: application/json. Fără codificare de formular.Î: Ce format de marcaj temporal este folosit?
YYYY-MM-DD HH:mm:ss GMT +OFFSET (de ex. 2020-09-17 07:48:22 GMT +0530). Câmpul Time este în UTC; marcajele temporale locale ale dispozitivului (precum LogTime, OperationTime) pot folosi un alt decalaj de fus orar.Î: Cum tratez pontările offline și datele retroactive?
Proiectați aplicația astfel încât să accepte pontări care sosesc în afara ordinii cronologice. Când un dispozitiv a fost offline, va trimite pontările din cache după reconectare. Poate fi necesar să actualizați retroactiv starea prezenței (de ex. să schimbați un utilizator afișat ca „absent” în „prezent”).
Proiectați aplicația astfel încât să accepte pontări care sosesc în afara ordinii cronologice. Când un dispozitiv a fost offline, va trimite pontările din cache după reconectare. Poate fi necesar să actualizați retroactiv starea prezenței (de ex. să schimbați un utilizator afișat ca „absent” în „prezent”).
Î: Cum determin INTRARE/IEȘIRE când un utilizator are mai multe dispozitive?
Sortați toate pontările unui utilizator după
Sortați toate pontările unui utilizator după
LogTime, de pe toate dispozitivele, apoi aplicați logica dumneavoastră de business. Nu vă bazați exclusiv pe câmpul Type (CheckIn/CheckOut) de la un singur dispozitiv dacă utilizatorul pontează pe dispozitive diferite.Î: Ce este OperationID și cum ar trebui să-l folosesc?
Un identificator unic de tip șir pentru fiecare operațiune. Pentru callback-urile primite, este generat de Biometric Gateway. Pentru cererile RESTful trimise, ar trebui să generați unul unic pentru fiecare cerere (UUID sau bazat pe marcaj temporal). Răspunsul îl returnează, astfel încât să puteți corela perechile cerere/răspuns.
Un identificator unic de tip șir pentru fiecare operațiune. Pentru callback-urile primite, este generat de Biometric Gateway. Pentru cererile RESTful trimise, ar trebui să generați unul unic pentru fiecare cerere (UUID sau bazat pe marcaj temporal). Răspunsul îl returnează, astfel încât să puteți corela perechile cerere/răspuns.
Î: Cum sunt stocate și transmise șabloanele biometrice?
Datele biometrice (amprentă, față, palmă, fotografia utilizatorului) sunt codificate Base64 în câmpul
Datele biometrice (amprentă, față, palmă, fotografia utilizatorului) sunt codificate Base64 în câmpul
Data al obiectului Template. Șabloanele de amprentă și facial includ și Size (lungimea în octeți) și Index (numărul locației). Numerele de card și PIN-urile sunt șiruri simple.Prețuri & licențiere
Î: Cum este licențiat API-ul?
Per dispozitiv biometric. Primul an necesită Activare API + Licență anuală. Anii următori necesită doar reînnoirea licenței anuale. Vezi Costul API pentru prețuri.
Per dispozitiv biometric. Primul an necesită Activare API + Licență anuală. Anii următori necesită doar reînnoirea licenței anuale. Vezi Costul API pentru prețuri.
Î: Ce se întâmplă dacă licența mea API expiră?
Comunicarea API pentru acel dispozitiv se oprește până la reînnoirea licenței. Datele dumneavoastră existente nu sunt afectate, dar nu vor mai fi procesate callback-uri sau comenzi RESTful noi.
Comunicarea API pentru acel dispozitiv se oprește până la reînnoirea licenței. Datele dumneavoastră existente nu sunt afectate, dar nu vor mai fi procesate callback-uri sau comenzi RESTful noi.
Î: Există o opțiune on-premise?
Da. Protocol Engine Lite poate fi instalat pe propriul server (Windows/Linux), pentru medii exclusiv LAN sau auto-găzduite. Contactați sales@camsbiometrics.com pentru detalii.
Da. Protocol Engine Lite poate fi instalat pe propriul server (Windows/Linux), pentru medii exclusiv LAN sau auto-găzduite. Contactați sales@camsbiometrics.com pentru detalii.
Informații suplimentare
SDK pentru pontaj biometric
Cams nu oferă un SDK tradițional. Toate operațiunile folosesc Callback API și RESTful API HTTP standard — nu este necesară instalarea niciunei biblioteci.
Nu este nevoie de SDK. Comunicarea se realizează integral prin Cams Protocol Engine, folosind Callback URL-uri și endpoint-uri RESTful HTTP.
Astfel, integrarea cu orice platformă web este simplă:
OpenERPERPNextZoho PeopleSAPTallyHRAPPOdooAplicații web personalizate
Informații suplimentare
Costul API
Licențele API se facturează per dispozitiv biometric. Primul an = activare + licență; anii următori = doar reînnoirea licenței.
| Serviciu | USD | Observații |
|---|---|---|
| Native Push — dispozitive Cams & verificate | ||
| Activare API | $120 | O singură dată per dispozitiv. |
| Licență API anuală | $60 – $120 | Reînnoire anuală necesară. |
| Protocol Update (non-Cams) | $120 – $280 | O singură dată. Activează protocolul Cams pe dispozitivele non-Cams. |
| Hybrid Push — ZKTeco, eSSL & toate mărcile terțe | ||
| Activare API | $150 | O singură dată per dispozitiv. |
| Licență API anuală | $90 – $150 | Reînnoire anuală necesară. |
| Hybrid Connector (neverificat) | $150 – $300 | O singură dată. Necesar pentru dispozitivele neverificate care folosesc Hybrid Push. |
| Hardware & altele | ||
| Hardware | $220 – $720 | Variază în funcție de model. |
Protocol Engine Lite (on-premise) — pentru medii exclusiv LAN sau auto-găzduite. Cost: $500–$10,000. Contactați departamentul de vânzări pentru detalii.