مرجع API: البنية والحقول ورموز الحالة
اللبنات المشتركة بين جميع العمليات: تدفق الطلبات، وحقول JSON المشتركة، وأنواع القوالب، ورموز الحالة، والمنافذ، وتشفير البيانات.
إجابات سريعة
ما هما مساران واجهة API؟
تقوم واجهة Callback بإرسال الأحداث من الجهاز (عبر Cams Biometric Gateway) إلى خادمك في الوقت الفعلي. أما واجهة RESTful فتتيح لخادمك إرسال أوامر إلى الجهاز، وتصل الاستجابة خلال نحو 15 ثانية. إذا كان خادمك غير متصل، يخزّن المحرك استدعاءات callback مؤقتًا؛ وتُوضع أوامر REST في قائمة انتظار حتى يعيد الجهاز الاتصال.
ما رموز الحالة التي تعيدها واجهة RESTful؟
قيمة رقمية StatusCode: 0 نجاح، 1 بيانات الطلب غير صالحة، 2 Service Tag ID غير صالح، 3 طلب غير صالح، 4 تشفير غير صالح، 5 الجهاز غير متصل، 6 انتهاء مهلة العملية، 7 رمز المصادقة غير صالح، 8 المستخدم موجود بالفعل، 9 المستخدم غير موجود، 10 خطأ في القالب، 11 ذاكرة الجهاز ممتلئة، 13 مفتاح الأمان غير صالح، 15 الميزة غير مدعومة، 999 خطأ غير معروف. تستخدم استجابات callback دائمًا {"status":"done"}.
ماذا يعني رمز الحالة 5 (الجهاز غير متصل)؟
الجهاز المستهدف غير متصل حاليًا بـ Biometric Gateway. راجع رمز الحالة 5.
كيف أصادق على الطلبات؟
يحمل كل طلب AuthToken، وهو رمز من 32 حرفًا يحدد جهازًا واحدًا ويتم ضبطه في بوابة API Monitor. تحقق منه في كل callback وارد. كما تمرّر استدعاءات REST الجهاز عبر معامل الاستعلام stgid (Service Tag ID). راجع الحقول المشتركة.
ما المنافذ التي يحتاجها خادمي؟
المنفذ 80 (HTTP) أو 443 (HTTPS) للإنتاج؛ ويوصى باستخدام HTTPS مع شهادة صالحة. المنفذ 8123 (HTTP) للاختبار فقط. راجع المنافذ المدعومة.
كيف يتم تشفير البيانات المرسلة؟
التشفير اختياري. عند تفعيله، تستخدم البيانات AES-256 بوضع ECB مع حشو PKCS5 (AES/ECB/PKCS5PADDING)، باستخدام مفتاح الأمان المحدد في API Monitor، وتُرمَّز بصيغة Base64 للنقل عبر HTTP. فكّ تشفير callback الواردة وشفّر محتوى طلبات REST الصادرة بالمفتاح نفسه. راجع التشفير.
كيف أتعامل مع القوالب التي تصل عبر عدة callback؟
ادمجها. يحمل كل callback القوالب التي أُضيفت أو تغيّرت فقط. المفتاح الفريد للقالب هو Type + Index، لذا نفّذ upsert وفق هذا الزوج ولا تستبدل أبدًا مجموعة قوالب المستخدم بالكامل. راجع أنواع القوالب.
ما أنواع القوالب الموجودة؟
Card وPassword وFingerprint وFace وPalm وUserPhoto. قوالب Fingerprint وFace وPalm مرمّزة بصيغة Base64، ويمتد فهرس البصمة من 0–9.
بنية API
| الخاصية | واجهة Callback | واجهة RESTful |
|---|---|---|
| المبادر | الجهاز / Biometric Gateway | خادمك |
| الاتجاه | من الجهاز إلى خادمك | من خادمك إلى الجهاز |
| زمن الاستجابة | لحظي (بالميلي ثانية) | ~15 ثانية |
| المُحفِّز | حدث بيومتري على الجهاز | طلب HTTP POST من الكود الخاص بك |
| دورك | الاستقبال والتأكيد | إرسال الأمر وانتظار/استطلاع الاستجابة |
| جسم الاستجابة | {"status":"done"} | {"Status":"done","OperationID":"…","StatusCode":0} |
| السلوك عند انقطاع الاتصال | يخزّنها المحرك مؤقتًا وتُسلَّم عند عودة الخادم للعمل | يضعها المحرك في طابور وتُسلَّم عند إعادة اتصال الجهاز |
الحقول المشتركة
تشترك جميع الطلبات — Callback وRESTful — في هذه الحقول ذات المستوى الأعلى.
"j95xfejt3vr1"). تعيد استجابات RESTful قيمة OperationID نفسها لتتمكن من مطابقة الطلبات مع الاستجابات.YYYY-MM-DD HH:mm:ss GMT +0000. قد تستخدم الطوابع الزمنية المحلية للجهاز داخل البيانات فارق توقيت مختلفًا.POST https://<your-endpoint>?stgid=YOUR_TAG_ID.أنواع القوالب
تُنقل البيانات البيومترية وبيانات الاعتماد ضمن مصفوفة Template. لكل عنصر حقل Type:
عند دفع بيانات المستخدم من الجهاز (عمليات Callback رقم 3–9)، قد تصل القوالب واحدًا تلو الآخر أو في مجموعات عبر عدة استدعاءات. لا يحتوي كل استدعاء على المجموعة الكاملة لقوالب المستخدم — بل القوالب التي أُضيفت أو تغيّرت فقط.
يجب أن يدمج خادمك القوالب الواردة مع القوالب المخزّنة لذلك المستخدم. المفتاح الفريد لكل قالب هو
Type + Index. على سبيل المثال:• يصل الاستدعاء 1 مع
Fingerprint Index 0 → خزّنه• يصل الاستدعاء 2 مع
Face Index 0 + Card → ادمج، ولا تستبدل البصمة• يصل الاستدعاء 3 مع
Fingerprint Index 0 (بيانات جديدة) → حدّث البصمة الموجودة عند Index 0لا تستبدل جميع القوالب عند أي Callback — نفّذ دائمًا upsert حسب
Type + Index.
| النوع | الوصف | أهم الحقول الإضافية |
|---|---|---|
Card | رقم بطاقة RFID / القرب | Data (سلسلة رقم البطاقة) |
Password | رمز PIN رقمي | Data (سلسلة PIN) |
Fingerprint | قالب البصمة — بيانات ثنائية مرمّزة بـ Base64 | Index (رقم الإصبع 0–9)، Size، Data |
Face | قالب الوجه — JPEG أو بيانات ثنائية مرمّزة بـ Base64 | Index, Size, Data |
Palm | قالب وريد راحة اليد — بيانات ثنائية مرمّزة بـ Base64 | Index, Data |
UserPhoto | صورة الملف الشخصي للمستخدم — JPEG مرمّز بـ Base64 | Data |
رموز حالة الاستجابة
تتضمن استجابات RESTful قيمة رقمية StatusCode. تستخدم استجابات Callback دائمًا الصيغة البسيطة {"status":"done"} أيًا كانت النتيجة.
| الرمز | الحالة | الوصف |
|---|---|---|
0 | نجاح | اكتملت العملية بنجاح. |
1 | بيانات الطلب غير صالحة | جسم JSON مشوّه أو يحتوي على قيم غير صالحة. |
2 | Service Tag ID غير صالح | لا يطابق معامل الاستعلام stgid أي جهاز مسجّل. |
3 | طلب غير صالح | بنية الطلب لا تطابق صيغة العملية المتوقعة. |
4 | تشفير غير صالح | تعذّر فك تشفير البيانات (AES-256). تحقق من مفتاح التشفير لديك. |
5 | الجهاز غير متصل | الجهاز المستهدف غير متصل حاليًا بـ Biometric Gateway. |
6 | انتهاء مهلة العملية | لم يؤكد الجهاز استلام الأمر خلال مهلة الانتظار. |
7 | رمز مصادقة غير صالح | لا يطابق AuthToken في الطلب الرمزَ المضبوط للجهاز. |
8 | المستخدم موجود مسبقًا | جرت محاولة عملية إضافة لـ UserID موجود بالفعل على الجهاز. |
9 | المستخدم غير موجود | UserID المحدد غير موجود على الجهاز. |
10 | خطأ في القالب | بيانات القالب البيومتري تالفة أو بصيغة غير مدعومة. |
11 | ذاكرة الجهاز ممتلئة | بلغ الجهاز الحد الأقصى لسعته من المستخدمين أو القوالب. |
13 | مفتاح أمان غير صالح | مفتاح الأمان المضبوط في API Monitor لا يتطابق. |
15 | الميزة غير مدعومة | العملية المطلوبة غير مدعومة في طراز هذا الجهاز أو وضع الاتصال. |
999 | خطأ غير معروف | حدث خطأ غير متوقع. تواصل مع دعم Cams مع ذكر OperationID. |
المنافذ المدعومة
لاستقبال معلومات الحضور لحظيًا، يجب أن يوفّر خادمك نقطة HTTP(S) يمكن لـ Cams Protocol Engine الوصول إليها.
| المنفذ | البروتوكول | الاستخدام |
|---|---|---|
80 | HTTP | الإنتاج. اربط Callback URL بالمنفذ 80. يُضبط في API Monitor ويُستدعى تلقائيًا عند كل بصمة. |
443 | HTTPS | الإنتاج (آمن). HTTPS مع شهادة SSL صالحة. موصى به للإنتاج. |
8123 | HTTP | للاختبار فقط. منفذ غير قياسي متاح مؤقتًا أثناء التطوير. |
بيانات نموذجية
نماذج طلبات واستجابات جميع العمليات الـ38 موثّقة أعلاه في قسم كل عملية. لعرض موحّد:
التشفير
يمكن تفعيل تشفير AES-256 الاختياري لجميع البيانات المتبادلة بين Cams Protocol Engine وخادمك.
AES/ECB/PKCS5PADDING).مثال 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");