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

  يُرجع كائن المعاملة الكامل — العرض المرجعي لعملية اكتشاف أو دفع في خدمة دفع الفواتير. كل endpoint أخرى في خدمة دفع الفواتير إما تُرجع هذا الكائن نفسه أو تُرجع معرّفًا يشير إليه.

  ولأن الاكتشاف والدفع غير متزامنين، فإن هذه الـ endpoint هي المكان الذي تظهر فيه النتيجة الحقيقية. أما الاستجابة `200` التي تلقيتها من `discover` أو `pay` فقد أكّدت فقط أن الطلب قُبِل.

  <Note>
    المعاملة التي تعود إلى شريك آخر تُرجع `404`، لا `403`. لا تؤكد واجهة API أبدًا وجود معاملة تخص غيرك. وينطبق الأمر نفسه عبر البيئات: مفتاح Sandbox لا يمكنه قراءة معاملة إنتاج، والعكس صحيح.
  </Note>

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

  <ParamField path="transactionId" type="string" required>
    معرّف المعاملة الذي أرجعه [اكتشاف الفواتير](/ar/api-reference/bill-payment/discover-bills) أو [دفع فاتورة](/ar/api-reference/bill-payment/pay-bill).

    سلسلة سداسية عشرية من 24 حرفًا بأحرف صغيرة، مثلًا `68b2f4c1a7d3e9f204c81a55`.
  </ParamField>

  ## الاستجابة

  <ResponseField name="success" type="boolean" required>
    `true` عند العثور على المعاملة وإرجاعها.
  </ResponseField>

  <ResponseField name="data" type="object" required>
    كائن المعاملة.

    <Expandable title="properties">
      <ResponseField name="transactionId" type="string" required>
        معرّف المعاملة. موجود دائمًا.
      </ResponseField>

      <ResponseField name="ref" type="string" required>
        مرجع الإتقانية (idempotency) الذي قدّمته عند بدء عملية الاكتشاف. وهذه هي القيمة التي يبحث عنها [الحصول على المعاملة بالمرجع](/ar/api-reference/bill-payment/check-by-ref).
      </ResponseField>

      <ResponseField name="type" type="string" required>
        `discovery` ما دامت المعاملة قد بحثت عن الفواتير فقط، و`payment` بمجرد أن تقدّم دفعة مقابلها.
      </ResponseField>

      <ResponseField name="status" type="string" required>
        إحدى القيم `PENDING`، `READY`، `PROCESSING`، `SUCCESS`، `FAILED`، `REFUNDED`، `UNKNOWN`. راجع [دورة حياة الحالة](#status-lifecycle).
      </ResponseField>

      <ResponseField name="partner" type="string" required>
        إحدى القيم `ADE`، `SONELGAZ`، `SEAAL`، `AADL`، `Algérie Télécom`.
      </ResponseField>

      <ResponseField name="account" type="object" required>
        الحساب الذي تخصه المعاملة، مُفهرَسًا بحقل المعرّف الخاص بذلك الشريك: `reference` لـ ADE وSEAAL، و`contractNumber` لـ SONELGAZ، و`aadlNumber` لـ AADL، و`phoneNumber` لـ Algérie Télécom.
      </ResponseField>

      <ResponseField name="currency" type="string" required>
        دائمًا `DZD`.
      </ResponseField>

      <ResponseField name="createdAt" type="string" required>
        وقت إنشاء المعاملة، ISO 8601 بتوقيت UTC.
      </ResponseField>

      <ResponseField name="updatedAt" type="string" required>
        وقت آخر تغيير على المعاملة، ISO 8601 بتوقيت UTC.
      </ResponseField>

      <ResponseField name="completedAt" type="string | null" required>
        وقت توقف المعاملة عن العمل. `null` ما دامت قيد التنفيذ. تفرّع بناءً على `status`، لا على هذا الحقل أبدًا.
      </ResponseField>

      <ResponseField name="bills" type="array">
        موجود **فقط عندما تكون `status` هي `READY`**. الفواتير المستحقة والقابلة للدفع. المصفوفة الفارغة تعني أنه لا يوجد ما يُدفع.

        <Expandable title="bill properties">
          <ResponseField name="billId" type="string" required>
            المعرّف الذي تُرسله إلى [دفع فاتورة](/ar/api-reference/bill-payment/pay-bill).
          </ResponseField>

          <ResponseField name="amount" type="number" required>
            المبلغ المستحق للشريك، بالدينار الجزائري، بمنزلتين عشريتين.
          </ResponseField>

          <ResponseField name="fee" type="number" required>
            رسوم خدمة OneClickDz مقابل دفع هذه الفاتورة، بالدينار الجزائري، بمنزلتين عشريتين. اقرأها من الاستجابة — ولا تُعِد حسابها أبدًا.
          </ResponseField>

          <ResponseField name="label" type="string">
            وصف مقروء للبشر، حين يقدّمه الشريك.
          </ResponseField>

          <ResponseField name="period" type="string">
            فترة الفوترة، حين يقدّمها الشريك.
          </ResponseField>
        </Expandable>
      </ResponseField>

      <ResponseField name="selectedBill" type="object">
        موجود بمجرد اختيار فاتورة للدفع. له بنية عنصر `bills[]` نفسها، وهو الفاتورة التي خُصم مبلغها فعليًا.
      </ResponseField>

      <ResponseField name="total" type="number">
        موجود مع `selectedBill`. `amount + fee` — المبلغ الذي يُخصم من رصيدك.
      </ResponseField>

      <ResponseField name="receiptUrl" type="string">
        موجود **فقط عندما تكون `status` هي `SUCCESS`**. الرابط المطلق لـ[تنزيل الإيصال](/ar/api-reference/bill-payment/get-receipt).
      </ResponseField>

      <ResponseField name="operationId" type="string">
        موجود **فقط عندما تكون `status` هي `SUCCESS`**. مرجع إثبات الدفع لدى الشريك. احفظه — فهو ما يُحسم به نزاع العميل.
      </ResponseField>

      <ResponseField name="error" type="object">
        موجود **فقط عندما تكون `status` هي `FAILED` أو `REFUNDED`**.

        <Expandable title="properties">
          <ResponseField name="code" type="string" required>
            إحدى القيم `PAYMENT_DECLINED`، `PARTNER_UNAVAILABLE`، `INVALID_ACCOUNT`، `BILL_ALREADY_PAID`.
          </ResponseField>

          <ResponseField name="message" type="string" required>
            شرح موجز، آمن للتسجيل في السجلات. لا تحلّله نصيًا — تفرّع بناءً على `code`.
          </ResponseField>
        </Expandable>
      </ResponseField>
    </Expandable>
  </ResponseField>

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

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

  ## الأمثلة

  <CodeGroup>
    ```bash cURL theme={null}
    curl https://billapi.oneclickdz.com/v3/bills/transactions/68b2f4c1a7d3e9f204c81a55 \
      -H "X-Access-Token: YOUR_API_KEY"
    ```

    ```javascript Node.js theme={null}
    const transactionId = "68b2f4c1a7d3e9f204c81a55";

    const response = await fetch(
      `https://billapi.oneclickdz.com/v3/bills/transactions/${transactionId}`,
      { 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.status);
    ```

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

    transaction_id = '68b2f4c1a7d3e9f204c81a55'

    response = requests.get(
        f'https://billapi.oneclickdz.com/v3/bills/transactions/{transaction_id}',
        headers={'X-Access-Token': os.getenv('ONECLICKDZ_API_KEY')}
    )

    body = response.json()

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

    print(body['data']['status'])
    ```

    ```php PHP theme={null}
    <?php
    $transactionId = '68b2f4c1a7d3e9f204c81a55';

    $ch = curl_init("https://billapi.oneclickdz.com/v3/bills/transactions/$transactionId");
    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 $body['data']['status'];
    ?>
    ```
  </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-31T10:16:03.771Z"
    },
    "requestId": "req_9f3a1c72e0b84d51aB3xZq07"
  }
  ```

  عملية اكتشاف انتهت وعثرت على فاتورة واحدة قابلة للدفع:

  ```json theme={null}
  {
    "success": true,
    "data": {
      "transactionId": "68b2f4c1a7d3e9f204c81a55",
      "ref": "disc-inv-2026-0042",
      "type": "discovery",
      "status": "READY",
      "partner": "ADE",
      "account": {
        "reference": "0123456789012345678901234"
      },
      "bills": [
        {
          "billId": "sbx_bill_68b2f4c1a7d3e9f204c81a55_0",
          "amount": 443.39,
          "fee": 30.00,
          "label": "Facture ADE"
        }
      ],
      "currency": "DZD",
      "createdAt": "2026-08-31T10:15:32.194Z",
      "updatedAt": "2026-08-31T10:15:33.008Z",
      "completedAt": "2026-08-31T10:15:33.008Z"
    },
    "meta": {
      "timestamp": "2026-08-31T10:15:34.120Z"
    },
    "requestId": "req_9f3a1c72e0b84d51aB3xZq07"
  }
  ```

  دفعة رُفضت واستُردّت بالكامل:

  ```json theme={null}
  {
    "success": true,
    "data": {
      "transactionId": "68b2f4c1a7d3e9f204c81a55",
      "ref": "disc-inv-2026-0042",
      "type": "payment",
      "status": "REFUNDED",
      "partner": "ADE",
      "account": {
        "reference": "0123456789012340000000005"
      },
      "selectedBill": {
        "billId": "sbx_bill_68b2f4c1a7d3e9f204c81a55_0",
        "amount": 550.00,
        "fee": 30.00,
        "label": "Facture ADE"
      },
      "total": 580.00,
      "currency": "DZD",
      "error": {
        "code": "PAYMENT_DECLINED",
        "message": "The payment was declined by the bank or partner portal."
      },
      "createdAt": "2026-08-31T10:15:32.194Z",
      "updatedAt": "2026-08-31T10:15:44.310Z",
      "completedAt": "2026-08-31T10:15:44.310Z"
    },
    "meta": {
      "timestamp": "2026-08-31T10:15:46.002Z"
    },
    "requestId": "req_9f3a1c72e0b84d51aB3xZq07"
  }
  ```

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

  <AccordionGroup>
    <Accordion title="401 — رمز الوصول مفقود">
      **لم تُرسَل ترويسة `X-Access-Token`.**

      ```json theme={null}
      {
        "success": false,
        "error": {
          "code": "MISSING_ACCESS_TOKEN",
          "message": "X-Access-Token header is required."
        },
        "requestId": "req_9f3a1c72e0b84d51aB3xZq07"
      }
      ```

      **ما العمل:** أرسل مفتاح API الخاص بك في ترويسة `X-Access-Token` مع كل طلب.
    </Accordion>

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

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

      **ما العمل:** تحقق من المفتاح. لا تعد المحاولة بالقيمة نفسها — فهذا لن يُحل من تلقاء نفسه.
    </Accordion>

    <Accordion title="404 — المعاملة غير موجودة">
      **لا توجد معاملة بهذا المعرّف تعود إلى حسابك في هذه البيئة.**

      ```json theme={null}
      {
        "success": false,
        "error": {
          "code": "NOT_FOUND",
          "message": "Transaction not found."
        },
        "requestId": "req_9f3a1c72e0b84d51aB3xZq07"
      }
      ```

      **ما العمل:** تأكّد من المعرّف، وتأكّد من أنك تستخدم مفتاح البيئة التي أُنشئت فيها المعاملة. المعرّف المشوّه يُجيب أيضًا بـ `404`.
    </Accordion>

    <Accordion title="503 — المصادقة غير متاحة">
      **لم نتمكن من التحقق من مفتاحك في الوقت المحدد. هذا ليس حكمًا على مفتاحك.**

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

      **ما العمل:** انتظر عدد الثواني المذكور في ترويسة الاستجابة `Retry-After`، ثم أعد إرسال الطلب نفسه. لا تعرض هذا على عميلك أبدًا على أنه مشكلة في بيانات الاعتماد.
    </Accordion>

    <Accordion title="503 — الخدمة غير متاحة">
      **واجهة Bill Payment API في صيانة مُخطط لها. كل مسار `/v3` يُجيب بهذا.**

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

      **ما العمل:** التزم بـ `Retry-After` وأعد المحاولة. عمليات القراءة آمنة للتكرار.
    </Accordion>

    <Accordion title="500 — خطأ داخلي">
      **حدث خلل من جانبنا.**

      ```json theme={null}
      {
        "success": false,
        "error": {
          "code": "INTERNAL_ERROR",
          "message": "An unexpected error occurred."
        },
        "requestId": "req_9f3a1c72e0b84d51aB3xZq07"
      }
      ```

      **ما العمل:** أعد محاولة القراءة. إذا استمرت المشكلة، تواصل مع الدعم مع ذكر `requestId`.
    </Accordion>
  </AccordionGroup>

  ## دورة حياة الحالة

  تُنشأ المعاملة عبر `discover`، ثم تصبح قابلة للدفع، ثم تتابع الدفعة حتى تبلغ حالة نهائية.

  | الحالة       | المعنى                                                                  | نهائية  |
  | ------------ | ----------------------------------------------------------------------- | ------- |
  | `PENDING`    | مقبولة؛ الاكتشاف لم ينتهِ بعد                                           | لا      |
  | `READY`      | انتهى الاكتشاف — اقرأ `bills[]`. المصفوفة الفارغة تعني أنه لا شيء مستحق | لا      |
  | `PROCESSING` | الدفعة قيد التنفيذ                                                      | لا      |
  | `SUCCESS`    | مدفوعة. `operationId` و`receiptUrl` موجودان                             | نعم     |
  | `FAILED`     | لم تنفذ. لم تتحرك أي أموال                                              | نعم     |
  | `REFUNDED`   | تحركت الأموال ثم أُعيدت بالكامل                                         | نعم     |
  | `UNKNOWN`    | النتيجة لم تُؤكَّد بعد؛ قيد المراجعة                                    | ليس بعد |

  <Warning>
    `UNKNOWN` ليست فشلًا. لا تسترد المال لعميلك ولا تعد إرسال الدفعة أبدًا ما دامت المعاملة `UNKNOWN` — تابع الاستعلام الدوري. فهي تُحسم إلى `SUCCESS` أو `REFUNDED`.
  </Warning>

  [استراتيجية الاستعلام الدوري الكاملة →](/ar/bill-payment-guides/4-status-polling)

  ## الحقول حسب الحالة

  الحقول المؤشَّر عليها أدناه هي وحدها الموجودة. لا تفترض وجود حقل لمجرد أنك رأيته في حالة أخرى.

  | الحقل                                                                                                | `PENDING` | `READY` | `PROCESSING` | `SUCCESS` | `FAILED` | `REFUNDED` | `UNKNOWN` |
  | ---------------------------------------------------------------------------------------------------- | --------- | ------- | ------------ | --------- | -------- | ---------- | --------- |
  | `transactionId`، `ref`، `type`، `status`، `partner`، `account`، `currency`، `createdAt`، `updatedAt` | نعم       | نعم     | نعم          | نعم       | نعم      | نعم        | نعم       |
  | `completedAt`                                                                                        | `null`    | مُعيَّن | `null`       | مُعيَّن   | مُعيَّن  | مُعيَّن    | مُعيَّن   |
  | `bills`                                                                                              | —         | نعم     | —            | —         | —        | —          | —         |
  | `selectedBill`، `total`                                                                              | —         | —       | نعم          | نعم       | نعم      | نعم        | نعم       |
  | `receiptUrl`، `operationId`                                                                          | —         | —       | —            | نعم       | —        | —          | —         |
  | `error`                                                                                              | —         | —       | —            | —         | نعم      | نعم        | —         |

  يظهر `selectedBill` و`total` منذ لحظة اختيار فاتورة للدفع، ولذلك فهما غائبان عن عملية اكتشاف لم يُدفع مقابلها قط.

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

  <CardGroup cols={2}>
    <Card title="تفرّع بناءً على status" icon="code-branch">
      تعامل مع `status` بوصفها المصدر الوحيد للحقيقة بشأن النتيجة. لا تستنتجها أبدًا من `completedAt` ولا من حالة HTTP للطلب الأصلي.
    </Card>

    <Card title="احفظ operationId" icon="receipt">
      عند `SUCCESS`، احفظ `operationId` ونزّل الإيصال. فهما معًا الإثبات الذي يحتاجه نزاع العميل.
    </Card>

    <Card title="سجّل كل requestId" icon="fingerprint">
      احتفظ بـ `requestId` بجانب معرّف طلبك الخاص. فهو أسرع طريق للحصول على إجابة من الدعم.
    </Card>

    <Card title="استعلم دوريًا، لا تعد الإرسال" icon="arrows-rotate">
      المعاملة البطيئة ليست معاملة ضائعة. استعلم دوريًا عن هذه الـ endpoint بدلًا من إعادة إرسال الاكتشاف أو الدفعة.
    </Card>
  </CardGroup>

  ## Endpoints ذات الصلة

  <CardGroup cols={3}>
    <Card title="اكتشاف الفواتير" icon="magnifying-glass-dollar" href="/ar/api-reference/bill-payment/discover-bills">
      ابدأ عملية اكتشاف
    </Card>

    <Card title="دفع فاتورة" icon="money-bill-transfer" href="/ar/api-reference/bill-payment/pay-bill">
      ادفع فاتورة مكتشَفة
    </Card>

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

    <Card title="قائمة المعاملات" icon="list" href="/ar/api-reference/bill-payment/list-transactions">
      صفِّ السجل وتصفّحه
    </Card>

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

    <Card title="دليل الاستعلام الدوري عن الحالة" icon="arrows-rotate" href="/ar/bill-payment-guides/4-status-polling">
      مُستعلِم دوري بجودة الإنتاج
    </Card>
  </CardGroup>
</div>