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

  يعثر على معاملة عبر `ref` الذي أرسلته عند بدء الاستكشاف. ويُرجع الكائن نفسه تمامًا الذي يُرجعه [الحصول على معاملة بالمعرّف](/ar/api-reference/bill-payment/check-by-id).

  هذا هو مسار الاسترداد. عندما تضيع استجابة بسبب انتهاء مهلة أو تعطّل أو إعادة نشر، ابحث عن `ref` — ولا تُعِد إرسال عملية الكتابة أبدًا.

  <Note>
    يكون `ref` فريدًا لكل شريك، لا على مستوى النظام كله. إذا أعدت استخدام سلسلة `ref` نفسها لشريكين مختلفين، فمرّر `partner` أيضًا حتى يكون البحث غير ملتبس.
  </Note>

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

  <ParamField query="ref" type="string" required>
    المرجع الذي قدّمته عند إنشاء الاستكشاف. 100 حرف كحد أقصى.
  </ParamField>

  <ParamField query="partner" type="string">
    اختياري. أحد القيم `ADE` أو `SONELGAZ` أو `SEAAL` أو `AADL` أو `Algérie Télécom`. يحصر البحث في ذلك المُصدِر.
  </ParamField>

  ## الاستجابة

  مطابقة لـ [الحصول على معاملة بالمعرّف](/ar/api-reference/bill-payment/check-by-id#response) — كائن المعاملة الكامل، مغلَّفًا في الغلاف القياسي. راجع تلك الصفحة للاطلاع على مرجع الحقول حقلًا بحقل، وعلى الحقول التي تظهر في كل حالة.

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

  <ResponseField name="data" type="object" required>
    كائن المعاملة. [مرجع الحقول الكامل →](/ar/api-reference/bill-payment/check-by-id#response)
  </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 -G https://billapi.oneclickdz.com/v3/bills/transactions/by-ref \
      --data-urlencode "ref=disc-inv-2026-0042" \
      --data-urlencode "partner=ADE" \
      -H "X-Access-Token: YOUR_API_KEY"
    ```

    ```javascript Node.js theme={null}
    const url = new URL(
      "https://billapi.oneclickdz.com/v3/bills/transactions/by-ref",
    );
    url.searchParams.set("ref", "disc-inv-2026-0042");
    url.searchParams.set("partner", "ADE");

    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.transactionId, body.data.status);
    ```

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

    response = requests.get(
        'https://billapi.oneclickdz.com/v3/bills/transactions/by-ref',
        headers={'X-Access-Token': os.getenv('ONECLICKDZ_API_KEY')},
        params={'ref': 'disc-inv-2026-0042', 'partner': 'ADE'}
    )

    body = response.json()

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

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

    ```php PHP theme={null}
    <?php
    $query = http_build_query([
        'ref'     => 'disc-inv-2026-0042',
        'partner' => 'ADE'
    ]);

    $ch = curl_init("https://billapi.oneclickdz.com/v3/bills/transactions/by-ref?$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 $body['data']['transactionId'] . ' ' . $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"
  }
  ```

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

  <AccordionGroup>
    <Accordion title="400 — خطأ في التحقق">
      **كان `ref` مفقودًا أو أطول من اللازم، أو لم تكن `partner` قيمة معروفة.**

      ```json theme={null}
      {
        "success": false,
        "error": {
          "code": "ERR_VALIDATION",
          "message": "ref is required."
        },
        "requestId": "req_9f3a1c72e0b84d51aB3xZq07"
      }
      ```

      **ما العمل:** أرسل `ref` كمعلمة استعلام، مُرمَّزة لعناوين URL، وبطول 100 حرف كحد أقصى.
    </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="404 — لم يُعثر على المعاملة">
      **لا توجد معاملة بذلك `ref` تخصّ حسابك في هذه البيئة.**

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

      **ما العمل:** بعد فشل عملية كتابة، يكون `404` هنا هو الدليل على أن الطلب لم يصل أبدًا — ومن الآمن إرساله مرة أخرى بـ `ref` نفسه. وتحقّق أيضًا من أنك تستخدم مفتاح البيئة التي أُنشئت فيها المعاملة.
    </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` (5 ثوانٍ) وأعد المحاولة. تكرار البحث آمن دائمًا.
    </Accordion>
  </AccordionGroup>

  ## الاسترداد من استجابة ضائعة

  النمط نفسه للاستكشاف وللدفع: إذا فشلت عملية الكتابة بطريقة لا تستطيع تفسيرها، فاسأل عمّا يشير إليه `ref` قبل أن ترسل أي شيء مرة أخرى.

  ```javascript theme={null}
  async function resolveRef(ref, partner) {
    const url = new URL(
      "https://billapi.oneclickdz.com/v3/bills/transactions/by-ref",
    );
    url.searchParams.set("ref", ref);
    if (partner) url.searchParams.set("partner", partner);

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

    const body = await response.json();

    if (body.success) {
      return body.data; // The write landed. Continue from data.status.
    }

    if (body.error.code === "NOT_FOUND") {
      return null; // The write never landed. Safe to send it again.
    }

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

  <Warning>
    لا يكون `404` من هذا endpoint ذا معنى إلا عندما تسأل عن `ref` أرسلته بالتأكيد. لا تستخدمه أبدًا لتقرّر أن *عملية دفع* لم تحدث بينما الذي بحثت عنه هو `ref` الاستكشاف — فعملية الدفع تعيش على المعاملة نفسها التي يعيش عليها استكشافها، تحت `ref` الاستكشاف.
  </Warning>

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

  <CardGroup cols={2}>
    <Card title="ابحث، لا تُعِد الإرسال" icon="magnifying-glass">
      كل انتهاء مهلة وكل `DUPLICATED_REF` تُجاب هنا، لا بعملية كتابة ثانية.
    </Card>

    <Card title="مرّر الشريك" icon="building-columns">
      لا يكلّف شيئًا ويزيل أي التباس عندما توجد سلسلة `ref` نفسها لدى مُصدِرَي فواتير.
    </Card>

    <Card title="خزّن المرجع مع طلبك" icon="database">
      `ref` لا تستطيع إعادة بنائه هو معاملة لا تستطيع استردادها.
    </Card>

    <Card title="استعلم بالمعرّف بمجرد حصولك عليه" icon="id-card">
      استخدم هذا endpoint للاسترداد، ثم استعلم بـ `transactionId` — معلمة أقل يمكن أن تخطئ فيها.
    </Card>
  </CardGroup>

  ## Endpoints ذات الصلة

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

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

    <Card title="استكشاف الفواتير" icon="magnifying-glass-dollar" href="/ar/api-reference/bill-payment/discover-bills">
      حيث يُنشأ `ref`
    </Card>

    <Card title="استقصاء الحالة" icon="arrows-rotate" href="/ar/bill-payment-guides/4-status-polling">
      مُستقصٍ بمستوى الإنتاج
    </Card>
  </CardGroup>
</div>