> ## 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 في OneClickDz Flexy API v3 بنية استجابة متسقة، مما يسهّل التعامل مع الاستجابات في تطبيقك.

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

  عند نجاح الطلب، تتبع الاستجابة هذه البنية:

  ```json theme={null}
  {
    "success": true,
    "data": {
      // endpoint-specific data
    },
    "meta": {
      "timestamp": "2025-10-29T00:00:00.000Z"
      // additional metadata (pagination, etc.)
    },
    "requestId": "req_1234567890_abc123"
  }
  ```

  ### الحقول

  <ResponseField name="success" type="boolean" required>
    دائمًا `true` للاستجابات الناجحة
  </ResponseField>

  <ResponseField name="data" type="object" required>
    يحتوي على محتوى الاستجابة. تختلف البنية حسب كل endpoint.
  </ResponseField>

  <ResponseField name="meta" type="object">
    بيانات وصفية إضافية حول الاستجابة

    <Expandable title="properties">
      <ResponseField name="timestamp" type="string">
        طابع زمني بتنسيق ISO 8601 يشير إلى وقت إنشاء الاستجابة
      </ResponseField>

      <ResponseField name="pagination" type="object">
        تفاصيل التصفح بالصفحات (لـ endpoints القوائم)
      </ResponseField>
    </Expandable>
  </ResponseField>

  <ResponseField name="requestId" type="string">
    معرّف فريد لهذا الطلب. استخدمه عند التواصل مع الدعم الفني.
  </ResponseField>

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

  عند فشل الطلب، تتبع الاستجابة هذه البنية:

  ```json theme={null}
  {
    "success": false,
    "error": {
      "code": "ERROR_CODE",
      "message": "Human-readable error message",
      "details": {
        // additional error context
      }
    },
    "requestId": "req_1234567890_abc123"
  }
  ```

  ### الحقول

  <ResponseField name="success" type="boolean" required>
    دائمًا `false` لاستجابات الخطأ
  </ResponseField>

  <ResponseField name="error" type="object" required>
    يحتوي على معلومات الخطأ

    <Expandable title="properties">
      <ResponseField name="code" type="string">
        رمز الخطأ القابل للقراءة آليًا (مثل: `NO_BALANCE`، `INVALID_PHONE`)
      </ResponseField>

      <ResponseField name="message" type="string">
        وصف الخطأ القابل للقراءة البشرية
      </ResponseField>

      <ResponseField name="details" type="object">
        سياق إضافي حول الخطأ (اختياري)
      </ResponseField>
    </Expandable>
  </ResponseField>

  <ResponseField name="requestId" type="string">
    معرّف فريد لهذا الطلب. أدرجه عند الإبلاغ عن المشكلات.
  </ResponseField>

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

  ### رصيد الحساب

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

  ### إرسال شحن الهاتف المحمول

  ```json theme={null}
  {
    "success": true,
    "data": {
      "topupId": "6901616fe9e88196b4eb64b0",
      "topupRef": "my-order-123",
      "newBalance": 826.13
    },
    "meta": {
      "timestamp": "2025-10-29T00:35:59.454Z"
    }
  }
  ```

  ### قائمة المعاملات (مع التصفح بالصفحات)

  ```json theme={null}
  {
    "success": true,
    "data": {
      "items": [
        {
          "type": "FLEXY",
          "amount": 500,
          "time": "2025-10-29T00:00:00.000Z"
        }
      ],
      "pagination": {
        "page": 1,
        "pageSize": 20,
        "totalPages": 10,
        "totalResults": 195
      }
    },
    "meta": {
      "timestamp": "2025-10-29T00:35:58.852Z"
    }
  }
  ```

  ## التصفح بالصفحات

  تتضمن endpoints القوائم بيانات التصفح بالصفحات في الاستجابة:

  ```json theme={null}
  {
    "success": true,
    "data": {
      "items": [...],
      "pagination": {
        "page": 1,
        "pageSize": 20,
        "totalPages": 10,
        "totalResults": 195
      }
    }
  }
  ```

  ### حقول التصفح بالصفحات

  <ResponseField name="page" type="integer">
    رقم الصفحة الحالية (مفهرسة من 1)
  </ResponseField>

  <ResponseField name="pageSize" type="integer">
    عدد العناصر في كل صفحة
  </ResponseField>

  <ResponseField name="totalPages" type="integer">
    العدد الإجمالي للصفحات المتاحة
  </ResponseField>

  <ResponseField name="totalResults" type="integer">
    العدد الإجمالي للعناصر في جميع الصفحات
  </ResponseField>

  ### معلمات الاستعلام للتصفح بالصفحات

  تحكّم في التصفح بالصفحات باستخدام هذه المعلمات:

  | المعلمة    | النوع   | الافتراضي | الوصف                                      |
  | ---------- | ------- | --------- | ------------------------------------------ |
  | `page`     | integer | 1         | رقم الصفحة (الحد الأدنى: 1)                |
  | `pageSize` | integer | 20        | العناصر في الصفحة (الأدنى: 1، الأقصى: 100) |

  <Tip>تحقق دائمًا من `totalPages` لمعرفة متى تتوقف عن التصفح.</Tip>

  ## رموز حالة HTTP

  تستخدم API رموز حالة HTTP المعيارية:

  | رمز الحالة | المعنى                                           |
  | ---------- | ------------------------------------------------ |
  | `200`      | نجاح - اكتمل الطلب بنجاح                         |
  | `400`      | طلب غير صحيح - معلمات غير صالحة أو خطأ في التحقق |
  | `401`      | غير مصرح - مفتاح API غير صالح أو مفقود           |
  | `403`      | محظور - رصيد أو صلاحيات غير كافية                |
  | `404`      | غير موجود - المورد غير موجود                     |
  | `429`      | طلبات كثيرة جدًا - تجاوز حد المعدل               |
  | `500`      | خطأ داخلي في الخادم - حدث خطأ من جانبنا          |
  | `503`      | الخدمة غير متاحة - انقطاع مؤقت في الخدمة         |

  <Note>
    حتى لرموز الحالة غير 200، تتبع الاستجابة تنسيق الخطأ القياسي.
  </Note>

  ## معرّف الطلب (Request ID)

  تتضمن كل استجابة `requestId` فريدًا:

  ```json theme={null}
  {
    "success": true,
    "data": {...},
    "requestId": "req_1761698159_abc123xyz"
  }
  ```

  ### استخدامات Request ID

  <CardGroup cols={2}>
    <Card title="التصحيح" icon="bug">
      تتبع الطلبات عبر السجلات وتحديد المشكلات
    </Card>

    {" "}

    <Card title="الدعم الفني" icon="life-ring">
      إدراجه في تذاكر الدعم للحصول على حل أسرع
    </Card>

    {" "}

    <Card title="التدقيق" icon="clipboard-check">
      ربط الطلبات بالمعاملات
    </Card>

    <Card title="المراقبة" icon="chart-line">
      تتبع تدفق الطلبات عبر الأنظمة
    </Card>
  </CardGroup>

  <Tip>
    سجّل دائمًا `requestId` لكل استدعاء API تجريه. إنه لا يُقدّر بثمن للتصحيح.
  </Tip>

  ## نوع المحتوى

  تستخدم جميع الطلبات والاستجابات JSON:

  ### ترويسات الطلب

  ```http theme={null}
  Content-Type: application/json
  X-Access-Token: YOUR_API_KEY
  ```

  ### ترويسات الاستجابة

  ```http theme={null}
  Content-Type: application/json; charset=utf-8
  X-Request-ID: req_1761698159_abc123xyz
  X-RateLimit-Limit: 120
  X-RateLimit-Remaining: 115
  X-RateLimit-Reset: 1761698219
  ```

  ## التعامل مع الاستجابات

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

  <AccordionGroup>
    <Accordion title="تحقق دائماً من حقل success" icon="check-circle">
      ```javascript theme={null}
      const response = await fetch(url, options);
      const data = await response.json();

      if (data.success) {
        // Handle success
        console.log(data.data);
      } else {
        // Handle error
        console.error(data.error.code, data.error.message);
      }
      ```
    </Accordion>

    <Accordion title="سجّل Request IDs" icon="file-lines">
      ```javascript theme={null}
      console.log(`Request ${data.requestId}: ${data.success ? 'Success' : 'Failed'}`);

      if (!data.success) {
        console.error(`Error ${data.error.code}: ${data.error.message}`);
      }
      ```
    </Accordion>

    <Accordion title="معالجة Pagination" icon="list">
      ```javascript theme={null}
      let page = 1;
      let allItems = [];

      while (true) {
        const response = await fetch(`${url}?page=${page}&pageSize=100`);
        const data = await response.json();
        
        if (!data.success) break;
        
        allItems.push(...data.data.items);
        
        if (page >= data.data.pagination.totalPages) break;
        page++;
      }
      ```
    </Accordion>

    <Accordion title="تحليل الطوابع الزمنية" icon="clock">
      ```javascript theme={null}
      const timestamp = new Date(data.meta.timestamp);
      console.log(`Response generated at: ${timestamp.toLocaleString()}`);
      ```
    </Accordion>
  </AccordionGroup>

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

  <CardGroup cols={2}>
    <Card title="معالجة الأخطاء" icon="triangle-exclamation" href="/ar/api-reference/error-handling">
      تعلّم كيفية التعامل مع الأخطاء بفعالية
    </Card>

    <Card title="Endpoints الأساسية" icon="code" href="/ar/api-reference/core/health-check">
      استكشف جميع الـ endpoints المتاحة
    </Card>
  </CardGroup>
</div>