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

  يُرجع معاملات دفع الفواتير الخاصة بك، الأحدث أولًا. استخدمه للمطابقة المحاسبية، ولشاشة السجل، وللعثور على معاملة عندما تفقد معرّفها ومرجعها معًا.

  القائمة محصورة بحسابك أنت وببيئة المفتاح الذي ترسله: مفتاح Sandbox لا يرى أبدًا معاملات الإنتاج، والعكس صحيح.

  <Note>
    `data` هي **مصفوفة بسيطة** من كائنات المعاملات. أما الأعداد فتوجد في `meta`: `total` و`limit` و`offset`.
  </Note>

  ## معلمات الاستعلام

  <ParamField query="status" type="string">
    التصفية حسب الحالة. إحدى القيم `PENDING`، `READY`، `PROCESSING`، `SUCCESS`، `FAILED`، `REFUNDED`، `UNKNOWN`.
  </ParamField>

  <ParamField query="partner" type="string">
    التصفية حسب مُصدِر الفواتير. إحدى القيم `ADE`، `SONELGAZ`، `SEAAL`، `AADL`، `Algérie Télécom`.
  </ParamField>

  <ParamField query="from" type="string">
    المعاملات المنشأة في هذه اللحظة أو بعدها فقط. تاريخ أو تاريخ ووقت بتنسيق ISO 8601، مثلًا `2026-08-01` أو `2026-08-01T00:00:00Z`.
  </ParamField>

  <ParamField query="to" type="string">
    المعاملات المنشأة في هذه اللحظة أو قبلها فقط. بالتنسيق نفسه المستخدم في `from`.
  </ParamField>

  <ParamField query="limit" type="integer" default="20">
    حجم الصفحة، بين 1 و100.
  </ParamField>

  <ParamField query="offset" type="integer" default="0">
    عدد المعاملات المطلوب تخطّيها. صفر أو أكثر.
  </ParamField>

  <Warning>
    لا يوجد فلتر `ref` في هذه الـ endpoint. للعثور على معاملة بمرجعك الخاص، استخدم [الحصول على المعاملة بالمرجع](/ar/api-reference/bill-payment/check-by-ref).
  </Warning>

  ## الاستجابة

  <ResponseField name="success" type="boolean" required>
    `true` عند إرجاع الصفحة.
  </ResponseField>

  <ResponseField name="data" type="array" required>
    مصفوفة من كائنات المعاملات، الأحدث أولًا. لكل عنصر البنية نفسها الموثّقة في [الحصول على المعاملة بالمعرّف](/ar/api-reference/bill-payment/check-by-id#response) — بما في ذلك القاعدة القاضية بأن `bills` و`selectedBill` و`receiptUrl` و`operationId` و`error` تظهر فقط في الحالات التي تكون فيها ذات معنى.

    المصفوفة الفارغة تعني أنه لا توجد معاملة مطابقة.
  </ResponseField>

  <ResponseField name="meta" type="object" required>
    <Expandable title="properties">
      <ResponseField name="timestamp" type="string" required>
        وقت الاستجابة، ISO 8601 بتوقيت UTC.
      </ResponseField>

      <ResponseField name="total" type="integer" required>
        عدد المعاملات المطابقة للفلاتر إجمالًا، بصرف النظر عن `limit` و`offset`.
      </ResponseField>

      <ResponseField name="limit" type="integer" required>
        حجم الصفحة الذي طُبِّق.
      </ResponseField>

      <ResponseField name="offset" type="integer" required>
        الإزاحة التي طُبِّقت.
      </ResponseField>
    </Expandable>
  </ResponseField>

  <ResponseField name="requestId" type="string" required>
    معرّف الربط، يُرسل أيضًا في ترويسة الاستجابة `X-Request-Id`.
  </ResponseField>

  ## الأمثلة

  <CodeGroup>
    ```bash cURL theme={null}
    curl -G https://billapi.oneclickdz.com/v3/bills/transactions \
      --data-urlencode "status=SUCCESS" \
      --data-urlencode "partner=ADE" \
      --data-urlencode "from=2026-08-01" \
      --data-urlencode "to=2026-08-31" \
      --data-urlencode "limit=50" \
      -H "X-Access-Token: YOUR_API_KEY"
    ```

    ```javascript Node.js theme={null}
    const url = new URL("https://billapi.oneclickdz.com/v3/bills/transactions");
    url.searchParams.set("status", "SUCCESS");
    url.searchParams.set("partner", "ADE");
    url.searchParams.set("from", "2026-08-01");
    url.searchParams.set("to", "2026-08-31");
    url.searchParams.set("limit", "50");

    const response = await fetch(url, {
      headers: { "X-Access-Token": process.env.ONECLICKDZ_API_KEY },
    });

    const body = await response.json();

    if (!body.success) {
      throw new Error(`${body.error.code}: ${body.error.message}`);
    }

    console.log(`${body.data.length} of ${body.meta.total}`);
    ```

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

    response = requests.get(
        'https://billapi.oneclickdz.com/v3/bills/transactions',
        headers={'X-Access-Token': os.getenv('ONECLICKDZ_API_KEY')},
        params={
            'status': 'SUCCESS',
            'partner': 'ADE',
            'from': '2026-08-01',
            'to': '2026-08-31',
            'limit': 50
        }
    )

    body = response.json()

    if not body['success']:
        raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")

    print(f"{len(body['data'])} of {body['meta']['total']}")
    ```

    ```php PHP theme={null}
    <?php
    $query = http_build_query([
        'status'  => 'SUCCESS',
        'partner' => 'ADE',
        'from'    => '2026-08-01',
        'to'      => '2026-08-31',
        'limit'   => 50
    ]);

    $ch = curl_init("https://billapi.oneclickdz.com/v3/bills/transactions?$query");
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'X-Access-Token: ' . getenv('ONECLICKDZ_API_KEY')
    ]);

    $body = json_decode(curl_exec($ch), true);
    curl_close($ch);

    if (!$body['success']) {
        throw new Exception($body['error']['code'] . ': ' . $body['error']['message']);
    }

    echo count($body['data']) . ' of ' . $body['meta']['total'];
    ?>
    ```
  </CodeGroup>

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

  ```json theme={null}
  {
    "success": true,
    "data": [
      {
        "transactionId": "68b2f4c1a7d3e9f204c81a55",
        "ref": "disc-inv-2026-0042",
        "type": "payment",
        "status": "SUCCESS",
        "partner": "ADE",
        "account": { "reference": "0123456789012345678901234" },
        "selectedBill": {
          "billId": "sbx_bill_68b2f4c1a7d3e9f204c81a55_0",
          "amount": 443.39,
          "fee": 30.00,
          "label": "Facture ADE"
        },
        "total": 473.39,
        "currency": "DZD",
        "receiptUrl": "https://billapi.oneclickdz.com/v3/bills/transactions/68b2f4c1a7d3e9f204c81a55/receipt",
        "operationId": "op_7726351904",
        "createdAt": "2026-08-31T10:15:32.194Z",
        "updatedAt": "2026-08-31T10:15:41.902Z",
        "completedAt": "2026-08-31T10:15:41.902Z"
      }
    ],
    "meta": {
      "timestamp": "2026-08-31T11:02:14.508Z",
      "total": 137,
      "limit": 50,
      "offset": 0
    },
    "requestId": "req_9f3a1c72e0b84d51aB3xZq07"
  }
  ```

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

  <AccordionGroup>
    <Accordion title="400 — خطأ في التحقق">
      **قيمة فلتر غير مقبولة.**

      ```json theme={null}
      {
        "success": false,
        "error": {
          "code": "ERR_VALIDATION",
          "message": "status must be one of: PENDING, READY, PROCESSING, UNKNOWN, SUCCESS, FAILED, REFUNDED",
          "details": [
            "status must be one of: PENDING, READY, PROCESSING, UNKNOWN, SUCCESS, FAILED, REFUNDED"
          ]
        },
        "requestId": "req_9f3a1c72e0b84d51aB3xZq07"
      }
      ```

      الأسباب الشائعة: حالة أو شريك خارج المجموعة المسموح بها، أو `from` أو `to` ليس تاريخًا بتنسيق ISO 8601، أو `limit` أكبر من 100 أو أصغر من 1، أو `offset` سالب.

      **ما العمل:** صحّح سلسلة الاستعلام. القيم حساسة لحالة الأحرف.
    </Accordion>

    <Accordion title="401 — رمز وصول مفقود أو غير صالح">
      **المفتاح غائب أو مرفوض.**

      ```json theme={null}
      {
        "success": false,
        "error": {
          "code": "INVALID_ACCESS_TOKEN",
          "message": "The provided access token is invalid."
        },
        "requestId": "req_9f3a1c72e0b84d51aB3xZq07"
      }
      ```

      **ما العمل:** تحقق من المفتاح عبر [التحقق من مفتاح API](/ar/api-reference/bill-payment/validate-key).
    </Accordion>

    <Accordion title="503 — المصادقة أو الخدمة غير متاحة">
      **لم نتمكن من التحقق من مفتاحك في الوقت المحدد، أو أن واجهة API في صيانة مُخطط لها.**

      ```json theme={null}
      {
        "success": false,
        "error": {
          "code": "SERVICE_UNAVAILABLE",
          "message": "The service is temporarily unavailable. Please retry shortly."
        },
        "requestId": "req_9f3a1c72e0b84d51aB3xZq07"
      }
      ```

      **ما العمل:** التزم بترويسة `Retry-After` (5 ثوانٍ) وأعد المحاولة. تكرار عرض القائمة آمن دائمًا.
    </Accordion>
  </AccordionGroup>

  ## التصفح عبر فترة زمنية

  `meta.total` هو العدد الخاص بالفلاتر التي أرسلتها، لذا يمكنك التصفح حتى ترى كل شيء. أبقِ حجم الصفحة معتدلًا والنافذة الزمنية محدودة.

  ```javascript theme={null}
  async function* eachTransaction(filters) {
    let offset = 0;
    const limit = 100;

    for (;;) {
      const url = new URL("https://billapi.oneclickdz.com/v3/bills/transactions");
      for (const [key, value] of Object.entries(filters)) {
        url.searchParams.set(key, value);
      }
      url.searchParams.set("limit", String(limit));
      url.searchParams.set("offset", String(offset));

      const response = await fetch(url, {
        headers: { "X-Access-Token": process.env.ONECLICKDZ_API_KEY },
      });

      const body = await response.json();
      if (!body.success) throw new Error(body.error.code);

      for (const transaction of body.data) yield transaction;

      offset += body.data.length;
      if (offset >= body.meta.total || body.data.length === 0) return;
    }
  }

  // Every successful ADE payment in August
  for await (const transaction of eachTransaction({
    status: "SUCCESS",
    partner: "ADE",
    from: "2026-08-01",
    to: "2026-08-31",
  })) {
    console.log(transaction.transactionId, transaction.total);
  }
  ```

  <Note>
    تُنشأ معاملات جديدة أثناء تصفحك. لأغراض المطابقة المحاسبية، حُدّ النافذة الزمنية دائمًا بـ `from` و`to` حتى لا تكبر مجموعة النتائج من تحتك.
  </Note>

  ## ما تحتويه القائمة

  تظهر هنا عمليات الاكتشاف والدفعات معًا. ويُميّز `type` بينها:

  * `type: "discovery"` — بحث لم يُدفع مقابله. حالته `PENDING` أو `READY` أو `FAILED`.
  * `type: "payment"` — عملية اكتشاف قُدِّمت مقابلها دفعة. حالتها `PROCESSING` أو `SUCCESS` أو `FAILED` أو `REFUNDED` أو `UNKNOWN`.

  تتحول المعاملة إلى `payment` في مكانها، محتفظةً بـ `transactionId` الخاص بها وبمرجعها `ref` الأصلي.

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

  <CardGroup cols={2}>
    <Card title="حُدّ كل استعلام" icon="calendar">
      أرسل دائمًا `from` و`to` لأغراض المطابقة المحاسبية. القائمة غير المحدودة تكبر مع نمو نشاطك.
    </Card>

    <Card title="طابِق على SUCCESS وREFUNDED" icon="scale-balanced">
      هاتان الحالتان هما موضع تحرك الأموال. أما `FAILED` فلم تحرّك شيئًا أبدًا.
    </Card>

    <Card title="لا تستعلم دوريًا عن هذه الـ endpoint" icon="ban">
      لمتابعة معاملة واحدة، استعلم عنها بالمعرّف. تكرار عرض القائمة أبطأ وأثقل على الطرفين.
    </Card>

    <Card title="اقرأ meta.total" icon="list-ol">
      هو العدد الخاص بفلاترك، والوسيلة الوحيدة لمعرفة ما إذا كانت هناك صفحة أخرى.
    </Card>
  </CardGroup>

  ## Endpoints ذات الصلة

  <CardGroup cols={2}>
    <Card title="الحصول على المعاملة بالمعرّف" icon="id-card" href="/ar/api-reference/bill-payment/check-by-id">
      كائن المعاملة الكامل
    </Card>

    <Card title="الحصول على المعاملة بالمرجع" icon="tag" href="/ar/api-reference/bill-payment/check-by-ref">
      ابحث بمرجعك `ref` الخاص
    </Card>

    <Card title="تنزيل الإيصال" icon="file-arrow-down" href="/ar/api-reference/bill-payment/get-receipt">
      إثبات لمعاملة مدفوعة
    </Card>

    <Card title="الإيصالات والمطابقة المحاسبية" icon="scale-balanced" href="/ar/bill-payment-guides/5-receipts-and-reconciliation">
      روتين مطابقة يومي
    </Card>
  </CardGroup>
</div>