Skip to main content

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

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

تنسيق الرأس

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

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

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

مفتاح Sandbox

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

مفتاح Production

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

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

1

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

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

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

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

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

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

الحفظ بأمان

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

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

اختبر مفتاح API باستخدام endpoint التحقق:

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

خصائص مفتاح API

يتضمن مفتاح API الخاص بك الخصائص التالية:

القائمة البيضاء لعناوين 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 مفقود

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

بعد 5 محاولات مصادقة فاشلة، سيتم حجب عنوان IP الخاص بك مؤقتاً لمدة 15 دقيقة.

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

تتضمن استجابة الخطأ عنوان IP الحالي والبيئة (SANDBOX أو PRODUCTION) لمساعدتك في تحديد أي قائمة بيضاء تحتاج إلى تحديث.

403 - IP محظور

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

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

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

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

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

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

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

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

التحقق

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

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

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

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

دفع الفواتير جزء من واجهة v3، وليس واجهة منفصلة. قواعد المفاتيح أعلاه تنطبق عليه أيضاً — وأهمها القائمة البيضاء لعناوين IP. إذا كانت قائمة بيضاء مُعدّة على مفتاحك، فإن أي استدعاء لدفع الفواتير من عنوان خارجها يُرفض بـ 403 IP_NOT_ALLOWED، والمفتاح المُعطَّلة واجهته يُرفض بـ 403 API_DISABLED.
تستخدم واجهة دفع الفواتير نفس رأس X-Access-Token على نفس المضيف، لذا فالشريك المتكامل بالفعل مع Flexy لا يحتاج إلى بيانات اعتماد جديدة ولا إلى عنوان أساسي جديد. أمران يستحقان التذكير.نقاط النهاية تقع تحت /v3/bills. https://api.oneclickdz.com/v3/bills/...، إلى جانب نقاط نهاية الهاتف والإنترنت وبطاقات الهدايا التي تستدعيها بالفعل.البيئة خاصية للمفتاح. كل مفتاح لدفع الفواتير مرتبط ببيئة واحدة بالضبط، SANDBOX أو PRODUCTION. إنها خاصية للمفتاح الذي نُصدره، وليست شيئاً مُشفَّراً في نصه.
لا تستنتج البيئة أبداً من نص المفتاح أو من بادئة فيه. البيان الموثوق الوحيد هو apiKey.type الذي يُرجعه GET /v3/validate.
تحقّق من ذلك عند بدء التشغيل وأوقِف تسلسل الإقلاع إذا لم يكن المفتاح هو الذي تتوقعه بيئة النشر — فهي أرخص حماية من شحن مفتاح إنتاج إلى بيئة اختبار، أو العكس.حالتا فشل في المصادقة يجب التمييز بينهما:

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

مرجع الـ endpoint

اختبار Sandbox

الاختبار، ثم الانتقال إلى مفتاح الإنتاج

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

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