سجل التغييرات

رسوم الفواتير المتعددة - 23 سبتمبر 2026

تغيير في تسعير billIds. أصبحت رسوم الطلب متعدد الفواتير مجموع قيم fee المعلنة لكل فاتورة مختارة في bills[] — أي كما لو دُفعت هذه الفواتير واحدة تلو الأخرى. ويحلّ هذا محلّ الرسوم الواحدة على المبلغ المجمّع المعلنة أدناه. لا يُقبل billIds الذي يحوي أكثر من معرّف إلا لدى SEAAL.

دفع الفواتير المتعددة - سبتمبر 2026

معامل اختياري جديد، بلا تغييرات جوهرية. billId يعمل تماماً كما يعمل اليوم. وbillIds خيار بديل عنه، وليس استبدالاً له.

صار POST /v3/bills/pay يقبل billIds — حتى 50 فاتورة من المعاملة READY نفسها، تُسوَّى في طلب واحد لدى مُصدِر الفاتورة، ودفعة بطاقة واحدة، ورسوم خدمة واحدة على المجموع الكلي.

🟢 الجديد

billId أو billIds — واحد منهما بالضبط

{
  "transactionId": "68b2f4c1a7d3e9f204c81a55",
  "billIds": ["F059107046", "F057982311", "F056318924"],
  "ref": "pay-inv-2026-0042"
}

billId — فاتورة واحدة، نص لا يتجاوز 100 حرف. لم يتغير.
billIds — من 1 إلى 50 معرّفاً، كل منها لا يتجاوز 100 حرف، ودون تكرار أي معرّف.

وإرسالهما معاً، أو عدم إرسال أي منهما، يُجيب بـ 400 ERR_VALIDATION — “Provide exactly one of billId or billIds”. أما تكرار معرّف فيُجيب بـ “billIds must not repeat the same bill id”.

رسوم واحدة على المجموع الكلي

تُحتسب الرسوم مرة واحدة على مجموع الفواتير التي اخترتها — لا كمجموع الرسوم المذكورة لكل فاتورة على حدة في bills[]. ووفق قاعدة SEAAL البالغة 0.5% بحد أدنى 30 DZD وحد أقصى 60 DZD، فإن ثلاثة أرباع بقيمة 327.00 و480.00 و767.81 DZD مجموعها 1574.81 DZD: ونسبة 0.5% منها تساوي 7.87، أي دون الحد الأدنى، فيحمل الطلب رسوماً واحدة قدرها 30.00 DZD وtotal قدره 1604.81 DZD. ولو دُفعت الفواتير الثلاث نفسها واحدة تلو الأخرى لبلغت الحد الأدنى ثلاث مرات — 90.00 DZD. وطلب ماء من خمس فواتير يكلّف 30.00 DZD رسوماً بدلاً من 150.00 DZD.وتعرض المعاملة الطلب بوصفه فاتورة مختارة مجمّعة واحدة: amount هو مجموع الفواتير المختارة، وfee هي الرسوم الواحدة على ذلك المجموع. وتُجري بيئة sandbox الحساب نفسه كما في الإنتاج، فالأرقام التي تتحقق منها فيها هي الأرقام التي سيخصمها الإنتاج.

القائمة لا تُسوَّى جزئياً أبداً

كل معرّف ترسله يجب أن يكون ما زال على تلك المعاملة READY؛ ومعرّف واحد قديم أو غير معروف يجعل الاستدعاء كله مرفوضاً، فلا يُدفع شيء. ثم يعمل حارسا «مدفوعة بالفعل» و«دفعة قيد التنفيذ» على كل معرّف في القائمة، وهما يتعرّفان على فاتورة سُدّدت سابقاً كسطر ضمن طلب أكبر — فالربع الذي دُفع داخل مجموعة يظل يُجيب بـ 409 BILL_ALREADY_PAID إذا طُلب وحده.

أين يفيد ذلك: SEAAL

لا يكون للتجميع معنى إلا حيث تُسوّي بوابة مُصدِر الفاتورة نفسها عدة مستندات في معاملة واحدة. وهذا اليوم هو SEAAL، حيث تُفوتر المياه فصلياً ويدين الحساب عادةً بأرباع كثيرة غير مدفوعة في آن واحد — 25 ربعاً على حساب إنتاجي جرى التحقق منه. أما بقية المُصدِرين فيعيدون فاتورة واحدة على أي حال، لذا فإن billIds بمدخل واحد تعادل ببساطة billId.وحدّ SEAAL الأدنى للطلب البالغ 200 DA يسري على المجموع المُختار، لا على كل سطر على حدة، فالتجميع لا يزيد تجاوزه إلا سهولة.

دفع الفواتير

المثال المشروح

دفع فاتورة

مرجع الـ endpoint

دفع فواتير SEAAL - سبتمبر 2026

مُصدِر فواتير جديد، بلا تغييرات جوهرية. SEAAL يعمل الآن على endpoints /v3/bills التي تستدعيها بالفعل. لا شيء مما ترسله اليوم يتغير.

SEAAL — موزّع المياه في الجزائر العاصمة وتيبازة — مُدمَج ويسدّد مدفوعات حقيقية. وهو يُبلِّغ بالحالة ACTIVE في خريطة التوفر إلى جانب ADE وSONELGAZ وAADL وAlgérie Télécom. كانت الإصدارات السابقة تصفه بأنه غير قابل للوصول ويبقى UNAVAILABLE دائماً: لم يعد ذلك صحيحاً، لذا اقرأ خريطة التوفر بدلاً من إخفاء الشريك دون قيد أو شرط.

🟢 الجديد

معرّف حساب مُتداخل

SEAAL هو أول شريك يُخاطَب بزوج من المفاتيح بدلاً من مفتاح واحد، لأن مُصدِر الفاتورة يتحقق من الهوية بالشطرين معاً:

{
  "seaal": {
    "code_client": "400123",
    "code_contrat": "446547"
  }
}

code_client — من 2 إلى 6 محارف أبجدية رقمية
code_contrat — من 2 إلى 10 أرقام

كلاهما مطبوع على فاتورة الماء الورقية للعميل وكلاهما إلزامي؛ ولا يوجد اختصار بمفتاح واحد. وتُعيد المعاملة قراءة المعرّف مسطَّحاً في account.codeClient.

عدة فصول، طلب واحد، رسوم واحدة

تُفوتر المياه فصلياً ويمكن أن يحمل الحساب فواتير غير مدفوعة كثيرة في آن واحد — حساب جرى التحقق منه عند الإطلاق كان مديناً بـ 45 فصلاً. واختيار عدة فواتير منها يُنتج طلباً واحداً ودفعة بطاقة واحدة، وتُحتسب الرسوم مرة واحدة على الإجمالي، لا مجموعة لكل فاتورة على حدة. وقاعدة رسوم SEAAL هي 0.5% من المبلغ، محصورة بين حد أدنى 30 DZD وحد أقصى 60 DZD — وهي القاعدة نفسها لدى بقية المُفوتِرين، وعلى فاتورة الماء تستقر دائمًا على حدّ 30 DZD الأدنى.

وصل اختيار عدة فواتير أولاً إلى واجهة الدفع الموجّهة للمستهلك من OneClickDz. وهو متاح الآن في هذه الواجهة البرمجية أيضاً: يقبل POST /v3/bills/pay مصفوفة billIds تضم حتى 50 فاتورة — انظر المدخل أعلاه.

خمسة سيناريوهات sandbox

يتحدد كل سيناريو بقيمة code_client؛ ومع ذلك يجب أن يكون code_contrat موجوداً وصحيح الصيغة.

`code_client`	ما تحصل عليه
`100001`	خمس فواتير فصلية غير مدفوعة — حالة الفواتير المتعددة
`100002`	فاتورة واحدة مستحقة بالضبط
`100003`	حساب مسدَّد بالكامل: `READY` مع `bills[]` فارغة
`100004`	ينجح الاستكشاف ثم تُرفض البطاقة — `PAYMENT_DECLINED`
`100005`	ترفض البوّابة الزوج — خطأ `400 INVALID_ACCOUNT` متزامن

قواعد مُصدِر الفاتورة التي ينبغي التعامل معها

حد أدنى 200 DA. يرفض SEAAL أي طلب يقل إجماليه المُختار عن 200 DA.
حجب مؤقت للحساب. بعد محاولات فاشلة متكررة يحجب مُصدِر الفاتورة ذلك الحساب لبضع ساعات ويذكر المدة. وهذا خاص بالحساب — ليس انقطاعاً للخدمة ولا معرّفاً خاطئاً — والعلاج الوحيد هو الانتظار.
“لا شيء مستحق” نتيجة لا خطأ. الحساب المسدَّد بالكامل يردّ بعبارة «Vous êtes à jour, merci pour votre fidélité.» ويظهر كـ BILL_ALREADY_PAID. وتتم المطابقة بالغياب: الفاتورة المدفوعة تتوقف ببساطة عن الظهور في القائمة.

الشركاء والحسابات

قواعد المعرّفات

نظرة عامة على دفع الفواتير

المسار كاملاً

Bill Payment API - أغسطس 2026

منتج جديد، بلا تغييرات جوهرية. دفع الفواتير قسم جديد من واجهة v3، على العنوان الأساسي والمفتاح اللذين تستخدمهما بالفعل. لم يتغير أي شيء آخر في Flexy API.

ادفع فواتير المرافق والاتصالات الجزائرية نيابةً عن عملائك — ADE وSONELGAZ وSEAAL وAADL وAlgérie Télécom.

🟢 الجديد

العنوان الأساسي الذي تستخدمه بالفعل

+ https://api.oneclickdz.com/v3/bills

نفس المضيف، ونفس رأس X-Access-Token، ونفس المفتاح — لا عنوان أساسي جديد ولا آلية مصادقة جديدة. مفتاح الـ sandbox لديك يختار بيئة الـ sandbox، تماماً كما في بقية v3.

اكتشف، ادفع، استعلم، نزّل

POST /v3/bills/discover — اسأل جهة الفوترة عن مستحقات حساب ما
POST /v3/bills/pay — ادفع إحدى الفواتير المكتشفة
GET /v3/bills/transactions/{transactionId} — تابعها حتى تصل إلى حالة نهائية
GET /v3/bills/transactions/{transactionId}/receipt — نزّل إثبات الدفع

كلا الـ endpoints الكتابيين غير متزامن: الرمز 200 هو إقرار بالاستلام، وتظهر النتيجة في حقل status الخاص بالمعاملة.

بيئة sandbox حتمية

كل مفتاح مرتبط ببيئة واحدة. في وضع sandbox، معرّف الحساب الذي ترسله هو ما يحدد النتيجة، لذا يمكن إعادة إنتاج الرفض والاسترداد والدفعة غير المؤكَّدة عند الطلب.

نظرة عامة على دفع الفواتير

ابدأ من هنا

مرجع API

جميع الـ endpoints السبعة

v3.0.0 - أكتوبر 2025

تغييرات جوهرية: v3 إعادة تصميم كاملة. راجع دليل الهجرة للحصول على تعليمات الترقية.

🔴 ما يجب عليك تغييره

1. تغيير عنوان URL الأساسي

- https://flexy-api.oneclickdz.com/v2
+ https://api.oneclickdz.com/v3

2. تغيير رأس المصادقة

- Authorization: your-api-key
+ X-Access-Token: your-api-key

3. تغيير هيكل الاستجابة

جميع الاستجابات مُغلَّفة الآن في تنسيق موحّد:قبل (v2):

{
  "balance": 50000,
  "currency": "DZD"
}

بعد (v3):

{
  "success": true,
  "data": {
    "balance": 50000,
    "currency": "DZD"
  },
  "meta": {
    "timestamp": "2025-10-29T00:00:00.000Z"
  },
  "requestId": "req_abc123"
}

ادخل إلى البيانات عبر response.data بدلاً من الوصول المباشر من الاستجابة.

4. تغيير مسارات الـ endpoints

الـ endpoint في v2	الـ endpoint في v3
`/topup/plans`	`/mobile/plans`
`/topup/send`	`/mobile/send`
`/topup/check/:id`	`/mobile/check/:id`
`/plans/internet`	`/internet/products`
`/topup/sendInternet`	`/internet/send`
`/account/info`	`/account/balance`

5. تغيير معالجة الأخطاء

قبل (v2):

{
  "error": "Insufficient balance"
}

بعد (v3):

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Your balance is insufficient for this operation",
    "details": {
      "required": 1000,
      "available": 500
    }
  },
  "requestId": "req_abc123"
}

تحقق دائماً من القيمة المنطقية response.success أولاً.

✨ الجديد

API بطاقات الهدايا: نظام تسليم بطاقات هدايا كامل مع أكثر من 100 منتج
مفاتيح Sandbox: مفاتيح API منفصلة للاختبار دون التأثير على رصيد الإنتاج
القائمة البيضاء لعناوين IP: أمان معزّز من خلال إعدادات لوحة التحكم
تتبع الطلبات: كل طلب يتضمن requestId فريداً لأغراض التصحيح
أخطاء أفضل: أكواد خطأ منظّمة مع رسائل قابلة للتنفيذ
التحقق من المخطط: التحقق التلقائي يمنع الطلبات غير الصالحة

📅 الموعد النهائي للهجرة

ستُوقَف v2 في 30 أكتوبر 2026. انتقل قبل هذا التاريخ لتجنب انقطاع الخدمة.

البدء

أدلة متقدمة

رسوم الفواتير المتعددة - 23 سبتمبر 2026

دفع الفواتير المتعددة - سبتمبر 2026

🟢 الجديد

دفع الفواتير

دفع فاتورة

دفع فواتير SEAAL - سبتمبر 2026

🟢 الجديد

الشركاء والحسابات

نظرة عامة على دفع الفواتير

Bill Payment API - أغسطس 2026

🟢 الجديد

نظرة عامة على دفع الفواتير

مرجع API

v3.0.0 - أكتوبر 2025

🔴 ما يجب عليك تغييره

✨ الجديد

📅 الموعد النهائي للهجرة

🔗 الموارد

v2.x - ما قبل أكتوبر 2025

أغسطس 2025

يوليو 2023

سابقاً

تحتاج مساعدة؟

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

​رسوم الفواتير المتعددة - 23 سبتمبر 2026

​دفع الفواتير المتعددة - سبتمبر 2026

​🟢 الجديد

دفع الفواتير

دفع فاتورة

​دفع فواتير SEAAL - سبتمبر 2026

​🟢 الجديد

الشركاء والحسابات

نظرة عامة على دفع الفواتير

​Bill Payment API - أغسطس 2026

​🟢 الجديد

نظرة عامة على دفع الفواتير

مرجع API

​v3.0.0 - أكتوبر 2025

​🔴 ما يجب عليك تغييره

​✨ الجديد

​📅 الموعد النهائي للهجرة

​🔗 الموارد

​v2.x - ما قبل أكتوبر 2025

​أغسطس 2025

​يوليو 2023

​سابقاً

​تحتاج مساعدة؟

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

رسوم الفواتير المتعددة - 23 سبتمبر 2026

دفع الفواتير المتعددة - سبتمبر 2026

🟢 الجديد

دفع فواتير SEAAL - سبتمبر 2026

🟢 الجديد

Bill Payment API - أغسطس 2026

🟢 الجديد

v3.0.0 - أكتوبر 2025

🔴 ما يجب عليك تغييره

✨ الجديد

📅 الموعد النهائي للهجرة

🔗 الموارد

v2.x - ما قبل أكتوبر 2025

أغسطس 2025

يوليو 2023

سابقاً

تحتاج مساعدة؟