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

# تقديم طلب

> اشترِ بطاقات هدايا أو منتجات رقمية

<div dir="rtl">
  ## نظرة عامة

  أنشئ طلبات لبطاقات الهدايا والمنتجات الرقمية. تُسلَّم البطاقات رقمياً عبر endpoint الـ `/checkOrder`.

  <Note>
    **قبل الطلب:** تحقق من المخزون عبر `/checkProduct` وتحقق من رصيد الحساب.
  </Note>

  ## جسم الطلب

  <ParamField body="productId" type="string" required>
    معرف المنتج من `/catalog`
  </ParamField>

  <ParamField body="typeId" type="string" required>
    معرف النوع من `/checkProduct`
  </ParamField>

  <ParamField body="quantity" type="integer" required>
    عدد البطاقات للطلب (الحد الأدنى: 1)
  </ParamField>

  ## أمثلة

  <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": "507f1f77bcf86cd799439011",
        "typeId": "type_001",
        "quantity": 2
      }'
    ```

    ```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: "507f1f77bcf86cd799439011",
          typeId: "type_001",
          quantity: 2,
        }),
      }
    );
    const { data } = await response.json();
    console.log("Order ID:", data.orderId);
    ```

    ```python Python theme={null}
    response = requests.post(
        'https://api.oneclickdz.com/v3/gift-cards/placeOrder',
        headers={
            'Content-Type': 'application/json',
            'X-Access-Token': 'YOUR_API_KEY'
        },
        json={
            'productId': '507f1f77bcf86cd799439011',
            'typeId': 'type_001',
            'quantity': 2
        }
    )
    order_id = response.json()['data']['orderId']
    ```

    ```php PHP theme={null}
    <?php
    $data = [
        'productId' => '507f1f77bcf86cd799439011',
        'typeId' => 'type_001',
        'quantity' => 2
    ];

    $ch = curl_init('https://api.oneclickdz.com/v3/gift-cards/placeOrder');
    curl_setopt($ch, CURLOPT_POST, true);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'Content-Type: application/json',
        'X-Access-Token: YOUR_API_KEY'
    ]);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
    $response = json_decode(curl_exec($ch), true);
    $orderId = $response['data']['orderId'];
    ?>
    ```
  </CodeGroup>

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

  ```json theme={null}
  {
    "success": true,
    "data": {
      "orderId": "6901616fe9e88196b4eb64b3"
    },
    "meta": {
      "timestamp": "2025-10-29T01:00:00.000Z"
    },
    "requestId": "req_1730163600_abc123"
  }
  ```

  ## قائمة التحقق قبل الطلب

  <Steps>
    <Step title="التحقق من المخزون">
      ```javascript theme={null}
      const product = await checkProduct(productId);
      const type = product.types.find(t => t.id === typeId);
      if (!type || type.quantity < quantity) {
        throw new Error('Insufficient stock');
      }
      ```
    </Step>

    <Step title="التحقق من الرصيد">
      ```javascript theme={null}
      const balance = await getBalance();
      const totalCost = type.price * quantity;
      if (balance < totalCost) {
        throw new Error('Insufficient balance');
      }
      ```
    </Step>

    <Step title="تقديم الطلب">
      ```javascript theme={null}
      const order = await placeOrder({ productId, typeId, quantity });
      ```
    </Step>

    <Step title="الاستعلام عن البطاقات">
      ```javascript theme={null}
      const result = await pollOrder(order.orderId);
      ```
    </Step>
  </Steps>

  ## ردود الخطأ

  <AccordionGroup>
    <Accordion title="ERR_VALIDATION">معاملات طلب غير صالحة</Accordion>
    <Accordion title="ERR_STOCK">المنتج نفد من المخزون</Accordion>
    <Accordion title="INSUFFICIENT_BALANCE">رصيد غير كافٍ</Accordion>
  </AccordionGroup>

  ## المعالجة

  <Warning>الطلبات **نهائية بمجرد تقديمها**. احفظ `orderId` فوراً.</Warning>

  تُعالَج معظم الطلبات في غضون ثوانٍ. استعلم عن `/checkOrder/:orderId` كل 5 إلى 10 ثوانٍ حتى تصبح الحالة `FULFILLED` أو `REFUNDED`.

  ## روابط ذات صلة

  <CardGroup cols={2}>
    <Card title="التحقق من الطلب" icon="magnifying-glass" href="/ar/api-reference/gift-cards/check-order">
      الحصول على البطاقات عند الاكتمال
    </Card>

    <Card title="التحقق من المنتج" icon="box" href="/ar/api-reference/gift-cards/check-product">
      التحقق من المخزون أولاً
    </Card>
  </CardGroup>
</div>