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

# البدء السريع

> أرسل أول شحنة في أقل من 5 دقائق

<div dir="rtl">
  ## الحصول على مفتاح API

  <Steps>
    <Step title="إنشاء حساب">
      أنشئ حساباً مجانياً على [app.oneclickdz.com](https://app.oneclickdz.com/)
    </Step>

    <Step title="إنشاء مفاتيح API">
      انتقل إلى [الإعدادات](https://enterprise.oneclickdz.com/api-keys) ← قسم API ← إنشاء مفتاح API

      ستحصل على مفتاحين:

      * **Sandbox**: للاختبار دون معاملات حقيقية
      * **Production**: للمعاملات الفعلية
    </Step>

    <Step title="تأمين مفاتيحك">
      خزّن المفاتيح بشكل آمن في متغيرات البيئة. لا تعرضها أبداً في الكود من جانب العميل أو في نظام إدارة الإصدارات.
    </Step>
  </Steps>

  <Warning>
    ابدأ دائماً بوضع **Sandbox** لاختبار التكامل بأمان.
  </Warning>

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

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

  <CodeGroup>
    ```bash cURL theme={null}
    curl https://api.oneclickdz.com/v3/validate \
      -H "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": "YOUR_API_KEY" },
    });
    const data = await response.json();
    console.log(data);
    ```

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

    response = requests.get(
        "https://api.oneclickdz.com/v3/validate",
        headers={"X-Access-Token": "YOUR_API_KEY"}
    )
    print(response.json())
    ```

    ```php PHP theme={null}
    <?php
    $ch = curl_init("https://api.oneclickdz.com/v3/validate");
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, ["X-Access-Token: YOUR_API_KEY"]);
    $response = curl_exec($ch);
    echo $response;
    ?>
    ```
  </CodeGroup>

  **الاستجابة:**

  ```json theme={null}
  {
    "success": true,
    "data": {
      "username": "+213665983439",
      "apiKey": {
        "type": "SANDBOX",
        "scope": "READ-WRITE",
        "isEnabled": true
      }
    }
  }
  ```

  <Check>إذا رأيت `"success": true`، فمفتاح API الخاص بك يعمل بشكل صحيح!</Check>

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

  أرسل شحنة بقيمة 500 دج إلى رقم Djezzy:

  <CodeGroup>
    ```bash cURL theme={null}
    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"
      }'
    ```

    ```javascript Node.js theme={null}
    const response = await fetch("https://api.oneclickdz.com/v3/mobile/send", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "X-Access-Token": "YOUR_API_KEY",
      },
      body: JSON.stringify({
        plan_code: "PREPAID_DJEZZY",
        MSSIDN: "0778037340",
        amount: 500,
        ref: "order-001",
      }),
    });
    const data = await response.json();
    ```

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

    response = requests.post(
        'https://api.oneclickdz.com/v3/mobile/send',
        headers={
            'Content-Type': 'application/json',
            'X-Access-Token': 'YOUR_API_KEY'
        },
        json={
            'plan_code': 'PREPAID_DJEZZY',
            'MSSIDN': '0778037340',
            'amount': 500,
            'ref': 'order-001'
        }
    )
    print(response.json())
    ```

    ```php PHP theme={null}
    <?php
    $ch = curl_init("https://api.oneclickdz.com/v3/mobile/send");
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        "Content-Type: application/json",
        "X-Access-Token: YOUR_API_KEY"
    ]);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
        'plan_code' => 'PREPAID_DJEZZY',
        'MSSIDN' => '0778037340',
        'amount' => 500,
        'ref' => 'order-001'
    ]));
    $response = curl_exec($ch);
    echo $response;
    ?>
    ```
  </CodeGroup>

  **الاستجابة:**

  ```json theme={null}
  {
    "success": true,
    "data": {
      "topupId": "6901616fe9e88196b4eb64b0",
      "topupRef": "order-001"
    }
  }
  ```

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

  تحقق من حالة الشحن باستخدام المرجع:

  <CodeGroup>
    ```bash cURL theme={null}
    curl https://api.oneclickdz.com/v3/mobile/check-ref/order-001 \
      -H "X-Access-Token: YOUR_API_KEY"
    ```

    ```javascript Node.js theme={null}
    const response = await fetch(
      "https://api.oneclickdz.com/v3/mobile/check-ref/order-001",
      { headers: { "X-Access-Token": "YOUR_API_KEY" } }
    );
    const data = await response.json();
    console.log(data);
    ```

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

    response = requests.get(
        'https://api.oneclickdz.com/v3/mobile/check-ref/order-001',
        headers={'X-Access-Token': 'YOUR_API_KEY'}
    )
    print(response.json())
    ```

    ```php PHP theme={null}
    <?php
    $ch = curl_init("https://api.oneclickdz.com/v3/mobile/check-ref/order-001");
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, ["X-Access-Token: YOUR_API_KEY"]);
    $response = curl_exec($ch);
    echo $response;
    ?>
    ```
  </CodeGroup>

  **الاستجابة:**

  ```json theme={null}
  {
    "success": true,
    "data": {
      "status": "FULFILLED",
      "MSSIDN": "0778037340",
      "topup_amount": 500
    }
  }
  ```

  <Check>تسلسل الحالة: `PENDING` (5 ثواني) → `HANDLING` (15 ثانية) → `FULFILLED` ✅</Check>

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

  اشحن خطاً ADSL ببطاقة 1000 دينار:

  <CodeGroup>
    ```bash cURL theme={null}
    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"
      }'
    ```

    ```javascript Node.js theme={null}
    const response = await fetch("https://api.oneclickdz.com/v3/internet/send", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "X-Access-Token": "YOUR_API_KEY",
      },
      body: JSON.stringify({
        type: "ADSL",
        number: "036362608",
        value: 1000,
        ref: "internet-001",
      }),
    });
    const data = await response.json();
    ```

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

    response = requests.post(
        'https://api.oneclickdz.com/v3/internet/send',
        headers={
            'Content-Type': 'application/json',
            'X-Access-Token': 'YOUR_API_KEY'
        },
        json={
            'type': 'ADSL',
            'number': '036362608',
            'value': 1000,
            'ref': 'internet-001'
        }
    )
    print(response.json())
    ```

    ```php PHP theme={null}
    <?php
    $ch = curl_init("https://api.oneclickdz.com/v3/internet/send");
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        "Content-Type: application/json",
        "X-Access-Token: YOUR_API_KEY"
    ]);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
        'type' => 'ADSL',
        'number' => '036362608',
        'value' => 1000,
        'ref' => 'internet-001'
    ]));
    $response = curl_exec($ch);
    echo $response;
    ?>
    ```
  </CodeGroup>

  **الاستجابة:**

  ```json theme={null}
  {
    "success": true,
    "data": {
      "topupId": "6901616fe9e88196b4eb64b1",
      "topupRef": "internet-001"
    }
  }
  ```

  تحقق من حالة شحن الإنترنت:

  <CodeGroup>
    ```bash cURL theme={null}
    curl https://api.oneclickdz.com/v3/internet/check-ref/internet-001 \
      -H "X-Access-Token: YOUR_API_KEY"
    ```

    ```javascript Node.js theme={null}
    const response = await fetch(
      "https://api.oneclickdz.com/v3/internet/check-ref/internet-001",
      { headers: { "X-Access-Token": "YOUR_API_KEY" } }
    );
    const data = await response.json();
    console.log(data);
    ```

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

    response = requests.get(
        'https://api.oneclickdz.com/v3/internet/check-ref/internet-001',
        headers={'X-Access-Token': 'YOUR_API_KEY'}
    )
    print(response.json())
    ```

    ```php PHP theme={null}
    <?php
    $ch = curl_init("https://api.oneclickdz.com/v3/internet/check-ref/internet-001");
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, ["X-Access-Token: YOUR_API_KEY"]);
    $response = curl_exec($ch);
    echo $response;
    ?>
    ```
  </CodeGroup>

  **الاستجابة:**

  ```json theme={null}
  {
    "success": true,
    "data": {
      "status": "FULFILLED",
      "card_code": "123456789012",
      "num_trans": "AT-2025-001"
    }
  }
  ```

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

  احصل على كتالوج المنتجات لرؤية بطاقات الهدايا المتاحة:

  <CodeGroup>
    ```bash cURL theme={null}
    curl https://api.oneclickdz.com/v3/gift-cards/catalog \
      -H "X-Access-Token: YOUR_API_KEY"
    ```

    ```javascript Node.js theme={null}
    const response = await fetch(
      "https://api.oneclickdz.com/v3/gift-cards/catalog",
      { headers: { "X-Access-Token": "YOUR_API_KEY" } }
    );
    const data = await response.json();
    console.log(data);
    ```

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

    response = requests.get(
        'https://api.oneclickdz.com/v3/gift-cards/catalog',
        headers={'X-Access-Token': 'YOUR_API_KEY'}
    )
    print(response.json())
    ```

    ```php PHP theme={null}
    <?php
    $ch = curl_init("https://api.oneclickdz.com/v3/gift-cards/catalog");
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, ["X-Access-Token: YOUR_API_KEY"]);
    $response = curl_exec($ch);
    echo $response;
    ?>
    ```
  </CodeGroup>

  اطلب بطاقة هدية:

  <CodeGroup>
    ```bash cURL theme={null}
    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
      }'
    ```

    ```javascript Node.js theme={null}
    const response = await fetch(
      "https://api.oneclickdz.com/v3/gift-cards/placeOrder",
      {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          "X-Access-Token": "YOUR_API_KEY",
        },
        body: JSON.stringify({
          productId: "PRODUCT_ID",
          typeId: "TYPE_ID",
          quantity: 1,
        }),
      }
    );
    const data = await response.json();
    console.log(data);
    ```

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

    response = requests.post(
        'https://api.oneclickdz.com/v3/gift-cards/placeOrder',
        headers={
            'Content-Type': 'application/json',
            'X-Access-Token': 'YOUR_API_KEY'
        },
        json={
            'productId': 'PRODUCT_ID',
            'typeId': 'TYPE_ID',
            'quantity': 1
        }
    )
    print(response.json())
    ```

    ```php PHP theme={null}
    <?php
    $ch = curl_init("https://api.oneclickdz.com/v3/gift-cards/placeOrder");
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        "Content-Type: application/json",
        "X-Access-Token: YOUR_API_KEY"
    ]);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
        'productId' => 'PRODUCT_ID',
        'typeId' => 'TYPE_ID',
        'quantity' => 1
    ]));
    $response = curl_exec($ch);
    echo $response;
    ?>
    ```
  </CodeGroup>

  **الاستجابة:**

  ```json theme={null}
  {
    "success": true,
    "data": {
      "orderId": "6901616fe9e88196b4eb64c0"
    }
  }
  ```

  احصل على أكواد بطاقات الهدايا بالتحقق من حالة الطلب:

  <CodeGroup>
    ```bash cURL theme={null}
    curl https://api.oneclickdz.com/v3/gift-cards/checkOrder/6901616fe9e88196b4eb64c0 \
      -H "X-Access-Token: YOUR_API_KEY"
    ```

    ```javascript Node.js theme={null}
    // Poll order status until fulfilled
    async function getGiftCardCodes(orderId) {
      let status = 'HANDLING';
      
      while (status === 'HANDLING') {
        const response = await fetch(
          `https://api.oneclickdz.com/v3/gift-cards/checkOrder/${orderId}`,
          { headers: { "X-Access-Token": "YOUR_API_KEY" } }
        );
        const { data } = await response.json();
        status = data.status;
        
        if (status === 'FULFILLED') {
          return data.cards; // Array of {value, serial}
        }
        
        await new Promise(r => setTimeout(r, 5000)); // Wait 5 seconds
      }
    }

    const cards = await getGiftCardCodes('6901616fe9e88196b4eb64c0');
    console.log('Card codes:', cards);
    ```

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

    def get_gift_card_codes(order_id):
        status = 'HANDLING'
        
        while status == 'HANDLING':
            response = requests.get(
                f'https://api.oneclickdz.com/v3/gift-cards/checkOrder/{order_id}',
                headers={'X-Access-Token': 'YOUR_API_KEY'}
            )
            data = response.json()['data']
            status = data['status']
            
            if status == 'FULFILLED':
                return data['cards']  # List of {'value': ..., 'serial': ...}
            
            time.sleep(5)  # Wait 5 seconds

    cards = get_gift_card_codes('6901616fe9e88196b4eb64c0')
    print('Card codes:', cards)
    ```

    ```php PHP theme={null}
    <?php
    function getGiftCardCodes($orderId, $apiKey) {
        $status = 'HANDLING';
        
        while ($status === 'HANDLING') {
            $ch = curl_init("https://api.oneclickdz.com/v3/gift-cards/checkOrder/{$orderId}");
            curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
            curl_setopt($ch, CURLOPT_HTTPHEADER, ["X-Access-Token: {$apiKey}"]);
            $response = json_decode(curl_exec($ch), true);
            $status = $response['data']['status'];
            
            if ($status === 'FULFILLED') {
                return $response['data']['cards'];
            }
            
            sleep(5); // Wait 5 seconds
        }
    }

    $cards = getGiftCardCodes('6901616fe9e88196b4eb64c0', 'YOUR_API_KEY');
    print_r($cards);
    ?>
    ```
  </CodeGroup>

  **الاستجابة عند اكتمال الطلب:**

  ```json theme={null}
  {
    "success": true,
    "data": {
      "status": "FULFILLED",
      "cards": [
        {
          "value": "XXXX-XXXX-XXXX-XXXX",
          "serial": "123456789"
        }
      ]
    }
  }
  ```

  <Check>تُستخرج أكواد البطاقات من مصفوفة `cards` عندما تكون الحالة `FULFILLED`</Check>

  ## اختبار Sandbox

  في وضع sandbox، اختبر هذه السيناريوهات الخاصة مع شحن الهاتف:

  | رقم الهاتف                     | السلوك                               | الغرض                             |
  | ------------------------------ | ------------------------------------ | --------------------------------- |
  | أي رقم عادي (مثل `0778037340`) | نجاح: PENDING → HANDLING → FULFILLED | اختبار المعاملات الناجحة          |
  | `0600000001`                   | REFUNDED مع رسالة خطأ                | اختبار معالجة الاسترداد           |
  | `0600000002`                   | REFUNDED مع اقتراحات خطط بديلة       | اختبار عدم تطابق الخطة            |
  | `0600000003`                   | حالة UNKNOWN\_ERROR                  | اختبار معالجة الحالات غير المؤكدة |

  <Tip>
    يتضمن كل دليل سير عمل تعليمات اختبار sandbox شاملة مع أمثلة.
  </Tip>

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

  تتبع جميع استجابات API هذا الهيكل:

  ```json theme={null}
  {
    "success": true,
    "data": { ... },
    "meta": {
      "timestamp": "...",
      "pagination": { ... }
    },
    "requestId": "..."
  }
  ```

  [تعرف على تنسيق الاستجابة ←](/ar/api-reference/response-format)

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

  <CardGroup cols={2}>
    <Card title="دليل شحن الهاتف" icon="mobile" href="/ar/mobile-topup-guides/overview">
      سير عمل التكامل الكامل
    </Card>

    <Card title="دليل شحن الإنترنت" icon="wifi" href="/ar/internet-topup-guides/overview">
      ADSL و4G مع اختبار sandbox
    </Card>

    <Card title="دليل بطاقات الهدايا" icon="gift" href="/ar/gift-card-guides/overview">
      توصيل المنتجات الرقمية
    </Card>

    <Card title="معالجة الأخطاء" icon="shield" href="/ar/api-reference/error-handling">
      التعامل مع الأخطاء بشكل صحيح
    </Card>

    <Card title="المصادقة" icon="key" href="/ar/authentication">
      أنماط الوصول الآمن إلى API
    </Card>

    <Card title="أفضل الممارسات" icon="lightbulb" href="/ar/security-best-practices">
      أمان جاهز للإنتاج
    </Card>
  </CardGroup>

  <Note>
    **هل تحتاج مساعدة؟** راجع صفحة [التواصل والدعم](/ar/contact) أو راسلنا على
    [support@oneclickdz.com](mailto:support@oneclickdz.com)
  </Note>
</div>