> ## 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 `/check-order` لتتبع حالة الطلب واسترجاع تفاصيل البطاقة عند التنفيذ. تكتمل معظم الطلبات خلال 3-45 ثانية.

  <Info>
    استعلم كل **5-10 ثوانٍ** حتى يصل الطلب إلى حالة نهائية: FULFILLED أو PARTIALLY\_FILLED أو REFUNDED.
  </Info>

  ## مرجع API

  <Card title="GET /v3/gift-cards/check-order/{orderId}" icon="magnifying-glass" href="/ar/api-reference/gift-cards/check-order">
    التوثيق الكامل للـ endpoint
  </Card>

  ## قيم حالة الطلب

  <AccordionGroup>
    <Accordion title="HANDLING" icon="spinner">
      الطلب قيد المعالجة. المدة المعتادة: 3-45 ثانية. استمر في الاستعلام كل 5-10 ثوانٍ.
    </Accordion>

    <Accordion title="FULFILLED" icon="check-circle">
      **نجاح!** تم تسليم البطاقة. تفاصيل البطاقة متاحة. سلّم للعميل فوراً.
    </Accordion>

    <Accordion title="PARTIALLY_FILLED" icon="triangle-exclamation">
      **نجاح جزئي.** تم تسليم بعض البطاقات وإلغاء الباقي. `fulfilled_quantity < quantity`. يُصدر استرداد جزئي تلقائياً.
    </Accordion>

    <Accordion title="REFUNDED" icon="rotate-left">
      **فشل.** أُلغي الطلب وأُعيد المبلغ تلقائياً. أبلغ العميل بالفشل.
    </Accordion>
  </AccordionGroup>

  ## الاختبار في بيئة Sandbox

  استخدم وضع Sandbox للاختبار دون إنفاق رصيد حقيقي:

  <CardGroup cols={2}>
    <Card title="اختبار طلب فاشل" icon="circle-xmark">
      استخدم `TEST_REFUND` كـ type ID ← يحاكي طلباً فاشلاً (حالة REFUNDED)
    </Card>

    <Card title="اختبار نجاح جزئي" icon="triangle-exclamation">
      استخدم `TEST_PARTIAL` كـ type ID ← يحاكي تسليم 50% (حالة PARTIALLY\_FILLED)
    </Card>
  </CardGroup>

  ```javascript Sandbox Example theme={null}
  // Test different scenarios without real charges
  const testScenarios = [
    {
      productId: "507f1f77bcf86cd799439011",
      typeId: "TEST_REFUND", // Will fail and refund
      quantity: 2,
    },
    {
      productId: "507f1f77bcf86cd799439011",
      typeId: "TEST_PARTIAL", // Will deliver 50% of cards
      quantity: 4,
    },
  ];

  // Place test order
  const order = await placeOrder(
    testScenarios[0].productId,
    testScenarios[0].typeId,
    testScenarios[0].quantity
  );

  // Poll for results
  const result = await pollOrderUntilComplete(order.orderId);
  console.log("Test result:", result.status);
  ```

  ## فحص الحالة الأساسي

  <CodeGroup>
    ```javascript Node.js theme={null}
    async function checkOrderStatus(orderId) {
      const response = await fetch(
        `https://api.oneclickdz.com/v3/gift-cards/check-order/${orderId}`,
        {
          headers: {
            "X-Access-Token": process.env.API_KEY,
          },
        }
      );

      if (!response.ok) {
        throw new Error(`Failed to check status: ${response.status}`);
      }

      const result = await response.json();
      return result.data;
    }

    // Usage
    const orderId = "6901616fe9e88196b4eb64b2";
    const order = await checkOrderStatus(orderId);

    console.log(`Status: ${order.status}`);
    if (order.status === 'FULFILLED') {
      console.log('Card data available:', order.cards);
    }
    ```

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

    def check_order_status(order_id):
        response = requests.get(
            f'https://api.oneclickdz.com/v3/gift-cards/check-order/{order_id}',
            headers={'X-Access-Token': os.getenv('API_KEY')}
        )

        response.raise_for_status()
        return response.json()['data']

    # Usage
    order_id = '6901616fe9e88196b4eb64b2'
    order = check_order_status(order_id)

    print(f"Status: {order['status']}")
    if order['status'] == 'FULFILLED':
        print('Card data available:', order['cards'])
    ```

    ```php PHP theme={null}
    <?php

    function checkOrderStatus($orderId) {
        $url = "https://api.oneclickdz.com/v3/gift-cards/check-order/{$orderId}";

        $ch = curl_init($url);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'X-Access-Token: ' . getenv('API_KEY')
        ]);

        $response = curl_exec($ch);
        $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        curl_close($ch);

        if ($httpCode !== 200) {
            throw new Exception("Failed to check status: " . $httpCode);
        }

        $result = json_decode($response, true);
        return $result['data'];
    }

    // Usage
    $orderId = '6901616fe9e88196b4eb64b2';
    $order = checkOrderStatus($orderId);

    echo "Status: {$order['status']}\n";
    if ($order['status'] === 'FULFILLED') {
        echo "Card data available\n";
    }
    ?>
    ```

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

  ## أمثلة على الاستجابة

  ### قيد المعالجة (HANDLING)

  ```json theme={null}
  {
    "success": true,
    "data": {
      "_id": "6901616fe9e88196b4eb64b3",
      "status": "HANDLING",
      "quantity": 2,
      "product": "507f1f77bcf86cd799439011",
      "type": "type_001",
      "time": "2025-10-29T01:00:00.000Z"
    }
  }
  ```

  ### منفَّذ (FULFILLED)

  ```json theme={null}
  {
    "success": true,
    "data": {
      "_id": "6901616fe9e88196b4eb64b3",
      "status": "FULFILLED",
      "quantity": 2,
      "fulfilled_quantity": 2,
      "fulfilled_amount": 980,
      "price_per_card": 490,
      "cards": [
        {
          "value": "XXXX-XXXX-XXXX-XXXX",
          "serial": "123456789"
        },
        {
          "value": "YYYY-YYYY-YYYY-YYYY",
          "serial": "987654321"
        }
      ],
      "time": "2025-10-29T01:00:00.000Z"
    }
  }
  ```

  ### مُنفَّذ جزئياً (PARTIALLY\_FILLED)

  ```json theme={null}
  {
    "success": true,
    "data": {
      "_id": "6901616fe9e88196b4eb64b3",
      "status": "PARTIALLY_FILLED",
      "quantity": 5,
      "fulfilled_quantity": 3,
      "fulfilled_amount": 1470,
      "price_per_card": 490,
      "cards": [
        { "value": "AAAA-AAAA-AAAA-AAAA", "serial": "111111111" },
        { "value": "BBBB-BBBB-BBBB-BBBB", "serial": "222222222" },
        { "value": "CCCC-CCCC-CCCC-CCCC", "serial": "333333333" }
      ],
      "time": "2025-10-29T01:00:00.000Z"
    }
  }
  ```

  ## حلقة الاستعلام الأساسية

  <CodeGroup>
    ```javascript Node.js theme={null}
    async function pollOrderUntilComplete(orderId, maxAttempts = 60) {
      for (let attempt = 1; attempt <= maxAttempts; attempt++) {
        console.log(`Checking order status (${attempt}/${maxAttempts})...`);

        const order = await checkOrderStatus(orderId);

        // Order is complete
        if (["FULFILLED", "PARTIALLY_FILLED", "REFUNDED"].includes(order.status)) {
          console.log(`Order completed: ${order.status}`);
          return order;
        }

        // Wait 5 seconds before next check
        if (attempt < maxAttempts) {
          await new Promise((resolve) => setTimeout(resolve, 5000));
        }
      }

      throw new Error("Order still processing after timeout");
    }

    // Usage
    try {
      const order = await pollOrderUntilComplete("6901616fe9e88196b4eb64b3");

      if (order.status === "FULFILLED") {
        console.log("Success! Cards:", order.cards);
      } else if (order.status === "PARTIALLY_FILLED") {
        console.log(
          `Partial delivery: ${order.fulfilled_quantity}/${order.quantity}`
        );
      } else {
        console.log("Order failed and refunded");
      }
    } catch (error) {
      console.error("Error:", error.message);
    }
    ```

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

    def poll_order_until_complete(order_id, max_attempts=60):
        for attempt in range(1, max_attempts + 1):
            print(f"Checking order status ({attempt}/{max_attempts})...")

            order = check_order_status(order_id)

            # Order is complete
            if order['status'] in ['FULFILLED', 'PARTIALLY_FILLED', 'REFUNDED']:
                print(f"Order completed: {order['status']}")
                return order

            # Wait 5 seconds before next check
            if attempt < max_attempts:
                time.sleep(5)

        raise Exception('Order still processing after timeout')

    # Usage
    try:
        order = poll_order_until_complete('6901616fe9e88196b4eb64b3')

        if order['status'] == 'FULFILLED':
            print(f"Success! Cards: {len(order['cards'])}")
        elif order['status'] == 'PARTIALLY_FILLED':
            print(f"Partial delivery: {order['fulfilled_quantity']}/{order['quantity']}")
        else:
            print('Order failed and refunded')
    except Exception as e:
        print(f"Error: {e}")
    ```

    ```php PHP theme={null}
    <?php

    function pollOrderUntilComplete($orderId, $apiKey, $maxAttempts = 60) {
        for ($attempt = 1; $attempt <= $maxAttempts; $attempt++) {
            echo "Checking order status ({$attempt}/{$maxAttempts})...\n";

            $order = checkOrderStatus($orderId, $apiKey);

            // Order is complete
            $finalStates = ['FULFILLED', 'PARTIALLY_FILLED', 'REFUNDED'];
            if (in_array($order['status'], $finalStates)) {
                echo "Order completed: {$order['status']}\n";
                return $order;
            }

            // Wait 5 seconds before next check
            if ($attempt < $maxAttempts) {
                sleep(5);
            }
        }

        throw new Exception('Order still processing after timeout');
    }

    // Usage
    try {
        $order = pollOrderUntilComplete('6901616fe9e88196b4eb64b3', getenv('API_KEY'));

        if ($order['status'] === 'FULFILLED') {
            echo "Success! Cards: " . count($order['cards']) . "\n";
        } elseif ($order['status'] === 'PARTIALLY_FILLED') {
            echo "Partial delivery: {$order['fulfilled_quantity']}/{$order['quantity']}\n";
        } else {
            echo "Order failed and refunded\n";
        }
    } catch (Exception $e) {
        echo "Error: " . $e->getMessage() . "\n";
    }
    ?>
    ```
  </CodeGroup>

  ## معالجة الحالات النهائية

  <CodeGroup>
    ```javascript Node.js theme={null}
    function handleOrderResult(order) {
      switch (order.status) {
        case "FULFILLED":
          console.log(`✅ Success: ${order.fulfilled_quantity} cards delivered`);
          console.log(`Cost: ${order.fulfilled_amount} DA`);

          // Process each card
          order.cards.forEach((card, index) => {
            console.log(`Card ${index + 1}: ${card.value}`);
            // Encrypt and deliver to customer
          });
          break;

        case "PARTIALLY_FILLED":
          console.log(
            `⚠️ Partial: ${order.fulfilled_quantity}/${order.quantity} cards`
          );
          console.log(`Charged: ${order.fulfilled_amount} DA`);

          const refund =
            (order.quantity - order.fulfilled_quantity) * order.price_per_card;
          console.log(`Refunded: ${refund} DA`);

          // Deliver available cards
          order.cards.forEach((card) => {
            console.log(`Delivered: ${card.value}`);
          });
          break;

        case "REFUNDED":
          console.log("❌ Order failed - full refund issued");
          break;
      }
    }
    ```

    ```python Python theme={null}
    def handle_order_result(order):
        if order['status'] == 'FULFILLED':
            print(f"✅ Success: {order['fulfilled_quantity']} cards delivered")
            print(f"Cost: {order['fulfilled_amount']} DA")

            # Process each card
            for i, card in enumerate(order['cards']):
                print(f"Card {i + 1}: {card['value']}")
                # Encrypt and deliver to customer

        elif order['status'] == 'PARTIALLY_FILLED':
            print(f"⚠️ Partial: {order['fulfilled_quantity']}/{order['quantity']} cards")
            print(f"Charged: {order['fulfilled_amount']} DA")

            refund = (order['quantity'] - order['fulfilled_quantity']) * order['price_per_card']
            print(f"Refunded: {refund} DA")

            # Deliver available cards
            for card in order['cards']:
                print(f"Delivered: {card['value']}")

        elif order['status'] == 'REFUNDED':
            print('❌ Order failed - full refund issued')
    ```

    ```php PHP theme={null}
    <?php

    function handleOrderResult($order) {
        switch ($order['status']) {
            case 'FULFILLED':
                echo "✅ Success: {$order['fulfilled_quantity']} cards delivered\n";
                echo "Cost: {$order['fulfilled_amount']} DA\n";

                // Process each card
                foreach ($order['cards'] as $index => $card) {
                    echo "Card " . ($index + 1) . ": {$card['value']}\n";
                    // Encrypt and deliver to customer
                }
                break;

            case 'PARTIALLY_FILLED':
                echo "⚠️ Partial: {$order['fulfilled_quantity']}/{$order['quantity']} cards\n";
                echo "Charged: {$order['fulfilled_amount']} DA\n";

                $refund = ($order['quantity'] - $order['fulfilled_quantity']) * $order['price_per_card'];
                echo "Refunded: {$refund} DA\n";

                // Deliver available cards
                foreach ($order['cards'] as $card) {
                    echo "Delivered: {$card['value']}\n";
                }
                break;

            case 'REFUNDED':
                echo "❌ Order failed - full refund issued\n";
                break;
        }
    }
    ?>
    ```
  </CodeGroup>

  ## مثال على الاستعلام الكامل

  ```javascript theme={null}
  async function processOrder(productId, typeId, quantity) {
    try {
      // 1. Place order
      console.log("Placing order...");
      const order = await placeOrder(productId, typeId, quantity);
      console.log(`Order placed: ${order.orderId}`);

      // 2. Poll for completion
      console.log("Waiting for fulfillment...");
      const result = await pollOrderUntilComplete(order.orderId);

      // 3. Handle result
      handleOrderResult(result);

      return result;
    } catch (error) {
      console.error("Order processing failed:", error.message);
      throw error;
    }
  }

  // Usage
  await processOrder("507f1f77bcf86cd799439011", "type_001", 2);
  ```

  <CardGroup cols={2}>
    <Card title="الاستعلام كل 5-10 ثوانٍ" icon="clock">
      توازن بين الاستجابة وعدد طلبات API
    </Card>

    <Card title="معالجة PARTIALLY_FILLED بشكل صحيح" icon="triangle-exclamation">
      قدّم البطاقات المتاحة وأبلغ العميل بالتسليم الجزئي
    </Card>

    <Card title="تحديد حد أقصى للوقت" icon="stopwatch">
      أوقف الاستعلام بأمان بعد 5 دقائق وأبلغ العميل بالانتظار
    </Card>

    <Card title="تحديث قاعدة البيانات" icon="database">
      سجّل تغييرات الحالة وبيانات البطاقة عند كل تحديث
    </Card>
  </CardGroup>

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

  <CardGroup cols={2}>
    <Card title="استعلم كل 5 ثوانٍ" icon="clock">
      وازن بين الاستجابة وحمل API
    </Card>

    <Card title="حدّد مهلة زمنية" icon="stopwatch">
      أوقف الاستعلام بعد 5 دقائق (60 محاولة)
    </Card>

    <Card title="تعامل مع جميع الحالات" icon="list-check">
      اعالج FULFILLED وPARTIALLY\_FILLED وREFUNDED
    </Card>

    <Card title="اختبر أولاً" icon="flask">
      استخدم وضع Sandbox مع TEST\_REFUND وTEST\_PARTIAL
    </Card>
  </CardGroup>

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

  <CardGroup cols={3}>
    <Card title="التسليم الآمن" icon="shield" href="/ar/gift-card-guides/5-secure-delivery">
      تشفير وتسليم رموز البطاقات للعملاء
    </Card>

    <Card title="تقديم الطلبات" icon="cart-shopping" href="/ar/gift-card-guides/3-placing-orders">
      تقديم طلبات بطاقات الهدايا
    </Card>

    <Card title="مرجع API" icon="book" href="/ar/api-reference/gift-cards/check-order">
      التوثيق الكامل للـ endpoint
    </Card>
  </CardGroup>
</div>