> ## 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-id` لتتبع الحالة واسترجاع تفاصيل البطاقة عند التنفيذ. تكتمل معظم الطلبات في 3-45 ثانية، لكن بعضها قد يكون في حالة QUEUED لمدة 12-48 ساعة.

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

  ## مرجع API

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

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

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

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

    <Accordion title="QUEUED" icon="clock">
      **مجدول لاحقاً.** سيُعالَج الطلب خلال 12-48 ساعة. ليس فشلاً - جدوّل إعادة التحقق وأبلغ العميل.
    </Accordion>

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

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

  <CodeGroup>
    ```javascript Node.js theme={null}
    async function checkTopupStatus(topupId) {
      const response = await fetch(
        `https://api.oneclickdz.com/v3/internet/check-id/${topupId}`,
        {
          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 topupId = "6901616fe9e88196b4eb64b2";
    const order = await checkTopupStatus(topupId);

    console.log(`Status: ${order.status}`);
    console.log(`Type: ${order.type}`);

    if (order.card_code) {
      console.log(`Card Code: ${order.card_code}`);
      console.log(`Transaction: ${order.num_trans}`);
    }
    ```

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

    def check_topup_status(topup_id):
        response = requests.get(
            f'https://api.oneclickdz.com/v3/internet/check-id/{topup_id}',
            headers={'X-Access-Token': os.getenv('API_KEY')}
        )

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

    # Usage
    topup_id = '6901616fe9e88196b4eb64b2'
    order = check_topup_status(topup_id)

    print(f"Status: {order['status']}")
    if 'card_code' in order:
        print(f"Card Code: {order['card_code']}")
        print(f"Transaction: {order['num_trans']}")
    ```

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

    function checkTopupStatus($topupId) {
        $url = "https://api.oneclickdz.com/v3/internet/check-id/{$topupId}";

        $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
    $topupId = '6901616fe9e88196b4eb64b2';
    $order = checkTopupStatus($topupId);

    echo "Status: {$order['status']}\n";
    if (isset($order['card_code'])) {
        echo "Card Code: {$order['card_code']}\n";
    }
    ?>
    ```

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

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

  ### قيد المعالجة

  ```json theme={null}
  {
    "success": true,
    "data": {
      "_id": "6901616fe9e88196b4eb64b2",
      "ref": "order-123456",
      "status": "HANDLING",
      "type": "ADSL",
      "number": "036362608",
      "topup_amount": 1000,
      "created_at": "2025-11-01T12:00:00.000Z"
    }
  }
  ```

  ### منفَّذ (نجاح)

  ```json theme={null}
  {
    "success": true,
    "data": {
      "_id": "6901616fe9e88196b4eb64b2",
      "ref": "order-123456",
      "status": "FULFILLED",
      "type": "ADSL",
      "number": "036362608",
      "topup_amount": 1000,
      "card_code": "123456789012",
      "num_trans": "AT-2025-12345",
      "date_traitement": "2025-11-01T12:00:45.000Z",
      "created_at": "2025-11-01T12:00:00.000Z"
    }
  }
  ```

  ### في قائمة الانتظار

  ```json theme={null}
  {
    "success": true,
    "data": {
      "_id": "6901616fe9e88196b4eb64b2",
      "ref": "order-123456",
      "status": "QUEUED",
      "type": "ADSL",
      "number": "036362608",
      "topup_amount": 1000,
      "created_at": "2025-11-01T12:00:00.000Z"
    }
  }
  ```

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

  <CodeGroup>
    ```javascript Node.js theme={null}
    async function pollTopupUntilComplete(topupId, maxAttempts = 60) {
      const pollInterval = 5000; // 5 seconds

      for (let attempt = 1; attempt <= maxAttempts; attempt++) {
        console.log(`Polling attempt ${attempt}/${maxAttempts}`);

        const order = await checkTopupStatus(topupId);

        const finalStates = ['FULFILLED', 'REFUNDED', 'QUEUED'];
        if (finalStates.includes(order.status)) {
          return order;
        }

        if (attempt < maxAttempts) {
          await new Promise(resolve => setTimeout(resolve, pollInterval));
        }
      }

      throw new Error('Polling timeout - order still processing');
    }

    // Usage
    try {
      const order = await pollTopupUntilComplete('6901616fe9e88196b4eb64b2');

      if (order.status === 'FULFILLED') {
        console.log('✅ Card delivered:', order.card_code);
      } else if (order.status === 'QUEUED') {
        console.log('⏰ Order scheduled for later');
      } else if (order.status === 'REFUNDED') {
        console.log('❌ Order failed and refunded');
      }
    } catch (error) {
      console.error('Polling failed:', error.message);
    }
    ```

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

    def poll_topup_until_complete(topup_id, max_attempts=60):
        poll_interval = 5  # 5 seconds

        for attempt in range(1, max_attempts + 1):
            print(f"Polling attempt {attempt}/{max_attempts}")

            order = check_topup_status(topup_id)

            final_states = ['FULFILLED', 'REFUNDED', 'QUEUED']
            if order['status'] in final_states:
                return order

            if attempt < max_attempts:
                time.sleep(poll_interval)

        raise Exception('Polling timeout - order still processing')

    # Usage
    try:
        order = poll_topup_until_complete('6901616fe9e88196b4eb64b2')

        if order['status'] == 'FULFILLED':
            print(f"✅ Card delivered: {order['card_code']}")
        elif order['status'] == 'QUEUED':
            print('⏰ Order scheduled for later')
        elif order['status'] == 'REFUNDED':
            print('❌ Order failed and refunded')
    except Exception as e:
        print(f"Polling failed: {e}")
    ```

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

    function pollTopupUntilComplete($topupId, $maxAttempts = 60) {
        $pollInterval = 5; // 5 seconds

        for ($attempt = 1; $attempt <= $maxAttempts; $attempt++) {
            $order = checkTopupStatus($topupId);

            $finalStates = ['FULFILLED', 'REFUNDED', 'QUEUED'];
            if (in_array($order['status'], $finalStates)) {
                return $order;
            }

            if ($attempt < $maxAttempts) {
                sleep($pollInterval);
            }
        }

        throw new Exception('Polling timeout - order still processing');
    }
    ?>
    ```
  </CodeGroup>

  ## استراتيجية الاستعلام المتكيفة

  اضبط تكرار الاستعلام بناءً على الوقت المنقضي:

  ```javascript theme={null}
  async function pollTopupAdaptive(topupId, maxDuration = 5 * 60 * 1000) {
    const startTime = Date.now();
    let pollInterval = 3000; // Start with 3 seconds
    
    while (Date.now() - startTime < maxDuration) {
      const order = await checkTopupStatus(topupId);
      
      // Check for final state
      const finalStates = ['FULFILLED', 'REFUNDED', 'QUEUED'];
      if (finalStates.includes(order.status)) {
        return order;
      }
      
      // Adaptive interval: increase as time passes
      const elapsed = Date.now() - startTime;
      if (elapsed > 60000) {
        pollInterval = 10000; // 10 seconds after 1 minute
      } else if (elapsed > 30000) {
        pollInterval = 5000; // 5 seconds after 30 seconds
      }
      
      await new Promise(resolve => setTimeout(resolve, pollInterval));
    }
    
    throw new Error('Order processing timeout');
  }

  // Usage
  const order = await pollTopupAdaptive('6901616fe9e88196b4eb64b2');
  ```

  ## معالجة نتائج الطلب

  <CodeGroup>
    ```javascript Node.js theme={null}
    async function handleTopupResult(topupId, order) {
      switch (order.status) {
        case 'FULFILLED':
          console.log(`✅ Order fulfilled`);
          console.log(`Card: ${order.card_code}`);
          console.log(`Transaction: ${order.num_trans}`);
          
          // Update database
          await db.internetOrders.updateOne(
            { topupId },
            { 
              $set: { 
                status: 'FULFILLED',
                cardCode: order.card_code,
                numTrans: order.num_trans,
                dateTraitement: order.date_traitement,
                fulfilledAt: new Date()
              } 
            }
          );
          
          // Deliver card to customer
          await deliverCard(order);
          break;
        
        case 'QUEUED':
          console.log(`⏰ Order scheduled for later delivery`);
          
          // Update database
          await db.internetOrders.updateOne(
            { topupId },
            { 
              $set: { 
                status: 'SCHEDULED',
                message: 'Card will be delivered within 48 hours',
                nextCheckAt: new Date(Date.now() + 24 * 60 * 60 * 1000)
              } 
            }
          );
          
          // Schedule recheck after 24 hours
          await scheduleRecheck(topupId, 24 * 60 * 60 * 1000);
          
          // Notify customer
          await notifyCustomer(order, 
            'Your order is scheduled and will be delivered within 48 hours.'
          );
          break;
        
        case 'REFUNDED':
          console.log(`❌ Order failed and refunded`);
          
          // Update database
          await db.internetOrders.updateOne(
            { topupId },
            { 
              $set: { 
                status: 'REFUNDED',
                refundedAt: new Date()
              } 
            }
          );
          
          // Notify customer of failure
          await notifyCustomer(order, 
            'Your order could not be completed. A full refund has been issued.'
          );
          break;
      }
    }
    ```

    ```python Python theme={null}
    from datetime import datetime, timedelta

    async def handle_topup_result(topup_id, order):
        if order['status'] == 'FULFILLED':
            print('✅ Order fulfilled')
            print(f"Card: {order['card_code']}")
            print(f"Transaction: {order['num_trans']}")
            
            db.internet_orders.update_one(
                {'topupId': topup_id},
                {
                    '$set': {
                        'status': 'FULFILLED',
                        'cardCode': order['card_code'],
                        'numTrans': order['num_trans'],
                        'dateTraitement': order['date_traitement'],
                        'fulfilledAt': datetime.now()
                    }
                }
            )
            await deliver_card(order)
        
        elif order['status'] == 'QUEUED':
            print('⏰ Order scheduled for later delivery')
            
            db.internet_orders.update_one(
                {'topupId': topup_id},
                {
                    '$set': {
                        'status': 'SCHEDULED',
                        'message': 'Card will be delivered within 48 hours',
                        'nextCheckAt': datetime.now() + timedelta(hours=24)
                    }
                }
            )
            await schedule_recheck(topup_id, 24 * 60 * 60 * 1000)
            await notify_customer(order, 
                'Your order is scheduled and will be delivered within 48 hours.'
            )
        
        elif order['status'] == 'REFUNDED':
            print('❌ Order failed and refunded')
            
            db.internet_orders.update_one(
                {'topupId': topup_id},
                {'$set': {'status': 'REFUNDED', 'refundedAt': datetime.now()}}
            )
            await notify_customer(order, 
                'Your order could not be completed. A full refund has been issued.'
            )
    ```

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

    function handleTopupResult($topupId, $order) {
        switch ($order['status']) {
            case 'FULFILLED':
                error_log('✅ Order fulfilled');
                error_log("Card: {$order['card_code']}");
                error_log("Transaction: {$order['num_trans']}");
                
                updateOrderStatus($topupId, 'FULFILLED', [
                    'cardCode' => $order['card_code'],
                    'numTrans' => $order['num_trans'],
                    'dateTraitement' => $order['date_traitement'],
                    'fulfilledAt' => date('Y-m-d H:i:s')
                ]);
                deliverCard($order);
                break;
            
            case 'QUEUED':
                error_log('⏰ Order scheduled for later delivery');
                
                updateOrderStatus($topupId, 'SCHEDULED', [
                    'message' => 'Card will be delivered within 48 hours',
                    'nextCheckAt' => date('Y-m-d H:i:s', time() + 24 * 60 * 60)
                ]);
                scheduleRecheck($topupId, 24 * 60 * 60);
                notifyCustomer($order, 
                    'Your order is scheduled and will be delivered within 48 hours.'
                );
                break;
            
            case 'REFUNDED':
                error_log('❌ Order failed and refunded');
                
                updateOrderStatus($topupId, 'REFUNDED', [
                    'refundedAt' => date('Y-m-d H:i:s')
                ]);
                notifyCustomer($order, 
                    'Your order could not be completed. A full refund has been issued.'
                );
                break;
        }
    }
    ?>
    ```
  </CodeGroup>

  ## معالجة حالة QUEUED

  <Info>
    **الطلبات في حالة QUEUED ليست فشلاً!** إنها مجدولة للتسليم خلال 12-48 ساعة.
  </Info>

  ```javascript theme={null}
  async function handleTopupResult(order) {
    switch (order.status) {
      case 'FULFILLED':
        await storeCardSecurely(order._id, order);
        await deliverCardToCustomer(order._id, order);
        console.log('✅ Topup fulfilled and delivered');
        break;

      case 'QUEUED':
        await updateOrderStatus(order._id, 'QUEUED');
        await scheduleRecheck(order._id, 24 * 60 * 60 * 1000); // 24 hours
        await notifyCustomerQueued(order._id);
        console.log('⏰ Topup queued - will recheck in 24 hours');
        break;

      case 'REFUNDED':
        await updateOrderStatus(order._id, 'FAILED');
        await notifyCustomerRefunded(order._id);
        console.log('❌ Topup failed and refunded');
        break;
    }
  }
  ```

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

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

    <Card title="معالجة QUEUED بشكل صحيح" icon="calendar">
      لا تعامل QUEUED كفشل - جدوّل إعادة التحقق بعد 24 ساعة
    </Card>

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

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

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

  <CardGroup cols={3}>
    <Card title="تسليم البطاقات" icon="credit-card" href="/ar/internet-topup-guides/5-card-delivery">
      تسليم رموز البطاقات بأمان للعملاء
    </Card>

    <Card title="إرسال الشحنات" icon="satellite-dish" href="/ar/internet-topup-guides/3-sending-topups">
      تقديم طلبات مع التحقق
    </Card>

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