> ## 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">
  ## مقدمة

  يتيح لك دفع الفواتير سداد فواتير المرافق والاتصالات الجزائرية نيابةً عن عملائك. تسأل مُصدِر الفاتورة عمّا يدين به حساب ما، ثم تدفع إحدى الفواتير التي تعود إليك، وتتابعها حتى تصل إلى حالة نهائية، وتحتفظ بالإيصال.

  المنتج بأكمله خمسة استدعاءات. هذه الصفحة هي الخريطة؛ وكل خطوة أدناه ترتبط بدليل يحتوي على كود عملي بلغات cURL وNode.js وPython وPHP.

  <Note>
    يعمل دفع الفواتير على **`https://billapi.oneclickdz.com`** — وهو عنوان أساسي مختلف عن بقية المنصة. أما ترويسة المصادقة فهي نفسها التي تستخدمها بالفعل: `X-Access-Token`.
  </Note>

  ## كيف يعمل النظام

  ```mermaid theme={null}
  sequenceDiagram
      participant Customer
      participant YourApp
      participant API as Bill Payment API

      YourApp->>API: 1. GET /v3/partners
      API-->>YourApp: Availability map

      Customer->>YourApp: Enters account number
      YourApp->>API: 2. POST /v3/bills/discover
      API-->>YourApp: transactionId (PENDING)

      loop Until READY
          YourApp->>API: GET /v3/bills/transactions/{id}
          API-->>YourApp: Status
      end

      API-->>YourApp: READY + bills[]
      YourApp->>Customer: Shows amount + fee
      Customer->>YourApp: Confirms

      YourApp->>API: 3. POST /v3/bills/pay
      API-->>YourApp: PROCESSING

      loop 4. Until final
          YourApp->>API: GET /v3/bills/transactions/{id}
          API-->>YourApp: Status
      end

      API-->>YourApp: SUCCESS + operationId
      YourApp->>API: 5. GET .../receipt
      API-->>YourApp: Receipt file
      YourApp->>Customer: Confirmation + receipt
  ```

  ## الخطوات الخمس

  <Steps>
    <Step title="تحقق من توفر مُصدِر الفاتورة">
      اقرأ خريطة التوفر وأخفِ أي مُصدِر فاتورة حالته `UNAVAILABLE` قبل أن يبدأ عميلك بملء أي نموذج.

      → [الخطوة 1: الشركاء والحسابات](/ar/bill-payment-guides/1-partners-and-accounts)
    </Step>

    <Step title="استكشف ما هو مستحق">
      أرسل الشريك ومعرّف الحساب و`ref` الخاص بك. تحصل في المقابل على `transactionId`؛ وتصل الفواتير على تلك المعاملة بعد لحظة.

      → [الخطوة 2: استكشاف الفواتير](/ar/bill-payment-guides/2-discovering-bills)
    </Step>

    <Step title="ادفع فاتورة واحدة">
      اختر `billId` من `bills[]`، واعرض على عميلك `amount + fee`، ثم أرسل الدفعة بـ `ref` جديد.

      → [الخطوة 3: دفع الفواتير](/ar/bill-payment-guides/3-paying-bills)
    </Step>

    <Step title="تابع الحالة حتى تصبح نهائية">
      `SUCCESS` أو `FAILED` أو `REFUNDED`. أما `UNKNOWN` فتعني استمر في التتبع — لا تُعِد المبلغ لعميلك أبداً ولا تُعِد إرسال الدفعة ما دامت هذه الحالة قائمة.

      → [الخطوة 4: تتبع الحالة](/ar/bill-payment-guides/4-status-polling)
    </Step>

    <Step title="احفظ الإيصال وطابق الحسابات">
      نزّل الإيصال، واحفظه مع `operationId`، وطابق يومياً مع دفتر حساباتك الخاص.

      → [الخطوة 5: الإيصالات والمطابقة](/ar/bill-payment-guides/5-receipts-and-reconciliation)
    </Step>
  </Steps>

  ## ما تحتاج معرفته

  ### كل شيء غير متزامن

  يستجيب كل من `POST /v3/bills/discover` و`POST /v3/bills/pay` بالرمز `200` فوراً. وهذا الـ `200` يعني **مقبول**، لا **منتهٍ**.

  <Warning>
    الرمز `200` من `pay` لا يعني أن الفاتورة دُفعت. النتيجة الحقيقية لا تظهر إلا في `status` الخاص بالمعاملة. صمّم تكاملك حول التتبع من أول سطر كود — فتأجيل ذلك إلى وقت لاحق هو ما يجعل العملاء يُخصم منهم مرتين.
  </Warning>

  ### مُصدِرو الفواتير ومعرّفاتهم

  خمسة مُصدِري فواتير، لكل منهم حقل معرّف واحد. أرسل الحقل الذي يخص الشريك؛ وتُعيد API الحقل نفسه إليك في كل معاملة.

  | الشريك            | ما هو                            | المعرّف          |
  | ----------------- | -------------------------------- | ---------------- |
  | `ADE`             | المياه                           | `reference`      |
  | `SONELGAZ`        | الكهرباء والغاز                  | `contractNumber` |
  | `SEAAL`           | المياه — الجزائر العاصمة وتيبازة | `reference`      |
  | `AADL`            | أقساط السكن                      | `aadlNumber`     |
  | `Algérie Télécom` | الهاتف الثابت والإنترنت          | `phoneNumber`    |

  `SEAAL` و`AADL` حالياً `UNAVAILABLE` في كل من sandbox والإنتاج. اقرأ خريطة التوفر بدلاً من ترميز ذلك بشكل ثابت في الكود.

  → [قواعد المعرّفات وصيغها وأمثلتها](/ar/bill-payment-guides/1-partners-and-accounts)

  ### الحالات السبع

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

  → [آلة الحالات الكاملة ومتتبِّع حالة جاهز للإنتاج](/ar/bill-payment-guides/4-status-polling)

  ### الرسوم وعتبة 200 DZD

  كل فاتورة تحمل حقولها المالية الخاصة:

  * `amount` — ما هو مستحق لمُصدِر الفاتورة، بالـ DZD.
  * `fee` — رسوم خدمة OneClickDz: نسبة مئوية من المبلغ محصورة بين حد أدنى وحد أقصى، **تُضبط لكل مُصدِر فاتورة على حدة**:

    | مُصدِر الفاتورة   | النسبة | الحد الأدنى | الحد الأقصى |
    | ----------------- | ------ | ----------- | ----------- |
    | `ADE`             | 0.5%   | 30 DZD      | 60 DZD      |
    | `SONELGAZ`        | 0.5%   | 30 DZD      | 60 DZD      |
    | `Algérie Télécom` | 0.5%   | 10 DZD      | 50 DZD      |

    عمليًا تدفع معظم الفواتير الحد الأدنى: لا تتجاوز نسبة 0.5% مبلغ 30 DZD إلا فوق فاتورة قيمتها 6,000 DZD. هذه القيم إعدادات قابلة للتعديل، لذا اقرأ `fee` من الاستجابة بدلًا من إعادة حسابه.
  * `total` — `amount + fee`، وهو المبلغ المخصوم من رصيدك.

  الفواتير التي تقل عن **200 DZD** تُستبعد أثناء الاستكشاف ولا تظهر أبداً في `bills[]`. لذلك فإن معاملة `READY` بـ `bills[]` فارغة تعني إما "لا شيء مستحق" وإما "كل ما هو مستحق يقع دون العتبة" — وAPI لا تفرّق بينهما. أخبر عميلك "لا توجد فواتير قابلة للدفع الآن"، لا "أنت لا تدين بشيء".

  ### مرجعك هو شبكة أمانك

  `ref` مطلوب في كل من `discover` و`pay`، وطوله 100 حرف كحد أقصى، ويجب أن يكون فريداً بين معاملاتك النشطة لدى ذلك المُصدِر. إعادة استخدام أحدها تُجيب بـ `403 DUPLICATED_REF`.

  اشتقّه من شيء تخزّنه بالفعل، حتى تتمكن بعد أي انتهاء مهلة من أن تسأل [عمّا آل إليه ذلك `ref`](/ar/api-reference/bill-payment/check-by-ref) بدلاً من إرسال الطلب مرة أخرى.

  <Note>
    استخدم `ref` **مختلفاً** للاستكشاف وللدفع. تحتفظ المعاملة بـ `ref` الاستكشاف الأصلي، وهو الذي يبحث عنه `by-ref`.
  </Note>

  ### Sandbox

  يستخدم sandbox المضيف نفسه، والمسارات نفسها، والمغلّف نفسه، ودورة الحياة نفسها. الفرق الوحيد هو أن مفتاح sandbox لا يصل أبداً إلى مُصدِر فاتورة ولا يحرّك أي أموال. والنتيجة التي تحصل عليها يحددها معرّف الحساب الذي ترسله، فيمكنك إعادة إنتاج رفض، واسترداد، ودفعة غير مؤكدة، متى شئت.

  كل مفتاح مرتبط ببيئة واحدة. استدعِ [التحقق من مفتاح API](/ar/api-reference/bill-payment/validate-key) واقرأ `key.type` لتثبت أي مفتاح تحمل.

  → [كل سيناريوهات sandbox وقائمة تحقق قبل الإطلاق](/ar/bill-payment-guides/6-sandbox-testing)

  ## النقاط الأساسية

  <AccordionGroup>
    <Accordion title="الرمز 200 إقرار بالاستلام، لا نتيجة" icon="triangle-exclamation">
      كلا endpointي الكتابة يقبل العمل ويستجيب فوراً. أما النتيجة فتوجد في `status` الخاص بالمعاملة.

      → [الخطوة 4: تتبع الحالة](/ar/bill-payment-guides/4-status-polling)
    </Accordion>

    <Accordion title="لا تُعِد إرسال دفعة أبداً عند UNKNOWN" icon="ban">
      `UNKNOWN` تعني أن النتيجة لم تُؤكَّد بعد. استمر في التتبع — فهي تُحسم إلى `SUCCESS` أو `REFUNDED`. أما إعادة المبلغ لعميلك أو إعادة إرسال الدفعة ما دامت هذه الحالة قائمة فهي الطريق إلى خسارة المال مرتين.

      → [التعامل مع UNKNOWN](/ar/bill-payment-guides/4-status-polling)
    </Accordion>

    <Accordion title="ابحث، ولا تُعِد الإرسال" icon="magnifying-glass">
      كل انتهاء مهلة، وكل `DUPLICATED_REF`، وكل فشل غير مفسَّر، يُجاب عنه بالبحث عن `ref`. وعملية كتابة ثانية ليست أبداً هي التعافي الصحيح.

      → [الخطوة 2: استكشاف الفواتير](/ar/bill-payment-guides/2-discovering-bills)
    </Accordion>

    <Accordion title="اقرأ fee وtotal من الاستجابة" icon="calculator">
      تُضبط الرسوم لكل شريك ويمكن أن تتغير. حمّل عميلك الـ `total` الذي أعادته API، لا رقماً حسبته أنت.

      → [الخطوة 3: دفع الفواتير](/ar/bill-payment-guides/3-paying-bills)
    </Accordion>

    <Accordion title="المعاملة التي ليست لك تعني 404" icon="shield-halved">
      المعاملة التي ليست لك — أو التي تخص البيئة الأخرى — تُعيد `404`، لا `403` أبداً. لا تؤكد API أبداً أن معاملة شخص آخر موجودة.

      → [جلب معاملة بالمعرّف](/ar/api-reference/bill-payment/check-by-id)
    </Accordion>
  </AccordionGroup>

  ## مرجع API

  <CardGroup cols={2}>
    <Card title="التحقق من مفتاح API" icon="key" href="/ar/api-reference/bill-payment/validate-key">
      GET /v3/validate
    </Card>

    <Card title="سرد الشركاء" icon="building-columns" href="/ar/api-reference/bill-payment/list-partners">
      GET /v3/partners
    </Card>

    <Card title="استكشاف الفواتير" icon="magnifying-glass-dollar" href="/ar/api-reference/bill-payment/discover-bills">
      POST /v3/bills/discover
    </Card>

    <Card title="دفع فاتورة" icon="money-bill-transfer" href="/ar/api-reference/bill-payment/pay-bill">
      POST /v3/bills/pay
    </Card>

    <Card title="جلب معاملة بالمعرّف" icon="id-card" href="/ar/api-reference/bill-payment/check-by-id">
      GET /v3/bills/transactions/id
    </Card>

    <Card title="جلب معاملة بالمرجع" icon="tag" href="/ar/api-reference/bill-payment/check-by-ref">
      GET /v3/bills/transactions/by-ref
    </Card>

    <Card title="سرد المعاملات" icon="list" href="/ar/api-reference/bill-payment/list-transactions">
      GET /v3/bills/transactions
    </Card>

    <Card title="تنزيل الإيصال" icon="file-arrow-down" href="/ar/api-reference/bill-payment/get-receipt">
      GET /v3/bills/transactions/id/receipt
    </Card>
  </CardGroup>

  ## بدء التكامل

  <Card title="ابدأ بالخطوة 1: الشركاء والحسابات" icon="play" href="/ar/bill-payment-guides/1-partners-and-accounts" color="#0D9373">
    تحقق من التوفر وتعرّف على قواعد المعرّف لكل مُصدِر فاتورة
  </Card>

  ## موارد إضافية

  <CardGroup cols={2}>
    <Card title="المصادقة" icon="key" href="/ar/authentication">
      المفاتيح والترويسات والبيئات
    </Card>

    <Card title="تنسيق الاستجابة" icon="code" href="/ar/api-reference/response-format">
      المغلّف الذي تُعيده كل endpoint
    </Card>

    <Card title="معالجة الأخطاء" icon="triangle-exclamation" href="/ar/api-reference/error-handling">
      كل رمز خطأ وما ينبغي فعله حياله
    </Card>

    <Card title="استراتيجيات Polling" icon="chart-line" href="/ar/polling-strategies">
      الفواصل الزمنية والتراجع التدريجي والحدود القصوى
    </Card>

    <Card title="أفضل ممارسات الأمان" icon="shield-check" href="/ar/security-best-practices">
      احمِ مفاتيحك وعملاءك
    </Card>

    <Card title="التواصل مع الدعم" icon="headset" href="/ar/contact">
      احصل على مساعدة فريقنا
    </Card>
  </CardGroup>
</div>