> ## 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

<div dir="rtl">
  ## المصادقة بمفتاح API

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

  ### تنسيق الرأس

  ```http theme={null}
  X-Access-Token: YOUR_API_KEY
  ```

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

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

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

  <CardGroup cols={2}>
    <Card title="مفتاح Sandbox" icon="flask">
      **الغرض**: الاختبار والتطوير - لا خصم من الرصيد الحقيقي - استجابات محاكاة - أرقام اختبار خاصة متاحة - آمن للتطوير
    </Card>

    <Card title="مفتاح Production" icon="rocket">
      **الغرض**: المعاملات الفعلية - خصم من الرصيد الحقيقي - تكامل مع المشغل الفعلي - جاهز للإنتاج - استخدم بحذر
    </Card>
  </CardGroup>

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

  <Steps>
    <Step title="تسجيل الدخول إلى لوحة التحكم">
      قم بزيارة [enterprise.oneclickdz.com](https://enterprise.oneclickdz.com/api-keys) وسجّل الدخول إلى حسابك
    </Step>

    <Step title="الانتقال إلى الإعدادات">انتقل إلى الإعدادات ← تكوين API</Step>

    <Step title="إنشاء المفاتيح">
      انقر على "إنشاء مفتاح API" لبيئتي Sandbox وProduction
    </Step>

    <Step title="الحفظ بأمان">
      انسخ مفاتيحك واحفظها في مكان آمن. لن تتمكن من رؤيتها مجدداً.
    </Step>
  </Steps>

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

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

  <CodeGroup>
    ```bash cURL theme={null}
    curl --request GET \
      --url https://api.oneclickdz.com/v3/validate \
      --header 'X-Access-Token: YOUR_API_KEY'
    ```

    ```javascript Node.js theme={null}
    const response = await fetch("https://api.oneclickdz.com/v3/validate", {
      headers: {
        "X-Access-Token": process.env.ONECLICKDZ_API_KEY,
      },
    });

    const data = await response.json();

    if (data.success) {
      console.log("API key is valid!");
      console.log("Account:", data.data.username);
      console.log("Key type:", data.data.apiKey.type);
    } else {
      console.error("API key validation failed:", data.error);
    }
    ```

    ```python Python theme={null}
    import requests
    import os

    response = requests.get(
        'https://api.oneclickdz.com/v3/validate',
        headers={'X-Access-Token': os.getenv('ONECLICKDZ_API_KEY')}
    )

    data = response.json()

    if data['success']:
        print('API key is valid!')
        print(f"Account: {data['data']['username']}")
        print(f"Key type: {data['data']['apiKey']['type']}")
    else:
        print(f"API key validation failed: {data['error']}")
    ```

    ```php PHP theme={null}
    <?php
    $apiKey = getenv('ONECLICKDZ_API_KEY');
    $ch = curl_init("https://api.oneclickdz.com/v3/validate");
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, ["X-Access-Token: " . $apiKey]);
    $response = curl_exec($ch);
    $data = json_decode($response, true);

    if ($data['success']) {
        echo "API key is valid!\n";
        echo "Account: " . $data['data']['username'] . "\n";
        echo "Key type: " . $data['data']['apiKey']['type'] . "\n";
    } else {
        echo "API key validation failed: " . json_encode($data['error']) . "\n";
    }
    ?>
    ```
  </CodeGroup>

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

  ```json theme={null}
  {
    "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`  | هل المفتاح نشط              |
  | `type`       | `SANDBOX` أو `PRODUCTION`   |
  | `allowedips` | القائمة البيضاء لعناوين IP  |
  | `scope`      | `READ-WRITE` أو `READ-ONLY` |

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

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

  <Steps>
    <Step title="الانتقال إلى إعدادات API">
      انتقل إلى الإعدادات ← تكوين API في لوحة التحكم
    </Step>

    <Step title="إضافة عناوين IP">
      أدخل عناوين IP المحددة لكل بيئة: - **القائمة البيضاء لـ Production**: تتحكم في الوصول لمفتاح API الإنتاج - **القائمة البيضاء لـ Sandbox**: تتحكم في الوصول لمفتاح API sandbox - اتركها فارغة للسماح لجميع العناوين
    </Step>

    <Step title="حفظ التغييرات">
      انقر على "تحديث القائمة البيضاء" لتطبيق التغييرات
    </Step>
  </Steps>

  <Warning>
    عندما تحتوي القائمة البيضاء على عناوين، ستُسمح فقط تلك العناوين المحددة. ستُرفض الطلبات من عناوين IP أخرى بخطأ 403.
  </Warning>

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

  أضف عناوين IP محددة إلى القائمة البيضاء، واحد في كل سطر:

  * `203.0.113.45` - يسمح فقط لهذا العنوان
  * `198.51.100.23` - عنوان IP آخر محدد

  <Tip>
    اترك القائمة البيضاء فارغة للسماح لجميع عناوين IP (السلوك الافتراضي). أضف عناوين IP لتفعيل القيود.
  </Tip>

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

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

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

  وصول كامل لجميع العمليات:

  * عرض الرصيد والمعاملات
  * إرسال الشحنات
  * تقديم الطلبات
  * التحقق من الحالات

  ### READ-ONLY

  مقتصر على عمليات القراءة:

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

  <Tip>
    استخدم مفاتيح READ-ONLY للوحات التقارير أو أدوات التحليل التي لا يجب أن تعدّل البيانات.
  </Tip>

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

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

  ```json theme={null}
  {
    "success": false,
    "error": {
      "code": "MISSING_ACCESS_TOKEN",
      "message": "Access token is required"
    },
    "requestId": "req_abc123"
  }
  ```

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

  ```json theme={null}
  {
    "success": false,
    "error": {
      "code": "INVALID_ACCESS_TOKEN",
      "message": "The provided access token is invalid",
      "details": {
        "attemptsLeft": 3
      }
    },
    "requestId": "req_abc123"
  }
  ```

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

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

  ```json theme={null}
  {
    "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"
  }
  ```

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

  ### 403 - IP محظور

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

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

  <AccordionGroup>
    <Accordion title="تخزين المفاتيح بأمان" icon="lock">
      * لا تلتزم أبداً بمفاتيح API في نظام إدارة الإصدارات
      * استخدم متغيرات البيئة أو أنظمة إدارة الأسرار
      * دوِّر المفاتيح بشكل دوري
      * استخدم مفاتيح مختلفة لبيئات مختلفة
    </Accordion>

    <Accordion title="استخدام HTTPS فقط" icon="shield-halved">
      * استخدم دائماً endpoints بروتوكول HTTPS
      * لا ترسل مفاتيح API عبر HTTP أبداً
      * تحقق من شهادات SSL
    </Accordion>

    <Accordion title="تطبيق القائمة البيضاء لعناوين IP" icon="list-check">
      * أضف فقط عناوين IP الضرورية
      * استخدم عناوين IP محددة بدلاً من نطاقات واسعة
      * حدّث القائمة البيضاء عند تغيير البنية التحتية
    </Accordion>

    <Accordion title="مراقبة استخدام API" icon="chart-line">
      * تتبع استخدام مفاتيح API بانتظام
      * أعدّ تنبيهات للأنشطة غير المعتادة
      * راجع سجلات الوصول
      * أبطِل المفاتيح المخترقة فوراً
    </Accordion>

    <Accordion title="تحديد نطاق المفاتيح" icon="eye-slash">
      * استخدم مفاتيح للقراءة فقط حيثما أمكن
      * أنشئ مفاتيح منفصلة لخدمات مختلفة
      * طبّق مبدأ الحد الأدنى من الامتيازات
    </Accordion>
  </AccordionGroup>

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

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

  <Steps>
    <Step title="إنشاء مفتاح جديد">أنشئ مفتاح API جديداً من لوحة التحكم</Step>

    <Step title="تحديث التطبيق">
      انشر تطبيقك بالمفتاح الجديد
    </Step>

    <Step title="التحقق">اختبر أن المفتاح الجديد يعمل بشكل صحيح</Step>

    <Step title="إبطال المفتاح القديم">
      بعد التحقق، أبطِل المفتاح القديم من لوحة التحكم
    </Step>
  </Steps>

  <Tip>دوِّر المفاتيح كل 90 يوماً على الأقل لأمان مُعزَّز.</Tip>

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

  إذا كنت تواجه مشاكل في المصادقة:

  1. تحقق من صحة مفتاح API
  2. تأكد من استخدام اسم الرأس الصحيح (`X-Access-Token`)
  3. تأكد من أن عنوان IP الخاص بك في القائمة البيضاء (إذا كانت مفعّلة)
  4. تحقق من حالة API على [status.oneclickdz.com](https://status.oneclickdz.com)
  5. تواصل مع الدعم على [support@oneclickdz.com](mailto:support@oneclickdz.com)
</div>