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

​
الحصول على مفتاح API

1

إنشاء حساب

أنشئ حساباً مجانياً على app.oneclickdz.com
2

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

انتقل إلى الإعدادات ← قسم API ← إنشاء مفتاح APIستحصل على مفتاحين:
  • Sandbox: للاختبار دون معاملات حقيقية
  • Production: للمعاملات الفعلية
3

تأمين مفاتيحك

خزّن المفاتيح بشكل آمن في متغيرات البيئة. لا تعرضها أبداً في الكود من جانب العميل أو في نظام إدارة الإصدارات.
ابدأ دائماً بوضع Sandbox لاختبار التكامل بأمان.

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

اختبر مفتاح API باستخدام endpoint التحقق:
curl https://api.oneclickdz.com/v3/validate \
  -H "X-Access-Token: YOUR_API_KEY"
الاستجابة:
{
  "success": true,
  "data": {
    "username": "+213665983439",
    "apiKey": {
      "type": "SANDBOX",
      "scope": "READ-WRITE",
      "isEnabled": true
    }
  }
}
إذا رأيت "success": true، فمفتاح API الخاص بك يعمل بشكل صحيح!

​
الخطوة 1: إرسال شحن هاتف

أرسل شحنة بقيمة 500 دج إلى رقم Djezzy:
curl https://api.oneclickdz.com/v3/mobile/send \
  -X POST \
  -H "Content-Type: application/json" \
  -H "X-Access-Token: YOUR_API_KEY" \
  -d '{
    "plan_code": "PREPAID_DJEZZY",
    "MSSIDN": "0778037340",
    "amount": 500,
    "ref": "order-001"
  }'
الاستجابة:
{
  "success": true,
  "data": {
    "topupId": "6901616fe9e88196b4eb64b0",
    "topupRef": "order-001"
  }
}

​
الخطوة 2: التحقق من حالة الشحن

تحقق من حالة الشحن باستخدام المرجع:
curl https://api.oneclickdz.com/v3/mobile/check-ref/order-001 \
  -H "X-Access-Token: YOUR_API_KEY"
الاستجابة:
{
  "success": true,
  "data": {
    "status": "FULFILLED",
    "MSSIDN": "0778037340",
    "topup_amount": 500
  }
}
تسلسل الحالة: PENDING (5 ثواني) → HANDLING (15 ثانية) → FULFILLED ✅

​
الخطوة 3: إرسال شحن إنترنت

اشحن خطاً ADSL ببطاقة 1000 دينار:
curl https://api.oneclickdz.com/v3/internet/send \
  -X POST \
  -H "Content-Type: application/json" \
  -H "X-Access-Token: YOUR_API_KEY" \
  -d '{
    "type": "ADSL",
    "number": "036362608",
    "value": 1000,
    "ref": "internet-001"
  }'
الاستجابة:
{
  "success": true,
  "data": {
    "topupId": "6901616fe9e88196b4eb64b1",
    "topupRef": "internet-001"
  }
}
تحقق من حالة شحن الإنترنت:
curl https://api.oneclickdz.com/v3/internet/check-ref/internet-001 \
  -H "X-Access-Token: YOUR_API_KEY"
الاستجابة:
{
  "success": true,
  "data": {
    "status": "FULFILLED",
    "card_code": "123456789012",
    "num_trans": "AT-2025-001"
  }
}

​
الخطوة 4: استكشاف بطاقات الهدايا

احصل على كتالوج المنتجات لرؤية بطاقات الهدايا المتاحة:
curl https://api.oneclickdz.com/v3/gift-cards/catalog \
  -H "X-Access-Token: YOUR_API_KEY"
اطلب بطاقة هدية:
curl https://api.oneclickdz.com/v3/gift-cards/placeOrder \
  -X POST \
  -H "Content-Type: application/json" \
  -H "X-Access-Token: YOUR_API_KEY" \
  -d '{
    "productId": "PRODUCT_ID",
    "typeId": "TYPE_ID",
    "quantity": 1
  }'
الاستجابة:
{
  "success": true,
  "data": {
    "orderId": "6901616fe9e88196b4eb64c0"
  }
}
احصل على أكواد بطاقات الهدايا بالتحقق من حالة الطلب:
curl https://api.oneclickdz.com/v3/gift-cards/checkOrder/6901616fe9e88196b4eb64c0 \
  -H "X-Access-Token: YOUR_API_KEY"
الاستجابة عند اكتمال الطلب:
{
  "success": true,
  "data": {
    "status": "FULFILLED",
    "cards": [
      {
        "value": "XXXX-XXXX-XXXX-XXXX",
        "serial": "123456789"
      }
    ]
  }
}
تُستخرج أكواد البطاقات من مصفوفة cards عندما تكون الحالة FULFILLED

​
اختبار Sandbox

في وضع sandbox، اختبر هذه السيناريوهات الخاصة مع شحن الهاتف:
رقم الهاتفالسلوكالغرض
أي رقم عادي (مثل 0778037340)نجاح: PENDING → HANDLING → FULFILLEDاختبار المعاملات الناجحة
0600000001REFUNDED مع رسالة خطأاختبار معالجة الاسترداد
0600000002REFUNDED مع اقتراحات خطط بديلةاختبار عدم تطابق الخطة
0600000003حالة UNKNOWN_ERRORاختبار معالجة الحالات غير المؤكدة
يتضمن كل دليل سير عمل تعليمات اختبار sandbox شاملة مع أمثلة.

​
فهم تنسيق الاستجابة

تتبع جميع استجابات API هذا الهيكل:
{
  "success": true,
  "data": { ... },
  "meta": {
    "timestamp": "...",
    "pagination": { ... }
  },
  "requestId": "..."
}
تعرف على تنسيق الاستجابة ←

​
الخطوات التالية

دليل شحن الهاتف

سير عمل التكامل الكامل

دليل شحن الإنترنت

ADSL و4G مع اختبار sandbox

دليل بطاقات الهدايا

توصيل المنتجات الرقمية

معالجة الأخطاء

التعامل مع الأخطاء بشكل صحيح

المصادقة

أنماط الوصول الآمن إلى API

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

أمان جاهز للإنتاج
هل تحتاج مساعدة؟ راجع صفحة التواصل والدعم أو راسلنا على [email protected]