مرجع API: البنية والحقول ورموز الحالة

اللبنات المشتركة بين جميع العمليات: تدفق الطلبات، وحقول JSON المشتركة، وأنواع القوالب، ورموز الحالة، والمنافذ، وتشفير البيانات.

مرجع واجهة API

بنية API

الخاصية	واجهة Callback	واجهة RESTful
المبادر	الجهاز / Biometric Gateway	خادمك
الاتجاه	من الجهاز إلى خادمك	من خادمك إلى الجهاز
زمن الاستجابة	لحظي (بالميلي ثانية)	~15 ثانية
المُحفِّز	حدث بيومتري على الجهاز	طلب HTTP POST من الكود الخاص بك
دورك	الاستقبال والتأكيد	إرسال الأمر وانتظار/استطلاع الاستجابة
جسم الاستجابة	`{"status":"done"}`	`{"Status":"done","OperationID":"…","StatusCode":0}`
السلوك عند انقطاع الاتصال	يخزّنها المحرك مؤقتًا وتُسلَّم عند عودة الخادم للعمل	يضعها المحرك في طابور وتُسلَّم عند إعادة اتصال الجهاز

مرجع واجهة API

الحقول المشتركة

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

مرجع واجهة API

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

تتضمن استجابات 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	للاختبار فقط. منفذ غير قياسي متاح مؤقتًا أثناء التطوير.

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