> ## 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">
  ## نظرة عامة

  أفضل الممارسات للاستعلام عن الـ endpoints لتتبع حالة الطلبات بكفاءة.

  ## نمط الاستعلام الأساسي

  <CodeGroup>
    ```javascript Node.js theme={null}
    async function pollStatus(checkFunction, options = {}) {
      const {
        maxAttempts = 60,
        interval = 5000,
        finalStates = ["FULFILLED", "REFUNDED"],
      } = options;

      for (let attempt = 1; attempt <= maxAttempts; attempt++) {
        const result = await checkFunction();

        if (finalStates.includes(result.status)) {
          return result;
        }

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

      throw new Error("Polling timeout");
    }

    // Usage
    const result = await pollStatus(() => checkTopupStatus(topupId), {
      maxAttempts: 60,
      interval: 5000,
    });
    ```

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

    def poll_status(check_function, max_attempts=60, interval=5, final_states=None):
        if final_states is None:
            final_states = ["FULFILLED", "REFUNDED"]

        for attempt in range(1, max_attempts + 1):
            result = check_function()

            if result['status'] in final_states:
                return result

            if attempt < max_attempts:
                time.sleep(interval)

        raise Exception("Polling timeout")

    # Usage
    result = poll_status(lambda: check_topup_status(topup_id), max_attempts=60, interval=5)
    ```

    ```php PHP theme={null}
    <?php
    function pollStatus($checkFunction, $maxAttempts = 60, $interval = 5, $finalStates = null) {
        if ($finalStates === null) {
            $finalStates = ['FULFILLED', 'REFUNDED'];
        }

        for ($attempt = 1; $attempt <= $maxAttempts; $attempt++) {
            $result = $checkFunction();

            if (in_array($result['status'], $finalStates)) {
                return $result;
            }

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

        throw new Exception('Polling timeout');
    }

    // Usage
    $result = pollStatus(fn() => checkTopupStatus($topupId), 60, 5);
    ?>
    ```
  </CodeGroup>

  ## الاستعلام الخاص بكل خدمة

  ### شحن الهاتف المحمول (بحد أقصى 5 دقائق)

  <CodeGroup>
    ```javascript Node.js theme={null}
    async function pollMobileTopup(topupId) {
      return await pollStatus(() => checkMobileStatus(topupId), {
        maxAttempts: 60,
        interval: 5000,
        finalStates: ["FULFILLED", "REFUNDED", "UNKNOWN_ERROR"],
      });
    }
    ```

    ```python Python theme={null}
    def poll_mobile_topup(topup_id):
        return poll_status(
            lambda: check_mobile_status(topup_id),
            max_attempts=60,
            interval=5,
            final_states=['FULFILLED', 'REFUNDED', 'UNKNOWN_ERROR']
        )
    ```

    ```php PHP theme={null}
    <?php
    function pollMobileTopup($topupId) {
        return pollStatus(
            fn() => checkMobileStatus($topupId),
            60,
            5,
            ['FULFILLED', 'REFUNDED', 'UNKNOWN_ERROR']
        );
    }
    ?>
    ```
  </CodeGroup>

  ### شحن الإنترنت (بحد أقصى 5 دقائق)

  <CodeGroup>
    ```javascript Node.js theme={null}
    async function pollInternetTopup(topupId) {
      return await pollStatus(() => checkInternetStatus(topupId), {
        maxAttempts: 60,
        interval: 5000,
        finalStates: ["FULFILLED", "REFUNDED", "QUEUED"],
      });
    }
    ```

    ```python Python theme={null}
    def poll_internet_topup(topup_id):
        return poll_status(
            lambda: check_internet_status(topup_id),
            max_attempts=60,
            interval=5,
            final_states=['FULFILLED', 'REFUNDED', 'QUEUED']
        )
    ```

    ```php PHP theme={null}
    <?php
    function pollInternetTopup($topupId) {
        return pollStatus(
            fn() => checkInternetStatus($topupId),
            60,
            5,
            ['FULFILLED', 'REFUNDED', 'QUEUED']
        );
    }
    ?>
    ```
  </CodeGroup>

  ### بطاقات الهدايا (بحد أقصى 10 دقائق)

  <CodeGroup>
    ```javascript Node.js theme={null}
    async function pollGiftCardOrder(orderId) {
      return await pollStatus(() => checkGiftCardOrder(orderId), {
        maxAttempts: 120,
        interval: 5000,
        finalStates: ["FULFILLED", "PARTIALLY_FILLED", "REFUNDED"],
      });
    }
    ```

    ```python Python theme={null}
    def poll_gift_card_order(order_id):
        return poll_status(
            lambda: check_gift_card_order(order_id),
            max_attempts=120,
            interval=5,
            final_states=['FULFILLED', 'PARTIALLY_FILLED', 'REFUNDED']
        )
    ```

    ```php PHP theme={null}
    <?php
    function pollGiftCardOrder($orderId) {
        return pollStatus(
            fn() => checkGiftCardOrder($orderId),
            120,
            5,
            ['FULFILLED', 'PARTIALLY_FILLED', 'REFUNDED']
        );
    }
    ?>
    ```
  </CodeGroup>

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

  <CardGroup cols={2}>
    <Card title="تعيين المهلة الزمنية" icon="clock">
      حدِّد دائماً مدة استعلام قصوى
    </Card>

    <Card title="معالجة الأخطاء" icon="triangle-exclamation">
      التقط وتعامل مع انتهاء مهلة الاستعلام
    </Card>

    <Card title="تسجيل التقدم" icon="list-check">
      تتبع محاولات الاستعلام لأغراض التصحيح
    </Card>

    <Card title="الحالات النهائية" icon="flag-checkered">
      حدِّد حالات نهائية واضحة
    </Card>
  </CardGroup>

  ## الإعدادات الموصى بها

  | الخدمة         | الفاصل الزمني | المدة القصوى | الحالات النهائية                       |
  | -------------- | ------------- | ------------ | -------------------------------------- |
  | الجوال         | 5 ثوانٍ       | 5 دقائق      | FULFILLED, REFUNDED, UNKNOWN\_ERROR    |
  | الإنترنت       | 5 ثوانٍ       | 5 دقائق      | FULFILLED, REFUNDED, QUEUED            |
  | بطاقات الهدايا | 5 ثوانٍ       | 10 دقائق     | FULFILLED, PARTIALLY\_FILLED, REFUNDED |

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

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

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

    <Card title="Webhooks" href="/ar/webhooks">
      إشعارات الحالة في الوقت الفعلي
    </Card>

    <Card title="أفضل الممارسات" href="/ar/security-best-practices">
      أفضل ممارسات الأمان
    </Card>
  </CardGroup>
</div>