مرجع 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 — في هذه الحقول ذات المستوى الأعلى.

AuthTokenسلسلة نصية. رمز من 32 حرفًا يعرّف الطلبات الواردة من جهاز معيّن ويصادق عليها. يُضبط في بوابة API Monitor. تحقق منه في كل Callback وارد.
OperationIDسلسلة نصية. معرّف فريد لهذه العملية (مثل "j95xfejt3vr1"). تعيد استجابات RESTful قيمة OperationID نفسها لتتمكن من مطابقة الطلبات مع الاستجابات.
Timeسلسلة نصية. الطابع الزمني UTC لوقت معالجة الحدث، بصيغة YYYY-MM-DD HH:mm:ss GMT +0000. قد تستخدم الطوابع الزمنية المحلية للجهاز داخل البيانات فارق توقيت مختلفًا.
stgid (معامل استعلام)سلسلة نصية. Service Tag ID — يحدد الجهاز المستهدف في استدعاءات RESTful. مرّره كمعامل استعلام في عنوان URL إلى النقطة الموجودة في حساب API Monitor: POST https://<your-endpoint>?stgid=YOUR_TAG_ID.

أنواع القوالب

تُنقل البيانات البيومترية وبيانات الاعتماد ضمن مصفوفة Template. لكل عنصر حقل Type:

سلوك دمج القوالب — مهم لمعالجات Callback
عند دفع بيانات المستخدم من الجهاز (عمليات 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قالب البصمة — بيانات ثنائية مرمّزة بـ Base64Index (رقم الإصبع 0–9)، Size، Data
Faceقالب الوجه — JPEG أو بيانات ثنائية مرمّزة بـ Base64Index, Size, Data
Palmقالب وريد راحة اليد — بيانات ثنائية مرمّزة بـ Base64Index, Data
UserPhotoصورة الملف الشخصي للمستخدم — JPEG مرمّز بـ Base64Data

رموز حالة الاستجابة

تتضمن استجابات RESTful قيمة رقمية StatusCode. تستخدم استجابات Callback دائمًا الصيغة البسيطة {"status":"done"} أيًا كانت النتيجة.

الرمزالحالةالوصف
0نجاحاكتملت العملية بنجاح.
1بيانات الطلب غير صالحةجسم JSON مشوّه أو يحتوي على قيم غير صالحة.
2Service 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 الوصول إليها.

المنفذالبروتوكولالاستخدام
80HTTPالإنتاج. اربط Callback URL بالمنفذ 80. يُضبط في API Monitor ويُستدعى تلقائيًا عند كل بصمة.
443HTTPSالإنتاج (آمن). HTTPS مع شهادة SSL صالحة. موصى به للإنتاج.
8123HTTPللاختبار فقط. منفذ غير قياسي متاح مؤقتًا أثناء التطوير.
يُوصى بـ HTTPS. استخدم HTTPS مع شهادة SSL صالحة في الإنتاج. تأكد من التجديد التلقائي دون إعادة تشغيل الخادم.

بيانات نموذجية

نماذج طلبات واستجابات جميع العمليات الـ38 موثّقة أعلاه في قسم كل عملية. لعرض موحّد:

هذه الصفحةيتضمن كل قسم عملية أعلاه JSON للطلب والاستجابة جاهزًا للنسخ مع بيانات نموذجية.
صفحة النماذج القديمةbiometric-web-api-sample-request-response.html — قائمة منسدلة لاختيار كل عملية.

التشفير

يمكن تفعيل تشفير AES-256 الاختياري لجميع البيانات المتبادلة بين Cams Protocol Engine وخادمك.

الخوارزميةAES-256 بوضع ECB مع حشو PKCS5 (AES/ECB/PKCS5PADDING).
إعداد المفتاحاضبط مفتاحك كـ Security Key في API Monitor. عند ضبطه، تُشفَّر جميع بيانات JSON الخام.
الترميزتُرمَّز البيانات المشفّرة بـ Base64 لنقل آمن عبر HTTP.

مثال 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 الصادرة باستخدام المفتاح نفسه.