الانتقال إلى المحتوى الرئيسي

Documentation Index

Fetch the complete documentation index at: https://docs.oneclickdz.com/llms.txt

Use this file to discover all available pages before exploring further.

المصادقة بمفتاح API

تستخدم OneClickDz Flexy API المصادقة بمفتاح API. يجب أن تتضمن جميع الطلبات مفتاح API في رأس الطلب.

تنسيق الرأس

X-Access-Token: YOUR_API_KEY
اسم الرأس هو X-Access-Token (وليس Authorization). تأكد من استخدام الاسم الصحيح للرأس.

أنواع مفاتيح API

لديك وصول إلى نوعين من مفاتيح API:

مفتاح Sandbox

الغرض: الاختبار والتطوير - لا خصم من الرصيد الحقيقي - استجابات محاكاة - أرقام اختبار خاصة متاحة - آمن للتطوير

مفتاح Production

الغرض: المعاملات الفعلية - خصم من الرصيد الحقيقي - تكامل مع المشغل الفعلي - جاهز للإنتاج - استخدم بحذر

إنشاء مفاتيح API

1

تسجيل الدخول إلى لوحة التحكم

قم بزيارة enterprise.oneclickdz.com وسجّل الدخول إلى حسابك
2

الانتقال إلى الإعدادات

انتقل إلى الإعدادات ← تكوين API
3

إنشاء المفاتيح

انقر على “إنشاء مفتاح API” لبيئتي Sandbox وProduction
4

الحفظ بأمان

انسخ مفاتيحك واحفظها في مكان آمن. لن تتمكن من رؤيتها مجدداً.

التحقق من مفتاح API

اختبر مفتاح API باستخدام endpoint التحقق:
curl --request GET \
  --url https://api.oneclickdz.com/v3/validate \
  --header 'X-Access-Token: YOUR_API_KEY'

الاستجابة عند النجاح

{
  "success": true,
  "data": {
    "username": "+213665983439",
    "apiKey": {
      "key": "ea27b376-9f5c-4b09-883f-1b96cd7b541c",
      "isEnabled": true,
      "type": "SANDBOX",
      "allowedips": [],
      "scope": "READ-WRITE"
    }
  }
}

خصائص مفتاح API

يتضمن مفتاح API الخاص بك الخصائص التالية:
الخاصيةالوصف
keyمعرّف مفتاح API الفريد
isEnabledهل المفتاح نشط
typeSANDBOX أو PRODUCTION
allowedipsالقائمة البيضاء لعناوين IP
scopeREAD-WRITE أو READ-ONLY

القائمة البيضاء لعناوين IP

لتعزيز الأمان، يمكنك تقييد مفاتيح API الخاصة بك على عناوين IP محددة. لكل بيئة (Production وSandbox) قائمتها البيضاء المستقلة.
1

الانتقال إلى إعدادات API

انتقل إلى الإعدادات ← تكوين API في لوحة التحكم
2

إضافة عناوين IP

أدخل عناوين IP المحددة لكل بيئة: - القائمة البيضاء لـ Production: تتحكم في الوصول لمفتاح API الإنتاج - القائمة البيضاء لـ Sandbox: تتحكم في الوصول لمفتاح API sandbox - اتركها فارغة للسماح لجميع العناوين
3

حفظ التغييرات

انقر على “تحديث القائمة البيضاء” لتطبيق التغييرات
عندما تحتوي القائمة البيضاء على عناوين، ستُسمح فقط تلك العناوين المحددة. ستُرفض الطلبات من عناوين IP أخرى بخطأ 403.

تنسيق القائمة البيضاء

أضف عناوين IP محددة إلى القائمة البيضاء، واحد في كل سطر:
  • 203.0.113.45 - يسمح فقط لهذا العنوان
  • 198.51.100.23 - عنوان IP آخر محدد
اترك القائمة البيضاء فارغة للسماح لجميع عناوين IP (السلوك الافتراضي). أضف عناوين IP لتفعيل القيود.

نطاقات المفاتيح

يمكن أن تمتلك مفاتيح API مستويات وصول مختلفة:

READ-WRITE (الافتراضي)

وصول كامل لجميع العمليات:
  • عرض الرصيد والمعاملات
  • إرسال الشحنات
  • تقديم الطلبات
  • التحقق من الحالات

READ-ONLY

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

استجابات الأخطاء

400 - مفتاح API مفقود

{
  "success": false,
  "error": {
    "code": "MISSING_ACCESS_TOKEN",
    "message": "Access token is required"
  },
  "requestId": "req_abc123"
}

401 - مفتاح API غير صالح

{
  "success": false,
  "error": {
    "code": "INVALID_ACCESS_TOKEN",
    "message": "The provided access token is invalid",
    "details": {
      "attemptsLeft": 3
    }
  },
  "requestId": "req_abc123"
}
بعد 5 محاولات مصادقة فاشلة، سيتم حجب عنوان IP الخاص بك مؤقتاً لمدة 15 دقيقة.

403 - عنوان IP غير مسموح به

{
  "success": false,
  "error": {
    "code": "IP_NOT_ALLOWED",
    "message": "Your IP address 203.0.113.45 is not whitelisted for this PRODUCTION API key. Add your IP to the whitelist at  https://app.oneclickdz.com/#/settings"
  },
  "requestId": "req_abc123"
}
تتضمن استجابة الخطأ عنوان IP الحالي والبيئة (SANDBOX أو PRODUCTION) لمساعدتك في تحديد أي قائمة بيضاء تحتاج إلى تحديث.

403 - IP محظور

{
  "success": false,
  "error": {
    "code": "IP_BLOCKED",
    "message": "Your IP has been temporarily blocked due to too many invalid attempts"
  },
  "requestId": "req_abc123"
}

أفضل ممارسات الأمان

  • لا تلتزم أبداً بمفاتيح API في نظام إدارة الإصدارات
  • استخدم متغيرات البيئة أو أنظمة إدارة الأسرار
  • دوِّر المفاتيح بشكل دوري
  • استخدم مفاتيح مختلفة لبيئات مختلفة
  • استخدم دائماً endpoints بروتوكول HTTPS
  • لا ترسل مفاتيح API عبر HTTP أبداً
  • تحقق من شهادات SSL
  • أضف فقط عناوين IP الضرورية
  • استخدم عناوين IP محددة بدلاً من نطاقات واسعة
  • حدّث القائمة البيضاء عند تغيير البنية التحتية
  • تتبع استخدام مفاتيح API بانتظام
  • أعدّ تنبيهات للأنشطة غير المعتادة
  • راجع سجلات الوصول
  • أبطِل المفاتيح المخترقة فوراً
  • استخدم مفاتيح للقراءة فقط حيثما أمكن
  • أنشئ مفاتيح منفصلة لخدمات مختلفة
  • طبّق مبدأ الحد الأدنى من الامتيازات

تدوير المفاتيح

يُنصح بتدوير مفاتيح API بشكل دوري:
1

إنشاء مفتاح جديد

أنشئ مفتاح API جديداً من لوحة التحكم
2

تحديث التطبيق

انشر تطبيقك بالمفتاح الجديد
3

التحقق

اختبر أن المفتاح الجديد يعمل بشكل صحيح
4

إبطال المفتاح القديم

بعد التحقق، أبطِل المفتاح القديم من لوحة التحكم
دوِّر المفاتيح كل 90 يوماً على الأقل لأمان مُعزَّز.

هل تحتاج مساعدة؟

إذا كنت تواجه مشاكل في المصادقة:
  1. تحقق من صحة مفتاح API
  2. تأكد من استخدام اسم الرأس الصحيح (X-Access-Token)
  3. تأكد من أن عنوان IP الخاص بك في القائمة البيضاء (إذا كانت مفعّلة)
  4. تحقق من حالة API على status.oneclickdz.com
  5. تواصل مع الدعم على [email protected]