Skip to main content

​
مقدمة

يتيح لك دفع الفواتير سداد فواتير المرافق والاتصالات الجزائرية نيابةً عن عملائك. تسأل مُصدِر الفاتورة عمّا يدين به حساب ما، ثم تدفع إحدى الفواتير التي تعود إليك، وتتابعها حتى تصل إلى حالة نهائية، وتحتفظ بالإيصال.المنتج بأكمله خمسة استدعاءات. هذه الصفحة هي الخريطة؛ وكل خطوة أدناه ترتبط بدليل يحتوي على كود عملي بلغات cURL وNode.js وPython وPHP.
يعمل دفع الفواتير على https://billapi.oneclickdz.com — وهو عنوان أساسي مختلف عن بقية المنصة. أما ترويسة المصادقة فهي نفسها التي تستخدمها بالفعل: X-Access-Token.

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

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

1

تحقق من توفر مُصدِر الفاتورة

اقرأ خريطة التوفر وأخفِ أي مُصدِر فاتورة حالته UNAVAILABLE قبل أن يبدأ عميلك بملء أي نموذج.→ الخطوة 1: الشركاء والحسابات
2

استكشف ما هو مستحق

أرسل الشريك ومعرّف الحساب وref الخاص بك. تحصل في المقابل على transactionId؛ وتصل الفواتير على تلك المعاملة بعد لحظة.→ الخطوة 2: استكشاف الفواتير
3

ادفع فاتورة واحدة

اختر billId من bills[]، واعرض على عميلك amount + fee، ثم أرسل الدفعة بـ ref جديد.→ الخطوة 3: دفع الفواتير
4

تابع الحالة حتى تصبح نهائية

SUCCESS أو FAILED أو REFUNDED. أما UNKNOWN فتعني استمر في التتبع — لا تُعِد المبلغ لعميلك أبداً ولا تُعِد إرسال الدفعة ما دامت هذه الحالة قائمة.→ الخطوة 4: تتبع الحالة
5

احفظ الإيصال وطابق الحسابات

نزّل الإيصال، واحفظه مع operationId، وطابق يومياً مع دفتر حساباتك الخاص.→ الخطوة 5: الإيصالات والمطابقة

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

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

يستجيب كل من POST /v3/bills/discover وPOST /v3/bills/pay بالرمز 200 فوراً. وهذا الـ 200 يعني مقبول، لا منتهٍ.
الرمز 200 من pay لا يعني أن الفاتورة دُفعت. النتيجة الحقيقية لا تظهر إلا في status الخاص بالمعاملة. صمّم تكاملك حول التتبع من أول سطر كود — فتأجيل ذلك إلى وقت لاحق هو ما يجعل العملاء يُخصم منهم مرتين.

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

خمسة مُصدِري فواتير، لكل منهم حقل معرّف واحد. أرسل الحقل الذي يخص الشريك؛ وتُعيد API الحقل نفسه إليك في كل معاملة.SEAAL وAADL حالياً UNAVAILABLE في كل من sandbox والإنتاج. اقرأ خريطة التوفر بدلاً من ترميز ذلك بشكل ثابت في الكود.→ قواعد المعرّفات وصيغها وأمثلتها

​
الحالات السبع

→ آلة الحالات الكاملة ومتتبِّع حالة جاهز للإنتاج

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

كل فاتورة تحمل حقولها المالية الخاصة:
  • amount — ما هو مستحق لمُصدِر الفاتورة، بالـ DZD.
  • fee — رسوم خدمة OneClickDz: نسبة مئوية من المبلغ محصورة بين حد أدنى وحد أقصى، تُضبط لكل مُصدِر فاتورة على حدة: عمليًا تدفع معظم الفواتير الحد الأدنى: لا تتجاوز نسبة 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 بدلاً من إرسال الطلب مرة أخرى.
استخدم ref مختلفاً للاستكشاف وللدفع. تحتفظ المعاملة بـ ref الاستكشاف الأصلي، وهو الذي يبحث عنه by-ref.

​
Sandbox

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

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

كلا endpointي الكتابة يقبل العمل ويستجيب فوراً. أما النتيجة فتوجد في status الخاص بالمعاملة.→ الخطوة 4: تتبع الحالة
UNKNOWN تعني أن النتيجة لم تُؤكَّد بعد. استمر في التتبع — فهي تُحسم إلى SUCCESS أو REFUNDED. أما إعادة المبلغ لعميلك أو إعادة إرسال الدفعة ما دامت هذه الحالة قائمة فهي الطريق إلى خسارة المال مرتين.→ التعامل مع UNKNOWN
كل انتهاء مهلة، وكل DUPLICATED_REF، وكل فشل غير مفسَّر، يُجاب عنه بالبحث عن ref. وعملية كتابة ثانية ليست أبداً هي التعافي الصحيح.→ الخطوة 2: استكشاف الفواتير
تُضبط الرسوم لكل شريك ويمكن أن تتغير. حمّل عميلك الـ total الذي أعادته API، لا رقماً حسبته أنت.→ الخطوة 3: دفع الفواتير
المعاملة التي ليست لك — أو التي تخص البيئة الأخرى — تُعيد 404، لا 403 أبداً. لا تؤكد API أبداً أن معاملة شخص آخر موجودة.→ جلب معاملة بالمعرّف

​
مرجع API

التحقق من مفتاح API

GET /v3/validate

سرد الشركاء

GET /v3/partners

استكشاف الفواتير

POST /v3/bills/discover

دفع فاتورة

POST /v3/bills/pay

جلب معاملة بالمعرّف

GET /v3/bills/transactions/id

جلب معاملة بالمرجع

GET /v3/bills/transactions/by-ref

سرد المعاملات

GET /v3/bills/transactions

تنزيل الإيصال

GET /v3/bills/transactions/id/receipt

​
بدء التكامل

ابدأ بالخطوة 1: الشركاء والحسابات

تحقق من التوفر وتعرّف على قواعد المعرّف لكل مُصدِر فاتورة

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

المصادقة

المفاتيح والترويسات والبيئات

تنسيق الاستجابة

المغلّف الذي تُعيده كل endpoint

معالجة الأخطاء

كل رمز خطأ وما ينبغي فعله حياله

استراتيجيات Polling

الفواصل الزمنية والتراجع التدريجي والحدود القصوى

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

احمِ مفاتيحك وعملاءك

التواصل مع الدعم

احصل على مساعدة فريقنا