البدء باستخدام 6clicks Developer API

جدول المحتويات:

• الحصول على الوصول إلى Developer API
• استخدام Developer API
• آلية المصادقة
• إنشاء حساب مستخدم API
• إنشاء مفتاح API
• إدارة مفاتيح API
• استبدال مفتاح API برمز JWT
• استخدام JWT في الطلبات اللاحقة
• اختبار التكامل عبر Swagger (اختياري)
• الوصول إلى الوثائق الكاملة لـ API

الحصول على الوصول إلى Developer API

إذا لم يظهر لك Developer API بصفتك مسؤول/مستشار/ مستخدم بالتصاريح المناسبة، ستحتاج إلى الاتصال بدعم 6clicks لتمكين الوصول إلى API في مثيل نظامك.

الوصول إلى الوثائق الكاملة لـ API

يمكن العثور على المرجع الكامل لـ API ضمن Administration > Integrations > Developer API > تبويب API Documentation.

ستجد هنا مرجعاً كاملاً لجميع نقاط نهاية API بصيغة OpenAPI (Swagger).

استخدام Developer API

يقوم 6clicks Developer API بالمصادقة باستخدام مفتاح API يمثل مستخدمًا نشطًا ضمن النظام، وهو مغلف في JSON Web Tokens (JWTs) لتعزيز الأمان. تُغلف رموز JWT معلومات المستخدم وامتيازاته، مما يوفر مزايا مقارنة بالمفاتيح البسيطة من خلال تضمين أوقات انتهاء الصلاحية وبيانات إضافية عن المستخدم.

إنشاء حساب مستخدم API

يجب إنشاء حساب مستخدم API مخصص، مع التصاريح اللازمة لمتطلبات التكامل الخاصة بك. سيحتاج هذا المستخدم إلى عنوان بريد إلكتروني صالح لاستلام الدعوة.

1. قم بإنشاء مستخدم جديد عبر Administration > Users
2. عين الدور أو التصاريح المناسبة لحساب مستخدم API. ملاحظة: يلزم وجود تصريح Integrations للوصول إلى Developer API وإنشاء مفاتيح API في الخطوة التالية.
   

إنشاء مفتاح API

1. قم بتسجيل الدخول إلى 6clicks باستخدام حساب مستخدم API
2. من القائمة الرئيسية، انتقل إلى Administration > Integrations
3. من القائمة، اختر 6clicks Developer API ثم اضغط على Connect
4. اضغط على Create API Key
5. امنح مفتاح API اسماً. نوصي بإنشاء مفتاح لكل تكامل محدد تخطط لاستخدامه.
   
6. إذا كان حسابك مفعلًا لاستخدام المصادقة المتبادلة، يمكنك بشكل اختياري رفع وتحديد شهادة بصيغة PEM/PFX.
7. اضغط على Create للحفظ وتدوين المفتاح. هذه هي المرة الوحيدة التي يمكنك فيها نسخ وحفظ هذا المفتاح.
   

إدارة مفاتيح API

• يمكن إنشاء مفاتيح API وحذفها فقط، ولا يمكن تعديلها
• هام: مفاتيح API هي وكلاء وتحمل نفس التصاريح الخاصة بالمستخدم الذي تم إنشاؤها تحته.
  
  
  
  

البحث عن نطاق API الخاص بك

يمكنك العثور على نطاق API الخاص بك في وثائق Swagger ضمن قائمة "Servers".

استبدال مفتاح API برمز JWT

أرسل طلب POST إلى نقطة النهاية "token" في Auth Controller، مع تضمين مفتاح API في ترويسة 6Clicks-Api-Key.

مثال: 

POST https://api-au.6clicks.io/auth-api/1.0/auth/token 
Headers: 
6Clicks-Api-Key: <Your_API_Key> 

بعد التحقق الناجح من مفتاح API، سيعيد API رمز JWT موقع من قبل مزود API. يحتوي هذا الـ JWT على تفاصيل حقوق وصول المستخدم ويتضمن وقت انتهاء صلاحية: الافتراضي هو ٢٤ ساعة.

مثال: 

"accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI4NTcxIiwibmFtZSI6ImdyZWcucnVkYWtvdkA2Y2xpY2tzLmNvbSIsImh0dHA6Ly9zY2hlbWFzLnhtbHNvYXAub3JnL3dzLzIwMDUvMDUvaWRlbnRpdHkvY2xhaW1zL2VtYWlsYWRkcmVzcyI6ImdyZWcucnVkYWtvdkA2Y2xpY2tzLmNvbSIsIkFzcE5ldC5JZGVudGl0eS5TZWN1cml0eVN0YW1wIjoiUUtWTVAzWlc1RklFT0pOWk5FRjQ2SlY1QklSQ0xDWVAiLCJodHRwOi8vd3d3LmFzcG5ldGJvaWxlcnBsYXRlLmNvbS9pZGVudGl0eS9jbGFpbXMvdGVuYW50SWQiOiIxNDE4IiwianRpIjoiZDcxZWNlOGYtMDFhMC00NDg0LWJlZjktZDI5NmZmZTE4MTg5IiwiaWF0IjoxNzEyMTExNDEzLCJ0b2tlbl92YWxpZGl0eV9rZXkiOiIxYmQ0NzhmOC02ZjdmLTRmYmItYTg3Ny01MjliNTQ0OTYwMmUiLCJ1c2VyX2lkZW50aWZpZXIiOiI4NTcxIiwibmJmIjoxNzEyMTExNDEzLCJleHAiOjE3MTIxOTc4MTMsImlzcyI6IjZjbGlja3MiLCJhdWQiOiJMZWdhbFJlZ1RlY2gifQ.SfaXT7Xpr_mqr15cH7GJ5uwZPieYxHHFcSlVwImd-Ww" 

استخدام JWT في الطلبات اللاحقة

قم بتضمين قيمة JWT ضمن ترويسة التفويض (authorization) في أي طلبات API لاحقة باستخدام طريقة Bearer.

مثال:

GET https://api-au.6clicks.io/assessments-api/1.0/assessments 
Authorization: Bearer <Your_JWT_Token_Value> 
Headers: 
Content-Type: application/json 
Body: 
{ 
  "sorting": "Name", 
  "maxResultCount": 10, 
  "skipCount": 0 
} 

اختبار التكامل عبر Swagger (اختياري)

إذا كنت تستخدم Swagger لاختبار API، يمكنك أيضًا تضمين JWT للمصادقة.

1. اضغط على زر Authorize داخل Swagger
2. الصق JWT في نافذة القيمة
3. سيسمح هذا لـ Swagger بتضمين JWT في الطلبات التالية لـ API لأغراض الاختبار والتوثيق

من خلال اتباع هذه الخطوات، يمكن للمطورين المصادقة والتفاعل بنجاح مع 6clicks Developer API، مما يضمن الوصول الآمن والمصرح به إلى ميزاته وبياناته.