إدماج أداء الفواتير في تطبيقكم: دليل المُدمِج

باختصار

• أداء الفواتير من أكثر الخدمات تكرارًا في تطبيق مالي: الكهرباء، والماء، والاتصالات، والخدمات العمومية، ومستحقات أخرى.
• API الخاصة بـChari Money تغطي المسار من البداية إلى النهاية: الدائنون، والمستحقات، والاستمارة الديناميكية، والفواتير غير المؤداة، والمعاينة، والتأكيد، والحالة، والإيصال، والويب هوك.
• ثلاث قواعد ذهبية: بناء الاستمارة انطلاقًا من استجابة API، وعدم عرض أي فشل قبل الإشعار النهائي، وإظهار مرجع التسوية دائمًا على الإيصال.
• بالنسبة إلى التاجر الذي يريد فقط أداء فواتيره الخاصة، فالمسار جاهز أصلًا في بوابة التاجر لدى منصة دفع: لا حاجة إلى أي إدماج.

---

لماذا ندمج أداء الفواتير

أداء الفاتورة يتكرر كل شهر. وبالنسبة إلى تطبيق، فهو سبب لفتحه بانتظام، أكثر بكثير من أداء عابر. وهو أيضًا خدمة منتظرة في المحفظة: فالرصيد الذي لا يمكن استعماله في الفواتير رصيد نصف مفيد.

يقدّم مقالنا حول أداء الفواتير عبر الإنترنت في المغرب الخدمة من جهة المستخدم. أما هنا، فنقف في صف الفريق التقني الذي يدمجها في تطبيق أو تطبيق شامل أو شبكة وكلاء، تحت علامته الخاصة، بواسطة وحدة الخدمات ذات القيمة المضافة لدى Chari Money.

وتوضيح قبل البدء: إذا كنتم تاجرًا يريد فقط أداء فواتيره الخاصة من مال مبيعاته، فلا شيء عليكم إدماجه. فـChariPay، منصة الدفع التي تشغّلها Chari Money، تتيح أداء الفواتير من حساب الأداء مباشرة في بوابة التاجر.

المتطلبات المسبقة

قبل أول استدعاء، يجب توفر ثلاثة عناصر:

1. مفتاح API صالح لبيئة sandbox، يُرسل في الترويسة Chari-Api-Key، مع معرّف طلب فريد في C-Request-Id للتتبع.
2. وحدة أداء الفواتير مفعّلة لحساب الشريك الخاص بكم من طرف فريق Chari Money. ودون تفعيل، تفشل الاستدعاءات.
3. مستخدم نهائي موجود، يُعرَّف برقم هاتفه بالصيغة الدولية، ورصيد اختباري للعمليات المدينة.

ويوجد الدليل خطوة بخطوة، مع طلبات واستجابات نموذجية، في توثيق API. ويشرح هذا المقال منطقه وفخاخه.

المسار في ست مراحل

1. عرض الدائنين

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

2. عرض المستحقات

قد يعرض الدائن عدة مستحقات، يقابل كل منها نوع خدمة: فاتورة، رسوم الربط، ضريبة... ويتكون رمز المستحق دائمًا من خانتين.

3. بناء استمارة التعريف

هذه هي المرحلة التي تُنجز في الغالب بشكل خاطئ. فلكل زوج من الدائن والمستحق، تُرجع API لائحة الحقول المراد عرضها: التسمية، والنوع، والصيغة، والحجمان الأدنى والأقصى، والطابع الإلزامي أو الاختياري. يجب أن تُبنى شاشتكم انطلاقًا من هذه الاستجابة، وألّا تُكتب أبدًا بشكل ثابت، وإلا تعطلت عند وصول دائن جديد. والحقول من نوع «التسمية» نص مساعد ثابت: اعرضوها، لكن لا ترسلوها أبدًا في الطلب الموالي.

4. استرجاع الفواتير غير المؤداة

ترسلون القيم التي أدخلها المستخدم. وانتبهوا إلى اسم الخاصية المنتظرة في الطلب، فهو يختلف عن اسمها في الاستجابات: ويشير دليل API إلى ذلك صراحة. وهذا الاستدعاء يفتح المعاملة ويُرجع مرجعًا من 12 رقمًا يجب الاحتفاظ به من أجل التأكيد؛ ويبقى الربط صالحًا لمدة سبعة أيام تقويمية.

وتعرض الاستجابة العناصر غير المؤداة: المستحق، والرسوم، والعناصر الإلزامية، ورسوم التنبر. وبعض المعاملات التقنية ذات التسمية الفارغة يجب ألّا تُعرض أبدًا على الزبون.

5. المعاينة ثم التأكيد

يختار المستخدم تسديد كل شيء أو تحديد عناصر بعينها: الأداء الجزئي مدعوم. ويمكنكم أولًا التحقق من جسم الطلب باستدعاء المعاينة، الذي يقبل الجسم نفسه تمامًا الذي يقبله التأكيد دون تنفيذ الأداء. ثم تؤكدون.

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

6. تتبع المعاملة وتسليم الإيصال

تُقرأ حالة المعاملة انطلاقًا من مرجعها؛ وتُرجع أيضًا معرّف العملية لدى Chari Money، الذي يتيح تنزيل ملف الإيصال. ويجب أن يتضمن الإيصال مرجع التسوية الذي يُرجعه التأكيد. ويتوفر كذلك سجل مُرقَّم لأداءات المستخدم.

الإنصات إلى الويب هوك

أداء الفواتير غير متزامن جزئيًا. وتُصدر الوحدة أربعة أحداث: أداء مؤكَّد، أو ملغى، أو مسترَد، أو فاشل. وتصل الإشعارات بطلب POST مع الترويسة X-Api-Key، وهي المفتاح السري الذي تقدّمونه لـChari Money.

أجيبوا بـ200 OK في أقل من خمس ثوانٍ. فأي رمز خارج 2xx يُطلق محاولة جديدة: بعد دقيقة، ثم 5 دقائق، ثم 30 دقيقة، ثم 60 دقيقة، ثم كل ست ساعات إلى غاية 72 ساعة في المجموع. ولذلك يجب أن تكون معالجتكم Idempotent: فالإشعار نفسه قد يصل أكثر من مرة.

الأخطاء التي يجب توقعها

• 401: مفتاح API غير مأذون له؛ تحققوا من الترويسة ومن البيئة، فالمفاتيح خاصة بكل بيئة.
• معامل ناقص: حقل مطلوب ناقص، رقم الهاتف أو الدائن أو المستحق أو مصفوفة القيم المُدخلة.
• لا توجد فاتورة للأداء: لا يجد الاسترجاع أي عنصر غير مؤدى، وهذا ليس خطأ تقنيًا؛ هيّئوا رسالة واضحة.
• حقل مطلوب غائب: لم يُرسل حقل إلزامي من الاستمارة الديناميكية.

بناء تجربة المستخدم

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

ويقترن أداء الفواتير بشكل طبيعي مع تعبئة الهاتف والقسائم، التي تتبع نموذج المعاينة ثم التأكيد نفسه. وبالنسبة إلى مشروع في بدايته، يساعد دليلنا حول إطلاق شركة تكنولوجيا مالية في المغرب على اختيار ترتيب الخدمات.

من جهة التاجر: الاستخلاص بدل الأداء

لا يجب الخلط بين تطبيق يتيح لمستخدميه أداء فواتيرهم وتاجر يريد أن يؤدى له ثمن فواتيره. فالمدرسة أو العيادة أو المتجر الذي يُفوتر زبناءه يحتاج إلى العكس: إرسال طلب أداء. ولذلك تقترح ChariPay روابط الدفع، التي تُشارَك كرابط أو رمز QR أو بالبريد الإلكتروني أو واتساب، دون أي إدماج.

الخطوة التالية

لتفعيل وحدة أداء الفواتير في بيئة sandbox، اطّلعوا على توثيق واجهة API للشركاء واطلبوا الوصول من صفحة التوثيق. ومن أجل إطلاق في الإنتاج، تُحضَّر إضافة أداء الفواتير كحالة استخدام قائمة بذاتها، مع فريق Chari Money.