API रेफ़रेंस: आर्किटेक्चर, फ़ील्ड और स्टेटस कोड

हर ऑपरेशन में साझा बुनियादी तत्व: रिक्वेस्ट फ़्लो, सामान्य JSON फ़ील्ड, टेम्पलेट प्रकार, स्टेटस कोड, पोर्ट और पेलोड एन्क्रिप्शन।

API रेफ़रेंस

API आर्किटेक्चर

प्रॉपर्टी	Callback API	RESTful API
आरंभकर्ता	डिवाइस / Biometric Gateway	आपका सर्वर
दिशा	डिवाइस → आपका सर्वर	आपका सर्वर → डिवाइस
लेटेंसी	रियल-टाइम (मिलीसेकंड)	~15 सेकंड
ट्रिगर	डिवाइस पर बायोमेट्रिक इवेंट	आपके कोड से HTTP POST
आपकी भूमिका	प्राप्त करें और पुष्टि करें	कमांड भेजें और रिस्पॉन्स की प्रतीक्षा/पोलिंग करें
रिस्पॉन्स बॉडी	`{"status":"done"}`	`{"Status":"done","OperationID":"…","StatusCode":0}`
ऑफ़लाइन व्यवहार	इंजन द्वारा कैश किया जाता है; सर्वर के ऑनलाइन होने पर डिलीवर होता है	इंजन द्वारा कतार में रखा जाता है; डिवाइस के दोबारा कनेक्ट होने पर डिलीवर होता है

API रेफ़रेंस

सामान्य फ़ील्ड

सभी रिक्वेस्ट — Callback और RESTful दोनों — ये टॉप-लेवल फ़ील्ड साझा करते हैं।

AuthTokenString. 32 अक्षरों का टोकन, जो किसी विशिष्ट डिवाइस के अनुरोधों की पहचान और ऑथेंटिकेशन करता है। API Monitor पोर्टल में कॉन्फ़िगर किया जाता है। हर इनबाउंड callback पर इसे सत्यापित करें।

OperationIDString. इस ऑपरेशन इंस्टेंस का अद्वितीय पहचानकर्ता (जैसे "j95xfejt3vr1")। RESTful रिस्पॉन्स वही OperationID लौटाते हैं ताकि आप रिक्वेस्ट और रिस्पॉन्स का मिलान कर सकें।

TimeString. इवेंट प्रोसेस होने का UTC टाइमस्टैम्प, फ़ॉर्मेट YYYY-MM-DD HH:mm:ss GMT +0000 में। पेलोड के भीतर डिवाइस के स्थानीय टाइमस्टैम्प में भिन्न टाइमज़ोन ऑफ़सेट हो सकता है।

stgid (क्वेरी पैरामीटर)String. Service Tag ID — RESTful API कॉल के लिए लक्षित डिवाइस की पहचान करता है। इसे अपने API Monitor खाते में उपलब्ध एंडपॉइंट पर URL क्वेरी पैरामीटर के रूप में दें: POST https://<your-endpoint>?stgid=YOUR_TAG_ID।

टेम्पलेट प्रकार

बायोमेट्रिक और क्रेडेंशियल डेटा Template ऐरे में होता है। हर आइटम में एक Type फ़ील्ड होती है:

टेम्पलेट मर्ज व्यवहार — Callback हैंडलर के लिए महत्वपूर्ण
जब यूज़र डेटा डिवाइस से पुश होता है (Callback ऑपरेशन #3–#9), तो टेम्पलेट कई callback में एक-एक करके या समूहों में आ सकते हैं। हर callback में यूज़र का पूरा टेम्पलेट सेट नहीं होता — उसमें केवल जोड़े या बदले गए टेम्पलेट होते हैं।

आपके सर्वर को आने वाले टेम्पलेट को उस यूज़र के संग्रहीत टेम्पलेट के साथ मर्ज करना होगा। हर टेम्पलेट की अद्वितीय कुंजी Type + Index है। उदाहरण:
• Callback 1 में Fingerprint Index 0 आता है → उसे संग्रहीत करें
• Callback 2 में Face Index 0 + Card आते हैं → मर्ज करें, फ़िंगरप्रिंट को ओवरराइट न करें
• Callback 3 में Fingerprint Index 0 (नया डेटा) आता है → Index 0 का मौजूदा फ़िंगरप्रिंट अपडेट करें
किसी callback पर सभी टेम्पलेट कभी न बदलें — हमेशा Type + Index के आधार पर upsert करें।

Type	विवरण	प्रमुख अतिरिक्त फ़ील्ड
`Card`	RFID / प्रॉक्सिमिटी कार्ड नंबर	`Data` (कार्ड नंबर स्ट्रिंग)
`Password`	न्यूमेरिक PIN	`Data` (PIN स्ट्रिंग)
`Fingerprint`	फ़िंगरप्रिंट टेम्पलेट — Base64 एन्कोडेड बाइनरी	`Index` (उँगली का इंडेक्स 0–9), `Size`, `Data`
`Face`	फ़ेस टेम्पलेट — Base64 एन्कोडेड JPEG या बाइनरी	`Index`, `Size`, `Data`
`Palm`	पाम वेन टेम्पलेट — Base64 एन्कोडेड बाइनरी	`Index`, `Data`
`UserPhoto`	यूज़र प्रोफ़ाइल फ़ोटो — Base64 एन्कोडेड JPEG	`Data`

API रेफ़रेंस

रिस्पॉन्स स्टेटस कोड

RESTful API रिस्पॉन्स में एक संख्यात्मक StatusCode होता है। परिणाम चाहे जो हो, Callback API रिस्पॉन्स हमेशा सरल {"status":"done"} रूप में होते हैं।

कोड	स्टेटस	विवरण
`0`	सफल	ऑपरेशन सफलतापूर्वक पूरा हुआ।
`1`	अमान्य रिक्वेस्ट डेटा	JSON बॉडी गलत फ़ॉर्मेट में है या उसमें अमान्य मान हैं।
`2`	अमान्य Service Tag ID	`stgid` क्वेरी पैरामीटर किसी पंजीकृत डिवाइस से मेल नहीं खाता।
`3`	अमान्य रिक्वेस्ट	रिक्वेस्ट की संरचना अपेक्षित ऑपरेशन फ़ॉर्मेट से मेल नहीं खाती।
`4`	अमान्य एन्क्रिप्शन	पेलोड एन्क्रिप्शन (AES-256) को डिक्रिप्ट नहीं किया जा सका। अपनी एन्क्रिप्शन कुंजी जाँचें।
`5`	डिवाइस ऑफ़लाइन	लक्षित डिवाइस वर्तमान में Biometric Gateway से कनेक्ट नहीं है।
`6`	ऑपरेशन टाइमआउट	डिवाइस ने टाइमआउट अवधि के भीतर कमांड की पुष्टि नहीं की।
`7`	अमान्य Auth Token	रिक्वेस्ट में दिया `AuthToken` डिवाइस के कॉन्फ़िगर किए टोकन से मेल नहीं खाता।
`8`	यूज़र पहले से मौजूद है	ऐसे UserID के लिए Add ऑपरेशन किया गया जो डिवाइस पर पहले से मौजूद है।
`9`	यूज़र नहीं मिला	बताया गया UserID डिवाइस पर मौजूद नहीं है।
`10`	टेम्पलेट त्रुटि	बायोमेट्रिक टेम्पलेट डेटा दूषित है या असमर्थित फ़ॉर्मेट में है।
`11`	डिवाइस मेमोरी भरी हुई	डिवाइस अपनी अधिकतम यूज़र या टेम्पलेट क्षमता तक पहुँच गया है।
`13`	अमान्य सिक्योरिटी की	API Monitor में कॉन्फ़िगर की गई सिक्योरिटी की मेल नहीं खाती।
`15`	सुविधा समर्थित नहीं	अनुरोधित ऑपरेशन इस डिवाइस मॉडल या संचार मोड द्वारा समर्थित नहीं है।
`999`	अज्ञात त्रुटि	कोई अप्रत्याशित त्रुटि हुई। OperationID के साथ Cams सपोर्ट से संपर्क करें।

अतिरिक्त जानकारी

समर्थित पोर्ट

रियल-टाइम अटेंडेंस जानकारी प्राप्त करने के लिए आपके सर्वर को एक HTTP(S) एंडपॉइंट उपलब्ध कराना होगा, जिस तक Cams Protocol Engine पहुँच सके।

पोर्ट	प्रोटोकॉल	उपयोग
`80`	HTTP	प्रोडक्शन। अपने callback URL को पोर्ट 80 से बाँधें। API Monitor में कॉन्फ़िगर किया जाता है और पंच होने पर अपने-आप कॉल होता है।
`443`	HTTPS	प्रोडक्शन (सुरक्षित)। मान्य SSL सर्टिफ़िकेट के साथ HTTPS। प्रोडक्शन के लिए अनुशंसित।
`8123`	HTTP	केवल टेस्टिंग के लिए। गैर-मानक पोर्ट, जो डेवलपमेंट के दौरान अस्थायी रूप से उपलब्ध है।

HTTPS अनुशंसित। प्रोडक्शन के लिए मान्य SSL सर्टिफ़िकेट के साथ HTTPS का उपयोग करें। सुनिश्चित करें कि सर्वर रीस्टार्ट के बिना ऑटो-रिन्यूअल हो।

अतिरिक्त जानकारी

सैंपल डेटा

सभी 38 ऑपरेशन के सैंपल रिक्वेस्ट और रिस्पॉन्स पेलोड ऊपर हर ऑपरेशन सेक्शन में दिए गए हैं। एकीकृत दृश्य के लिए:

यह पेजऊपर का हर ऑपरेशन सेक्शन सैंपल डेटा के साथ कॉपी-करने योग्य रिक्वेस्ट और रिस्पॉन्स JSON देता है।

पुराना सैंपल पेजbiometric-web-api-sample-request-response.html — हर ऑपरेशन के लिए ड्रॉपडाउन चयनकर्ता।

अतिरिक्त जानकारी

एन्क्रिप्शन

Cams Protocol Engine और आपके सर्वर के बीच आदान-प्रदान होने वाले सभी डेटा के लिए वैकल्पिक AES-256 एन्क्रिप्शन सक्षम किया जा सकता है।

एल्गोरिदमPKCS5 पैडिंग के साथ ECB मोड में AES-256 (AES/ECB/PKCS5PADDING)।

की कॉन्फ़िगरेशनअपनी कुंजी को API Monitor में Security Key के रूप में सेट करें। कॉन्फ़िगर होने पर सभी रॉ JSON पेलोड एन्क्रिप्ट हो जाते हैं।

एन्कोडिंगएन्क्रिप्टेड पेलोड सुरक्षित HTTP ट्रांसपोर्ट के लिए Base64-एन्कोडेड होते हैं।

Java उदाहरण

एन्क्रिप्ट / डिक्रिप्ट (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");

महत्वपूर्ण: एन्क्रिप्शन सक्षम होने पर, इनबाउंड Callback पेलोड को डिक्रिप्ट करें और आउटबाउंड RESTful रिक्वेस्ट बॉडी को उसी कुंजी से एन्क्रिप्ट करें।