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

  احصل على رصيد حسابك الحالي بالدينار الجزائري (DZD). يمثّل الرصيد الأموال المتاحة التي يمكن استخدامها للشحن والطلبات والخدمات الأخرى.

  <Info>
    عندما يصل رصيدك إلى حد منخفض، سيُرسَل إشعار إلى عنوان بريدك الإلكتروني
    المسجّل.
  </Info>

  ## الاستجابة

  <ResponseField name="success" type="boolean" required>
    `true` للطلبات الناجحة
  </ResponseField>

  <ResponseField name="data" type="object" required>
    <Expandable title="properties">
      <ResponseField name="balance" type="number">
        رصيد الحساب الحالي بالدينار الجزائري (DZD)
      </ResponseField>
    </Expandable>
  </ResponseField>

  <ResponseField name="meta" type="object">
    <Expandable title="properties">
      <ResponseField name="timestamp" type="string">
        طابع زمني للاستجابة (تنسيق ISO 8601)
      </ResponseField>
    </Expandable>
  </ResponseField>

  ## مثال على الطلب

  <CodeGroup>
    ```bash cURL theme={null}
    curl --request GET \
      --url https://api.oneclickdz.com/v3/account/balance \
      --header 'X-Access-Token: YOUR_API_KEY'
    ```

    ```javascript Node.js theme={null}
    const response = await fetch("https://api.oneclickdz.com/v3/account/balance", {
      headers: {
        "X-Access-Token": process.env.ONECLICKDZ_API_KEY,
      },
    });

    const data = await response.json();

    if (data.success) {
      console.log(`Balance: ${data.data.balance} DZD`);
    }
    ```

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

    response = requests.get(
        'https://api.oneclickdz.com/v3/account/balance',
        headers={'X-Access-Token': os.getenv('ONECLICKDZ_API_KEY')}
    )

    data = response.json()

    if data['success']:
        print(f"Balance: {data['data']['balance']} DZD")
    ```

    ```php PHP theme={null}
    <?php
    $ch = curl_init();

    curl_setopt($ch, CURLOPT_URL, 'https://api.oneclickdz.com/v3/account/balance');
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'X-Access-Token: ' . getenv('ONECLICKDZ_API_KEY')
    ]);

    $response = curl_exec($ch);
    curl_close($ch);

    $data = json_decode($response, true);

    if ($data['success']) {
        echo "Balance: " . $data['data']['balance'] . " DZD\n";
    }
    ?>
    ```
  </CodeGroup>

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

  ```json theme={null}
  {
    "success": true,
    "data": {
      "balance": 1326.13
    },
    "meta": {
      "timestamp": "2025-10-29T00:35:58.710Z"
    }
  }
  ```

  ## حالات الاستخدام

  <CardGroup cols={2}>
    <Card title="الفحص قبل المعاملة" icon="check-circle">
      تحقق من الأموال الكافية قبل معالجة الطلبات
    </Card>

    {" "}

    <Card title="عرض الرصيد" icon="wallet">
      اعرض الرصيد الحالي في واجهة المستخدم لتطبيقك
    </Card>

    {" "}

    <Card title="تنبيهات الرصيد المنخفض" icon="bell">
      راقب الرصيد وأرسل تنبيهًا عند انخفاضه
    </Card>

    <Card title="التقارير المالية" icon="chart-line">
      تتبع تغييرات الرصيد بمرور الوقت
    </Card>
  </CardGroup>

  ## أمثلة على التكامل

  ### التحقق قبل المعاملة

  ```javascript theme={null}
  async function canProcessTransaction(amount) {
    const response = await fetch(
      "https://api.oneclickdz.com/v3/account/balance",
      {
        headers: { "X-Access-Token": API_KEY },
      }
    );

    const data = await response.json();

    if (!data.success) {
      throw new Error("Failed to check balance");
    }

    const balance = data.data.balance;

    if (balance < amount) {
      throw new Error(
        `Insufficient balance. Required: ${amount} DZD, Available: ${balance} DZD`
      );
    }

    return true;
  }

  // Usage
  try {
    await canProcessTransaction(500);
    // Proceed with transaction
  } catch (error) {
    console.error(error.message);
  }
  ```

  ### مراقبة الرصيد

  ```javascript theme={null}
  class BalanceMonitor {
    constructor(apiKey, lowBalanceThreshold = 1000) {
      this.apiKey = apiKey;
      this.lowBalanceThreshold = lowBalanceThreshold;
      this.lastBalance = null;
    }

    async checkBalance() {
      const response = await fetch(
        "https://api.oneclickdz.com/v3/account/balance",
        {
          headers: { "X-Access-Token": this.apiKey },
        }
      );

      const data = await response.json();

      if (!data.success) {
        console.error("Failed to check balance:", data.error);
        return;
      }

      const currentBalance = data.data.balance;

      if (currentBalance < this.lowBalanceThreshold) {
        this.onLowBalance(currentBalance);
      }

      if (this.lastBalance !== null) {
        const change = currentBalance - this.lastBalance;
        if (Math.abs(change) > 100) {
          this.onBalanceChange(change, currentBalance);
        }
      }

      this.lastBalance = currentBalance;
      return currentBalance;
    }

    startMonitoring(intervalMinutes = 5) {
      this.checkBalance();
      setInterval(() => {
        this.checkBalance();
      }, intervalMinutes * 60 * 1000);
    }
  }

  // Usage
  const monitor = new BalanceMonitor(API_KEY, 1000);
  monitor.startMonitoring(5);
  ```

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

  <AccordionGroup>
    <Accordion title="الفحص قبل المعاملات" icon="shield-check">
      تحقق دائمًا من الرصيد الكافي قبل بدء المعاملات

      ```javascript theme={null}
      // ✅ Good
      const balance = await getBalance();
      if (balance >= requiredAmount) {
        await sendTopUp(...);
      }

      // ❌ Bad
      await sendTopUp(...); // Might fail with NO_BALANCE error
      ```
    </Accordion>

    <Accordion title="التخزين المؤقت الذكي" icon="database">
      خزّن الرصيد مؤقتًا لمدة 30 إلى 60 ثانية لتقليل استدعاءات API

      ```javascript theme={null}
      // Cache balance but invalidate after transactions
      const balance = await balanceCache.getBalance();
      await sendTopUp(...);
      balanceCache.invalidateCache(); // Refresh after transaction
      ```
    </Accordion>

    <Accordion title="معالجة الأخطاء بلطف" icon="triangle-exclamation">
      نفّذ معالجة أخطاء مناسبة

      ```javascript theme={null}
      async function getSafeBalance() {
        try {
          const response = await fetch('https://api.oneclickdz.com/v3/account/balance', {
            headers: { 'X-Access-Token': API_KEY }
          });
          
          const data = await response.json();
          
          if (!data.success) {
            console.error('Balance check failed:', data.error);
            return null;
          }
          
          return data.data.balance;
        } catch (error) {
          console.error('Network error:', error);
          return null;
        }
      }
      ```
    </Accordion>

    <Accordion title="مراقبة الرصيد المنخفض" icon="bell">
      إعداد تنبيهات للرصيد المنخفض

      ```javascript theme={null}
      const LOW_BALANCE_THRESHOLD = 1000;

      async function checkAndAlert() {
        const balance = await getBalance();
        
        if (balance < LOW_BALANCE_THRESHOLD) {
          await sendAlert({
            type: 'low_balance',
            balance: balance,
            message: `Balance is low: ${balance} DZD`
          });
        }
      }
      ```
    </Accordion>
  </AccordionGroup>

  ## استجابات الخطأ

  <AccordionGroup>
    <Accordion title="401 - غير مصرح">
      ```json theme={null}
      {
        "success": false,
        "error": {
          "code": "INVALID_ACCESS_TOKEN",
          "message": "The provided access token is invalid"
        },
        "requestId": "req_abc123"
      }
      ```
    </Accordion>

    <Accordion title="500 - خطأ داخلي في الخادم">
      ```json theme={null}
      {
        "success": false,
        "error": {
          "code": "INTERNAL_SERVER_ERROR",
          "message": "Developer was notified and will check shortly"
        },
        "requestId": "req_abc123"
      }
      ```
    </Accordion>
  </AccordionGroup>

  ## Endpoints ذات الصلة

  <CardGroup cols={2}>
    <Card title="قائمة المعاملات" icon="list" href="/ar/api-reference/account/list-transactions">
      عرض سجل المعاملات
    </Card>

    <Card title="إرسال شحن جوال" icon="mobile" href="/ar/api-reference/mobile/send-topup">
      إرسال شحن جوال
    </Card>
  </CardGroup>
</div>