Support Hub/API & Integrations/دليل الإعداد الأول لواجهة برمجة التطبيقات (API) لأجهزة…
Translated from the English article and reviewed by a person. Read the English original
Fix

دليل الإعداد الأول لواجهة برمجة التطبيقات (API) لأجهزة Cams البيومترية

دليل الإعداد الأول لواجهة برمجة التطبيقات (API) لأجهزة Cams البيومترية

يُعد إعداد تكامل واجهة برمجة التطبيقات (API) مع جهازك البيومتري للمرة الأولى خطوةً حاسمة لضمان تواصل سلس بين جهازك وخادمك. يقدّم هذا الدليل شرحًا شاملًا خطوةً بخطوة لتهيئة نقطة نهاية الخادم، وربط جهازك البيومتري بواجهة برمجة التطبيقات، والتحقق من تدفق البيانات. 

سواء كنت مطوّرًا أو مسؤول نظام، فقد صُمم هذا الدليل ليزوّدك بالأدوات والتعليمات اللازمة لإنشاء تكامل مستقر وفعّال. وبنهايته، سيكون جهازك البيومتري مُهيأً بنجاح لإرسال البيانات الفورية إلى خادمك والعمل دون أخطاء. 

قبل المتابعة في خطوات الإعداد، يرجى التأكد من استيفاء المتطلبات الأساسية التالية. فهذا سيساعد على ضمان عملية إعداد سلسة وخالية من الأخطاء. 

المتطلبات الأساسية

لضمان عملية إعداد وتكامل سلسة، يرجى مراجعة المتطلبات التالية واستكمالها قبل المتابعة: 

1. توثيق واجهة برمجة التطبيقات (API) (للتكامل المخصص)

إذا كنت تعتزم دمج الجهاز البيومتري مع برنامجك الخاص، فمن المهم أن: 

  • تعرّف على بنى البيانات 
    تعرّف على بنى الطلبات والاستجابات النموذجية. ويشمل ذلك: 
    • حمولات عنوان الاستدعاء (Callback URL Payloads): صيغة البيانات المنقولة من الجهاز البيومتري إلى خادمك عبر عنوان الاستدعاء. 
    • حمولات واجهة RESTful (RESTful URL Payloads): صيغة البيانات المرسلة من خادمك إلى الجهاز البيومتري عبر واجهة RESTful API. 

2. نقطة نهاية الخادم (عنوان الاستدعاء Callback URL)

بالنسبة لتكاملات واجهة برمجة التطبيقات المخصصة، تأكد مما يلي: 

  • عنوان استدعاء يعمل بشكل صحيح 
    وهو نقطة نهاية الخادم التي سيرسل إليها الجهاز البيومتري بيانات الحضور الفورية. 
  • إمكانية الوصول إلى الشبكة 
    تأكد من إمكانية الوصول إلى عنوان الاستدعاء عبر الإنترنت أو شبكتك المحلية. 

3. جاهزية الجهاز البيومتري 

قبل الإعداد، تأكد من أن الجهاز مُهيأ وجاهز للتكامل: 

  • توفر الجهاز 
    يجب أن يكون الجهاز البيومتري في الموقع ويمكن الوصول إليه فعليًا. 
  • الاتصال بالشبكة 
    • شغّل الجهاز. 
    • وصّله بالشبكة عبر LAN أو Wi-Fi. 
    • تأكد من أنه متصل بالإنترنت ويمكنه التواصل مع خادمك. 

4. المنصات المدمجة مسبقًا 

إذا كنت تدمج الجهاز البيومتري مع منصات مثل Zoho وBayzat وOrangeHRM وPalmHR وRazorpay وERPNext وSAP وOdoo، أو ما شابهها: 

  • عناوين استدعاء مُهيأة مسبقًا 
    لا حاجة لإعداد عنوان الاستدعاء يدويًا، إذ تتولى هذه المنصات ذلك نيابةً عنك. 
  • معالجة البيانات تلقائيًا 
    تتم إدارة صيغ البيانات ونقلها تلقائيًا بواسطة التكاملات المعنية. 

يُبسّط هذا الأسلوب عملية الإعداد بشكل كبير للمنصات المدعومة. 

بالتأكد من استيفاء هذه المتطلبات الأساسية، ستكون مستعدًا جيدًا لتكامل بيومتري سلس وفعّال، سواء كنت تعمل مع نظام مخصص أو منصة تابعة لطرف ثالث. 


لنبدأ

سجّل الدخول إلى https://Camsbiometrics.com

نظرة عامة على لوحة حالة الأجهزة

بعد تسجيل الدخول بنجاح، توفر لوحة حالة الأجهزة (Device Status Dashboard) للمستخدمين نظرة عامة ولوحة تحكم لإدارة الأجهزة البيومترية. 

1. عرضان لبطاقة الجهاز

2. ملخص حالة الأجهزة

يمنحك هذا القسم نظرة عامة شاملة على جميع الأجهزة المرتبطة بمؤسستك. 

  • الميزات الرئيسية:
    • فلاتر الحالة:
      يمكنك بسهولة تصفية الأجهزة حسب حالتها الحالية:
      • الكل: عرض جميع الأجهزة المسجلة.
      • متصل: الأجهزة المتصلة بشكل نشط.
      • غير متصل: الأجهزة التي لا يمكن الوصول إليها حاليًا. 
        راجع https://forum.camsbiometrics.com/how-to-bring-the-cams-biometrics-machine-online/ لحل أي مشكلة اتصال في الأجهزة.
      • في الانتظار: الأجهزة التي لديها إجراءات معلّقة.
      • ترخيص نشط: الأجهزة ذات التراخيص السارية.
      • تنتهي قريبًا: التراخيص التي تقترب من تاريخ انتهائها. 
      • منتهية: التراخيص التي تحتاج إلى تجديد.
      • إضافة أجهزة موثّقة: اختصار لإضافة أجهزة موثّقة جديدة.
  • بطاقات الأجهزة:
    • تمثل كل بطاقة جهازًا بيومتريًا واحدًا، وتعرض تفاصيله الرئيسية وحالته. 
    • تتيح أزرار مثل "تجديد الآن" تجديد الترخيص بسرعة للأجهزة المنتهية أو التي على وشك الانتهاء 
    • تقدّم مؤشرات الحالة مثل لا يوجد حضور أو غير متصل أو غير نشط معلومات حول وظائف الجهاز. 

3. تفاصيل الجهاز الفردي

تقدم كل بطاقة جهاز معلومات فورية ووصولًا إلى الإعدادات.

  • معلومات الجهاز:
    • الاسم والرقم التسلسلي للتعريف 
    • تاريخ صلاحية خدمة واجهة برمجة التطبيقات (API) 
    • نوع الطراز ووقت آخر اتصال 
  • مؤشرات الحالة:
    • لا يوجد حضور – لم يتم تسجيل أي بيانات بصمة. 
    • غير متصل – الجهاز غير قابل للوصول حاليًا. 
    • عدد الانتظار/المرسل/المستلم – لمراقبة تدفق البصمات 
  • الإجراءات المتاحة:
    • إعادة تشغيل الطابور – يدفع الطابور البيانات فورًا. 
    • الإعدادات – تعديل المنطقة الزمنية والاتجاه وعنوان الاستدعاء وغيرها. 
    • آخر استجابة – عرض آخر استجابة من الخادم لتصحيح المشكلات. 
  • زر تجديد الآن:
    • يتيح للمستخدمين تجديد تراخيص الأجهزة بسرعة عند الحاجة.

4. إدارة الأجهزة المتقدمة

بالنسبة للمسؤولين الذين يديرون أجهزة متعددة، توفر لوحة التحكم ما يلي:

  • الميزات الرئيسية:
    • تحديثات الحالة التفصيلية:
      • وقت آخر اتصال، وحالة الترخيص، وإعدادات واجهة برمجة التطبيقات (API).
      • تجميع الأجهزة حسب حالاتها التشغيلية الحالية (مثل: غير متصل، منتهٍ).
    • خيارات إضافية (إظهار المزيد):
      • النقر على "إظهار المزيد" يوسّع العرض لإظهار معلومات أكثر تفصيلًا عن الجهاز أو خيارات الإعداد.
    • الإجراءات الجماعية:
      • تجديد أو إعداد عدة أجهزة مباشرةً من هذه اللوحة.

التنقل في الشريط الجانبي

  • قسم المؤسسة 
    • معلومات المؤسسة: عرض الملف التعريفي للشركة وتعديله 
    • الدعم: رفع تذاكر الدعم لحل المشكلات 
  • قسم الطلبات 
    • قائمة الطلبات: تتبع وإدارة مشتريات الأجهزة/التراخيص 
  • قسم إدارة الأجهزة 
    • حالة الجهاز: يعرض حالة اتصال الجهاز مثل متصل أو غير متصل، ووقت آخر اتصال، والتحقق من الترخيص، مما يساعدك على معرفة حالة جهازك. 
    • سجل واجهة برمجة التطبيقات (API Log): يعرض جميع بيانات الحضور لديك، مما يساعدك على التحقق يوميًا مما إذا كانت البيانات قد أُرسلت بنجاح أم لا. يعرض السجل بيانات آخر 30 يومًا فقط. 
    • قائمة الأجهزة: تعرض جميع الأجهزة المسجلة مع معرّف علامة الخدمة الخاصة بها وتواريخ انتهائها ومعلومات العميل المرتبط بها. تساعدك على مراقبة تراخيص الأجهزة وإدارة التجديدات بكفاءة لضمان استمرارية الخدمة.  
    • أوامر الجهاز: استخدم هذه الصفحة لتنفيذ الأوامر على أجهزتك البيومترية. اختر الجهاز (معرّف علامة الخدمة)، والأمر الذي تريد تشغيله. عادةً تستغرق الأوامر من 30 إلى 60 ثانية لإكمالها، لذا يرجى التأكد من بقاء الجهاز متصلًا أثناء التنفيذ. 
      الأوامر المتاحة: 
      • إعادة إرسال جميع بيانات المستخدمين: يعيد إرسال بيانات المستخدمين كاملةً إلى الجهاز المحدد. 
      • إعادة إرسال سجلات الحضور: يعيد إرسال سجلات الحضور من الجهاز. 
      • إضافة مستخدم: يضيف مستخدمًا جديدًا إلى الجهاز. 
      • حذف مستخدم: يزيل مستخدمًا من الجهاز. 
      • مسح جميع صلاحيات المسؤول: يزيل جميع الصلاحيات الإدارية من الجهاز. 
    • مجموعة الأجهزة: تتيح لك هذه الصفحة إدارة مجموعات الأجهزة ضمن حسابك. يمكنك عرض المجموعات وتنظيمها، وإضافة مجموعات جديدة، ومشاهدة تفاصيل مثل أسماء المجموعات والأجهزة المضمنة فيها. باستخدام مجموعات الأجهزة، يمكنك مزامنة جميع الأجهزة داخل المجموعة لإدارة فعّالة ومبسطة. 
    • تجديد الخدمة: تتيح لك هذه الصفحة إدارة الخدمات المرتبطة بأجهزتك غير النشطة وتجديدها. يمكنك عرض قائمة الأجهزة ذات الخدمات غير النشطة، والاطلاع على تفاصيل الخدمة، وتجديدها بسهولة عبر تفعيل خيار "إضافة". تدعم الواجهة البحث والترقيم لإدارة عدة أجهزة وتجديدات الخدمة بكفاءة. 

كيفية استخدام لوحة التحكم

صُممت لوحة تحكم Cams البيومترية لتبسيط إدارة الأجهزة وتعزيزها. إليك كيفية الاستفادة القصوى من ميزاتها: 

  1. مراقبة صحة الأجهزة:
    • استخدم فلاتر الحالة (مثل: غير متصل، تراخيص منتهية) لتحديد الأجهزة التي تحتاج إلى اهتمام بسرعة. 
    • حدّد بسهولة الأجهزة التي تعاني من مشكلات في الترخيص أو الاتصال أو الحالة غير النشطة. 
  2. تنفيذ الإجراءات الأساسية:
    • انقر على تجديد الآن لتجديد تراخيص الأجهزة التي على وشك الانتهاء أو انتهت فورًا. 
    • استخدم إظهار المزيد للوصول إلى إعدادات مفصلة وتنفيذ إجراءات متقدمة على كل جهاز على حدة. 
  3. الوصول إلى سجلات الأجهزة:
    • انتقل إلى سجل واجهة برمجة التطبيقات (API Log) وقائمة الأجهزة لمراقبة تفاعلات واجهة برمجة التطبيقات، ومراجعة سجل تواصل الأجهزة، واستكشاف المشكلات وحلها بفعالية. 
  4. إدارة مجموعات الأجهزة:
    • استخدم ميزة مجموعة الأجهزة لتنظيم الأجهزة حسب الفروع أو الأقسام أو التجميعات المخصصة لتحكم ووضوح أفضل. 
  5. إعادة تشغيل طابور الجهاز:
    • تحقق من آخر استجابة للتأكد من أن الخادم يعيد استجابة صالحة وفقًا لمواصفات واجهة برمجة التطبيقات. 
    • إذا تم حل المشكلة، انقر على إعادة تشغيل الطابور لاستئناف نقل البيانات فورًا. أو يمكنك الانتظار حتى إعادة التشغيل التلقائية المجدولة للطابور. 

صُممت لوحة التحكم لتبسيط إدارة الأجهزة، وتزويد المستخدمين بإجراءات سريعة، ومعلومات، وأدوات متقدمة للحفاظ على التشغيل الأمثل. وإن أردت التوسع في أي قسم أو إضافة شرح خطوة بخطوة، فأخبرني! 

نظرة عامة على صفحة الإعدادات

تتيح لك هذه الصفحة إعداد جهازك البيومتري وتحسينه ليتكامل بسلاسة مع الخادم. فيما يلي تفصيل للأقسام والإعدادات الأساسية المتاحة للتهيئة

1. لوحة معلومات الجهاز (أعلى اليسار)

  • الرقم التسلسلي:
    • يحدد الرقم التسلسلي الفريد للجهاز البيومتري.
      مثال: AIOR18510621.
  • اسم التسمية:
    • التسمية أو الاسم المخصص الذي يُعطى للجهاز لتسهيل التعرف عليه.
      مثال: AIOR18486078.
  • اسم العميل:
    • يعرض اسم العميل أو المؤسسة المرتبطة بالجهاز.
      مثال: Nalan Garments.

2. إعدادات الجهاز (أسفل اليسار)

تحدد معلمات الإعداد الأساسية للجهاز البيومتري.

  • المنطقة الزمنية:
    • اختر المنطقة الزمنية المحلية المناسبة للتوقيت الدقيق لبيانات الحضور.
    • مثال: (UTC+05:30) Chennai, Kolkata, Mumbai, New Delhi.
  • الاتجاه:
    يتحكم في كيفية تفسير إدخالات الحضور وإرسالها إلى الخادم
    أوضاع الاتجاه:
    • فعلي: استخدمه عند الحاجة إلى حالات حضور دقيقة دون تعديل. 
    • دخول/خروج: استخدمه عندما يلزم تتبع نوع واحد فقط من الحالات (مثل الدخول أو الخروج). 
    • استراحة دخول/خروج: مثالي لإدارة أحداث محددة مثل فترات الاستراحة. 
    • الأول دخول، والباقي خروج: يبسّط بيانات الحضور لبيئات الوردية الواحدة. 
    • متعرج: مناسب للبيئات المنظمة ذات الإدخالات والخروجات المتناوبة. 

      توفر هذه الخيارات مرونة لتلبية متطلبات الأعمال أو المؤسسات المختلفة. 
  • الوقت المتوقع:
    يعرض الوقت الحالي المُهيأ على الجهاز البيومتري. (مثال: 24-Nov-2024 15:40)
    • إذا بدا وقت الجهاز البيومتري غير صحيح حتى بعد اختيار المنطقة الزمنية المناسبة: 
      • ضبط الوقت: استخدم هذا الخيار لمزامنة ساعة الجهاز مع وقت الخادم.
      • تفعيل التوقيت الصيفي (DLS): فعّله إذا كانت منطقتك تعتمد التوقيت الصيفي لضمان تتبع دقيق للوقت.

3. إعدادات واجهة برمجة التطبيقات (API) (اللوحة اليمنى)

تُستخدم لإعداد الاتصال بين جهازك وخادمك لنقل بيانات الحضور الفورية. 

عنوان الاستدعاء (Callback URL)

  • الغرض: يحدد نقطة نهاية الخادم التي ستُرسل إليها بيانات الحضور. 
  • حقل الإدخال: أدخل عنوان الاستدعاء (Callback URL) الخاص ببرنامجك/خادمك لاستقبال السجلات. 

معالجة الاستجابة (Handle Response)

  • نعم: يتطلب استجابة JSON ({status: “done”}) من خادمك لتأكيد استلام البيانات بنجاح. إذا لم تُرجع، يعيد النظام المحاولة كل 3 ساعات. 
  • لا: يفترض النجاح إذا كان رمز حالة HTTP هو 200، دون التحقق من محتوى الرسالة. 

رمز المصادقة (Auth Token)

  • الغرض: يضمن اتصالًا آمنًا عبر المصادقة القائمة على الرموز.
  • الإجراءات:
    • انقر على إنشاء لتوليد رمز جديد. 
    • استخدم نسخ لاسترجاع الرمز وحفظه للتكامل على جانب الخادم. 

مفتاح التشفير (اختياري) 

  • الغرض: تشفير الاتصال باستخدام تشفير AES ECB 256 بت.
  • حقل الإدخال: أدخل مفتاحًا مخصصًا إذا كان التشفير مطلوبًا، أو اتركه فارغًا.

عنوان IP المصدر (Origin IP)

  • الغرض: تقييد الوصول إلى الجهاز على عنوان IP محدد.
  • حقل الإدخال: استخدم localhost أثناء الاختبار، أو حدّد عنوان IP العام للخادم في بيئة الإنتاج.

نقطة نهاية واجهة الإدارة (Management API Endpoint)

خطوات الإعداد 

1. ضبط المنطقة الزمنية 

  • اختر المنطقة الزمنية المناسبة بناءً على توقيتك المحلي. 

2. اختيار اتجاه الحضور 

  • اضبط اتجاه الحضور وفقًا لمتطلبات مؤسستك. 

3. ضبط الوقت (عند الحاجة) 

  • إذا كانت ساعة الجهاز الداخلية غير صحيحة، استخدم خيار "ضبط الوقت" لمزامنتها. 

4. إعداد عنوان الاستدعاء (Callback URL) 

  • أدخل نقطة نهاية الخادم التي ستستقبل بيانات الحضور. 

5. تفعيل معالجة الاستجابة (Handle Response) 

  • فعّل هذا الخيار أو عطّله حسب قدرة خادمك على إرجاع استجابات الإقرار. 

6. إعداد الاتصال الآمن 

  • أنشئ واستخدم رمز المصادقة (Auth Token). 
  • (اختياري) فعّل التشفير بتعيين مفتاح التشفير. 
  • حدّد عنوان IP المصدر (Origin IP) لتقييد الوصول وتعزيز الأمان. 

7. تحديث الإعدادات 

  • انقر على تحديث، ثم انقر على موافق لحفظ التغييرات. 

ملاحظة: تحقق من انعكاس المنطقة الزمنية المختارة على جهازك. إذا لم يحدث ذلك، فنفّذ الخطوة 3 لضبط الوقت. 

8. التحقق من حالة الجهاز وتكامل واجهة برمجة التطبيقات (API) 

  • تأكد من أن جهازك متصل في صفحة حالة الجهاز (Device Status). 
  • بعد اتصال الجهاز، أضف مستخدمًا تجريبيًا وسجّل بصمة حضور على الجهاز. 
  • الآن، انتقل إلى إدارة الأجهزة > حالة الجهاز وتحقق من آخر استجابة لعرض أحدث استجابة وردت من الخادم. 
    • انتظر 30 ثانية، ثم حدّث الصفحة، وتحقق مما إذا كانت آخر استجابة تُظهر "Status:Done". 
  • يمكنك الآن البدء في تسجيل الحضور ومراجعة التقارير. 
    • إذا لم تظهر التقارير في برنامجك، فتحقق من قسم آخر استجابة بحثًا عن أي رسائل خطأ، ثم عالجها وفقًا لذلك. 

9. الدعم 
إذا كانت لديك أي أسئلة أو واجهتَ أي مشكلات أثناء الخطوات المذكورة أعلاه، يرجى رفع تذكرة دعم عبر الموقع camsbiometrics.com. انتقل إلى المؤسسة – > الدعم لإرسال طلبك. سيتولى فريقنا الرد على استفساراتك بسرعة. 

Was this article helpful?