الأسئلة الشائعة وSDK والتكلفة
أسئلة شائعة من المطورين، وكيفية عمل SDK وتسعير واجهة API.
معلومات إضافية
الأسئلة الشائعة
أسئلة شائعة حول التكامل مع Cams Biometrics Web API 3.0.
عام
س: ما هي Cams Biometric Gateway وواجهة Biometric API الخاصة بها؟
Cams Biometric Gateway منصة سحابية شاملة توفر واجهة Biometric API تمكّن أي تطبيق ويب من التواصل لحظيًا مع أجهزة الحضور البيومتري والتحكم في الدخول. تدعم 38 عملية عبر واجهات Callback (الواردة) وRESTful (الصادرة) — دون الحاجة إلى SDK للجهاز أو IP ثابت.
Cams Biometric Gateway منصة سحابية شاملة توفر واجهة Biometric API تمكّن أي تطبيق ويب من التواصل لحظيًا مع أجهزة الحضور البيومتري والتحكم في الدخول. تدعم 38 عملية عبر واجهات Callback (الواردة) وRESTful (الصادرة) — دون الحاجة إلى SDK للجهاز أو IP ثابت.
س: هل أحتاج إلى SDK للتكامل؟
لا. لا توفّر Cams أي SDK ولا تتطلبه. تعتمد جميع الاتصالات على طلبات HTTP/HTTPS POST القياسية مع بيانات JSON. تصلح أي لغة قادرة على إجراء استدعاءات HTTP.
لا. لا توفّر Cams أي SDK ولا تتطلبه. تعتمد جميع الاتصالات على طلبات HTTP/HTTPS POST القياسية مع بيانات JSON. تصلح أي لغة قادرة على إجراء استدعاءات HTTP.
س: ما لغات البرمجة المدعومة؟
أي لغة قادرة على إرسال/استقبال HTTP POST بصيغة JSON — PHP وPython وJava وC# وNode.js وGo وRuby وغيرها. نوفّر موجّهات مولّد الأكواد بالذكاء الاصطناعي لـ 7 لغات.
أي لغة قادرة على إرسال/استقبال HTTP POST بصيغة JSON — PHP وPython وJava وC# وNode.js وGo وRuby وغيرها. نوفّر موجّهات مولّد الأكواد بالذكاء الاصطناعي لـ 7 لغات.
س: ما هو Cams Protocol Engine؟
هو الوسيط السحابي بين الأجهزة البيومترية وخادمك. يتولى ترجمة البروتوكولات، وتوحيد البيانات، والتخزين المؤقت عند عدم الاتصال، ويوفّر واجهة JSON متسقة أيًا كانت علامة الجهاز أو طرازه.
هو الوسيط السحابي بين الأجهزة البيومترية وخادمك. يتولى ترجمة البروتوكولات، وتوحيد البيانات، والتخزين المؤقت عند عدم الاتصال، ويوفّر واجهة JSON متسقة أيًا كانت علامة الجهاز أو طرازه.
س: ما هو API Monitor؟
API Monitor هو بوابة الإدارة لديك حيث تضبط عناوين Callback URL، وتدير AuthToken، وتعيّن Security Key، وتعرض حالة الأجهزة، وتصل إلى عنوان RESTful endpoint ومعرّفات Service Tag.
API Monitor هو بوابة الإدارة لديك حيث تضبط عناوين Callback URL، وتدير AuthToken، وتعيّن Security Key، وتعرض حالة الأجهزة، وتصل إلى عنوان RESTful endpoint ومعرّفات Service Tag.
توافق الأجهزة
س: ما الأجهزة البيومترية المدعومة؟
تدعم جميع أجهزة Cams Biometrics (المدرجة في camsbiometrics.com/product) واجهة API الكاملة عبر Native Push. كما تحظى الأجهزة المعتمدة في developer.camsbiometrics.com بدعم Native Push الكامل.
تدعم جميع أجهزة Cams Biometrics (المدرجة في camsbiometrics.com/product) واجهة API الكاملة عبر Native Push. كما تحظى الأجهزة المعتمدة في developer.camsbiometrics.com بدعم Native Push الكامل.
س: هل يمكن للأجهزة غير التابعة لـ Cams (ZkTeco وeSSL وBioMax وغيرها) استخدام هذه الواجهة؟
نعم، مع Protocol Update. تعمل الأجهزة غير التابعة لـ Cams وغير المعتمدة عبر Hybrid Push. قد تكون بعض الميزات محدودة بحسب وضع الاتصال وإمكانات العتاد.
نعم، مع Protocol Update. تعمل الأجهزة غير التابعة لـ Cams وغير المعتمدة عبر Hybrid Push. قد تكون بعض الميزات محدودة بحسب وضع الاتصال وإمكانات العتاد.
س: ما الفرق بين Native Push وHybrid Push؟
Native Push: دعم كامل لواجهة API دون قيود — تعمل جميع العمليات الـ38. متاح لأجهزة Cams والأجهزة المعتمدة.
Hybrid Push: للأجهزة غير التابعة لـ Cams/غير المعتمدة. يعتمد توفر الميزات على وضع الاتصال (SDK أو DB Pull أو معالجة الملفات). انظر أوضاع الاتصال.
Native Push: دعم كامل لواجهة API دون قيود — تعمل جميع العمليات الـ38. متاح لأجهزة Cams والأجهزة المعتمدة.
Hybrid Push: للأجهزة غير التابعة لـ Cams/غير المعتمدة. يعتمد توفر الميزات على وضع الاتصال (SDK أو DB Pull أو معالجة الملفات). انظر أوضاع الاتصال.
س: ما الطرق البيومترية المدعومة؟
البصمة، والتعرّف على الوجه، ووريد راحة اليد، وبطاقة RFID/القرب، ورمز PIN/كلمة المرور الرقمية، ومسح القزحية، وقياس درجة حرارة الجسم (بحسب الجهاز).
البصمة، والتعرّف على الوجه، ووريد راحة اليد، وبطاقة RFID/القرب، ورمز PIN/كلمة المرور الرقمية، ومسح القزحية، وقياس درجة حرارة الجسم (بحسب الجهاز).
س: بعض ميزات API لا تعمل مع جهازي. لماذا؟
يعتمد ذلك على (a) وضع الاتصال — إذ تدعم أوضاع DB Pull ومعالجة الملفات دفع الحضور فقط دون واجهات RESTful، و(b) قيود العتاد — فقد لا تدعم بعض طُرز الأجهزة ميزات معيّنة على مستوى البرنامج الثابت. اختبر مع عتادك وتواصل مع دعم Cams للمساعدة.
يعتمد ذلك على (a) وضع الاتصال — إذ تدعم أوضاع DB Pull ومعالجة الملفات دفع الحضور فقط دون واجهات RESTful، و(b) قيود العتاد — فقد لا تدعم بعض طُرز الأجهزة ميزات معيّنة على مستوى البرنامج الثابت. اختبر مع عتادك وتواصل مع دعم Cams للمساعدة.
واجهة Callback (من الجهاز → الخادم)
س: ما هي واجهة Callback؟
توصل واجهة Callback الأحداث اللحظية من الأجهزة البيومترية إلى خادمك. عند حدوث بصمة أو تعديل مستخدم على الجهاز، يرسل Cams Protocol Engine فورًا بيانات JSON بطلب POST إلى Callback URL الذي ضبطته.
توصل واجهة Callback الأحداث اللحظية من الأجهزة البيومترية إلى خادمك. عند حدوث بصمة أو تعديل مستخدم على الجهاز، يرسل Cams Protocol Engine فورًا بيانات JSON بطلب POST إلى Callback URL الذي ضبطته.
س: بماذا يجب أن يرد خادمي؟
أعد دائمًا
أعد دائمًا
{"status":"done"} مع رمز HTTP 200 — حتى لو فشلت معالجتك الداخلية. لا تعطّل Cams Protocol Engine أبدًا. ضع المعالجة الثقيلة في طابور للتنفيذ غير المتزامن.س: ماذا يحدث إذا كان خادمي غير متصل عند حدوث بصمة؟
تخزّن Biometric Gateway جميع الأحداث مؤقتًا وتسلّمها تلقائيًا عند عودة خادمك للعمل. لا تُفقد أي بيانات.
تخزّن Biometric Gateway جميع الأحداث مؤقتًا وتسلّمها تلقائيًا عند عودة خادمك للعمل. لا تُفقد أي بيانات.
س: كيف أتعامل مع البصمات المكرّرة؟
نفّذ منطق اكتشاف التكرار على خادمك باستخدام الجمع بين
نفّذ منطق اكتشاف التكرار على خادمك باستخدام الجمع بين
UserID + LogTime. قد تُعاد البصمة نفسها أثناء الاستعادة بعد انقطاع الاتصال أو عند إعادة محاولات الشبكة.س: ما أنواع البصمات المدعومة؟
CheckIn وCheckOut وBreakOut وBreakIn وOverTimeIn وOverTimeOut وMealIn وMealOut. يوضح الحقل InputType الطريقة البيومترية المستخدمة: Fingerprint أو Face أو Palm أو Card أو Password.س: كيف تعمل قوالب المستخدمين في Callback؟
عند تحديث مستخدم على الجهاز (العمليات #3–#9)، قد تصل القوالب واحدًا تلو الآخر أو في مجموعات عبر عدة استدعاءات. يحمل كل استدعاء القوالب التي تغيّرت فقط — وليس المجموعة الكاملة. يجب أن يدمج/يُجري upsert خادمك حسب
عند تحديث مستخدم على الجهاز (العمليات #3–#9)، قد تصل القوالب واحدًا تلو الآخر أو في مجموعات عبر عدة استدعاءات. يحمل كل استدعاء القوالب التي تغيّرت فقط — وليس المجموعة الكاملة. يجب أن يدمج/يُجري upsert خادمك حسب
Type + Index كمفتاح فريد. لا تستبدل جميع القوالب أبدًا عند استدعاء واحد.س: هل يمكنني استقبال صور الحضور؟
نعم. تسلّم العملية #10 RealTimeAttendancePhoto لقطة JPEG مرمّزة بـ Base64 ملتقطة وقت البصمة. وهي منفصلة عن Callback سجل البصمات (#11) ومتاحة في الأجهزة المزوّدة بكاميرا.
نعم. تسلّم العملية #10 RealTimeAttendancePhoto لقطة JPEG مرمّزة بـ Base64 ملتقطة وقت البصمة. وهي منفصلة عن Callback سجل البصمات (#11) ومتاحة في الأجهزة المزوّدة بكاميرا.
س: هل يتضمن Callback درجة الحرارة وكشف الكمامة؟
نعم، إذا كان الجهاز يدعم ذلك. يتضمن الكائن
نعم، إذا كان الجهاز يدعم ذلك. يتضمن الكائن
PunchLog الحقل Temperature (قراءة درجة حرارة الجسم) وFaceMask (قيمة منطقية — هل رُصدت كمامة وجه).واجهة RESTful (من الخادم → الجهاز)
س: ما هي واجهة RESTful؟
تتيح واجهة RESTful لخادمك إرسال أوامر إلى الأجهزة البيومترية — إضافة/حذف المستخدمين، وتحميل السجلات، وتسجيل البيانات البيومترية، والتحكم في الوصول. ترسل JSON بطلب POST إلى عنوان endpoint الموجود في حساب API Monitor.
تتيح واجهة RESTful لخادمك إرسال أوامر إلى الأجهزة البيومترية — إضافة/حذف المستخدمين، وتحميل السجلات، وتسجيل البيانات البيومترية، والتحكم في الوصول. ترسل JSON بطلب POST إلى عنوان endpoint الموجود في حساب API Monitor.
س: أين أجد عنوان RESTful endpoint؟
سجّل الدخول إلى حساب API Monitor. يُدرج عنوان RESTful endpoint ومعرّفات Service Tag (
سجّل الدخول إلى حساب API Monitor. يُدرج عنوان RESTful endpoint ومعرّفات Service Tag (
stgid) هناك.س: ما زمن الاستجابة لأوامر RESTful؟
نحو 15 ثانية. تضع Biometric Gateway أمرك في طابور وتسلّمه إلى الجهاز عند اتصاله التالي (وهو شبه مستمر للأجهزة المتصلة).
نحو 15 ثانية. تضع Biometric Gateway أمرك في طابور وتسلّمه إلى الجهاز عند اتصاله التالي (وهو شبه مستمر للأجهزة المتصلة).
س: ما الحد الأقصى للنطاق الزمني في LoadLog؟
الحد الأقصى الموصى به هو 30 يومًا لكل طلب. للنطاقات الأكبر، أرسل عدة طلبات بنوافذ زمنية متتالية.
الحد الأقصى الموصى به هو 30 يومًا لكل طلب. للنطاقات الأكبر، أرسل عدة طلبات بنوافذ زمنية متتالية.
س: هل يمكنني إضافة مستخدم بعدة قوالب بيومترية دفعة واحدة؟
نعم. تقبل مصفوفة Template عدة عناصر. على سبيل المثال، تضيف العملية #27 مستخدمًا ببطاقة + بصمة + كلمة مرور + وجه + راحة اليد + صورة المستخدم في طلب واحد.
نعم. تقبل مصفوفة Template عدة عناصر. على سبيل المثال، تضيف العملية #27 مستخدمًا ببطاقة + بصمة + كلمة مرور + وجه + راحة اليد + صورة المستخدم في طلب واحد.
س: ماذا يحدث إذا كان الجهاز غير متصل عند إرسال أمر RESTful؟
تضع Biometric Gateway الأمر في طابور وتسلّمه تلقائيًا عند إعادة اتصال الجهاز. ستتلقى رمز الحالة
تضع Biometric Gateway الأمر في طابور وتسلّمه تلقائيًا عند إعادة اتصال الجهاز. ستتلقى رمز الحالة
5 (الجهاز غير متصل) إذا لم يستجب الجهاز خلال مهلة الانتظار.س: كيف أتحقق من نتيجة الأمر؟
تتضمن استجابات RESTful الحقل
تتضمن استجابات RESTful الحقل
StatusCode. الرمز 0 يعني النجاح. انظر رموز حالة الاستجابة للقائمة الكاملة لرموز الأخطاء ومعانيها.س: هل يمكنني تشغيل تسجيل البصمة عن بُعد؟
نعم. تشغّل العملية #35 EnrollFingerPrint جلسة تسجيل على الجهاز. لكن يجب أن يكون المستخدم حاضرًا فعليًا عند الجهاز لمسح إصبعه.
نعم. تشغّل العملية #35 EnrollFingerPrint جلسة تسجيل على الجهاز. لكن يجب أن يكون المستخدم حاضرًا فعليًا عند الجهاز لمسح إصبعه.
الأمان والشبكات
س: هل يمكنني استخدام HTTPS لـ Callback؟
نعم. HTTPS مع شهادة SSL صالحة على المنفذ 443 مدعوم بالكامل وموصى به للإنتاج.
نعم. HTTPS مع شهادة SSL صالحة على المنفذ 443 مدعوم بالكامل وموصى به للإنتاج.
س: هل التشفير إلزامي؟
لا. تشفير AES-256 اختياري. لتفعيله، اضبط Security Key في API Monitor. عند التفعيل، تُشفَّر/تُفكّ جميع بيانات JSON باستخدام AES/ECB/PKCS5PADDING مع ترميز Base64.
لا. تشفير AES-256 اختياري. لتفعيله، اضبط Security Key في API Monitor. عند التفعيل، تُشفَّر/تُفكّ جميع بيانات JSON باستخدام AES/ECB/PKCS5PADDING مع ترميز Base64.
س: كيف أتحقق من أن Callback صادر فعلًا عن Cams؟
يتضمن كل Callback الحقل
يتضمن كل Callback الحقل
AuthToken. قارنه بالرمز المضبوط في API Monitor. ارفض أي طلب برمز غير مطابق.س: ما المنافذ التي يجب فتحها؟
المنفذ
المنفذ
80 (HTTP) أو 443 (HTTPS) للإنتاج. المنفذ 8123 متاح للاختبار فقط. انظر المنافذ المدعومة.س: كيف أختبر محليًا دون النشر على خادم؟
استخدم IP عامًا مع إعادة توجيه المنافذ، أو أداة نفق مثل ngrok. انظر الاختبار محليًا لدليل خطوة بخطوة.
استخدم IP عامًا مع إعادة توجيه المنافذ، أو أداة نفق مثل ngrok. انظر الاختبار محليًا لدليل خطوة بخطوة.
اعتبارات البيانات والتصميم
س: ما صيغة البيانات التي تستخدمها الواجهة؟
جميع الطلبات والاستجابات JSON خام بترميز UTF-8. استخدم الترويسة
جميع الطلبات والاستجابات JSON خام بترميز UTF-8. استخدم الترويسة
Content-Type: application/json. دون ترميز النماذج (form encoding).س: ما صيغة الطابع الزمني المستخدمة؟
YYYY-MM-DD HH:mm:ss GMT +OFFSET (مثل 2020-09-17 07:48:22 GMT +0530). الحقل Time بتوقيت UTC؛ وقد تستخدم الطوابع الزمنية المحلية للجهاز (مثل LogTime وOperationTime) فارق توقيت مختلفًا.س: كيف أتعامل مع البصمات غير المتصلة والبيانات بأثر رجعي؟
صمّم تطبيقك ليقبل بصمات تصل بغير ترتيبها الزمني. عندما يكون الجهاز غير متصل، سيدفع البصمات المخزّنة مؤقتًا بعد إعادة الاتصال. وقد تحتاج إلى تحديث حالة الحضور بأثر رجعي (مثل تحويل مستخدم ظهر "غائبًا" إلى "حاضر").
صمّم تطبيقك ليقبل بصمات تصل بغير ترتيبها الزمني. عندما يكون الجهاز غير متصل، سيدفع البصمات المخزّنة مؤقتًا بعد إعادة الاتصال. وقد تحتاج إلى تحديث حالة الحضور بأثر رجعي (مثل تحويل مستخدم ظهر "غائبًا" إلى "حاضر").
س: كيف أحدد الدخول/الخروج عندما يستخدم المستخدم عدة أجهزة؟
رتّب جميع بصمات المستخدم حسب
رتّب جميع بصمات المستخدم حسب
LogTime عبر جميع الأجهزة، ثم طبّق منطق عملك. لا تعتمد على الحقل Type (CheckIn/CheckOut) من جهاز واحد فقط إذا كان المستخدم يبصم على أجهزة مختلفة.س: ما هو OperationID وكيف أستخدمه؟
معرّف نصي فريد لكل عملية. في Callback الواردة، تولّده Biometric Gateway. أما في طلبات RESTful الصادرة، فعليك توليد معرّف فريد لكل طلب (UUID أو قائم على الطابع الزمني). تعيده الاستجابة كما هو لتتمكن من مطابقة أزواج الطلب/الاستجابة.
معرّف نصي فريد لكل عملية. في Callback الواردة، تولّده Biometric Gateway. أما في طلبات RESTful الصادرة، فعليك توليد معرّف فريد لكل طلب (UUID أو قائم على الطابع الزمني). تعيده الاستجابة كما هو لتتمكن من مطابقة أزواج الطلب/الاستجابة.
س: كيف تُخزَّن القوالب البيومترية وتُنقل؟
تُرمَّز البيانات البيومترية (البصمة والوجه وراحة اليد وصورة المستخدم) بـ Base64 في الحقل
تُرمَّز البيانات البيومترية (البصمة والوجه وراحة اليد وصورة المستخدم) بـ Base64 في الحقل
Data من كائن Template. تتضمن قوالب البصمة والوجه أيضًا Size (الطول بالبايت) وIndex (رقم الموضع). أرقام البطاقات وأرقام PIN سلاسل نصية عادية.التسعير والترخيص
س: كيف تُرخَّص الواجهة؟
لكل جهاز بيومتري. تتطلب السنة الأولى تفعيل API + ترخيصًا سنويًا. وتتطلب السنوات التالية تجديد الترخيص السنوي فقط. انظر تكلفة واجهة API للأسعار.
لكل جهاز بيومتري. تتطلب السنة الأولى تفعيل API + ترخيصًا سنويًا. وتتطلب السنوات التالية تجديد الترخيص السنوي فقط. انظر تكلفة واجهة API للأسعار.
س: ماذا يحدث إذا انتهى ترخيص API؟
يتوقف اتصال API لذلك الجهاز حتى يُجدَّد الترخيص. لا تتأثر بياناتك الحالية، لكن لن تُعالَج أي استدعاءات Callback أو أوامر RESTful جديدة.
يتوقف اتصال API لذلك الجهاز حتى يُجدَّد الترخيص. لا تتأثر بياناتك الحالية، لكن لن تُعالَج أي استدعاءات Callback أو أوامر RESTful جديدة.
س: هل يوجد خيار محلي (on-premise)؟
نعم. يمكن تثبيت Protocol Engine Lite على خادمك الخاص (Windows/Linux) للشبكات المحلية فقط أو البيئات المستضافة ذاتيًا. تواصل مع sales@camsbiometrics.com للتفاصيل.
نعم. يمكن تثبيت Protocol Engine Lite على خادمك الخاص (Windows/Linux) للشبكات المحلية فقط أو البيئات المستضافة ذاتيًا. تواصل مع sales@camsbiometrics.com للتفاصيل.
معلومات إضافية
SDK الحضور البيومتري
لا توفّر Cams SDK تقليديًا. تستخدم جميع العمليات واجهات HTTP Callback وRESTful القياسية — دون تثبيت أي مكتبة.
لا حاجة إلى SDK. تتم الاتصالات بالكامل عبر Cams Protocol Engine باستخدام عناوين Callback URL ونقاط HTTP RESTful.
يجعل ذلك التكامل بسيطًا مع أي منصة ويب:
OpenERPERPNextZoho PeopleSAPTallyHRAPPOdooتطبيقات ويب مخصصة
معلومات إضافية
تكلفة واجهة API
تُحتسب تراخيص API لكل جهاز بيومتري. السنة الأولى = التفعيل + الترخيص؛ والسنوات التالية = تجديد الترخيص فقط.
| الخدمة | USD | ملاحظات |
|---|---|---|
| Native Push — أجهزة Cams والأجهزة المعتمدة | ||
| تفعيل API | $120 | مرة واحدة لكل جهاز. |
| ترخيص API السنوي | $60 – $120 | يتطلب تجديدًا سنويًا. |
| Protocol Update (غير تابع لـ Cams) | $120 – $280 | مرة واحدة. يفعّل بروتوكول Cams على الأجهزة غير التابعة لـ Cams. |
| Hybrid Push — ZKTeco وeSSL وجميع العلامات الأخرى | ||
| تفعيل API | $150 | مرة واحدة لكل جهاز. |
| ترخيص API السنوي | $90 – $150 | يتطلب تجديدًا سنويًا. |
| Hybrid Connector (غير معتمد) | $150 – $300 | مرة واحدة. مطلوب للأجهزة غير المعتمدة التي تستخدم Hybrid Push. |
| العتاد وأخرى | ||
| العتاد | $220 – $720 | يختلف بحسب الطراز. |
Protocol Engine Lite (محلي) — للشبكات المحلية فقط أو البيئات المستضافة ذاتيًا. التكلفة: $500–$10,000. تواصل مع المبيعات للتفاصيل.