تعبئة الهاتف والقسائم عبر API: إضافة خدمات الحياة اليومية إلى تطبيقكم
باختصار
- تعبئة الهاتف والقسائم خدمات ذات قيمة مضافة تعيد المستخدم: مبالغ صغيرة، وحاجة متكررة، ونتيجة فورية.
- التعبئة تتم باستدعاءين (الكتالوج، ثم التنفيذ) حين يؤدي الشريك، أو بمعاينة مسبقة حين يُقتطع من محفظة الزبون.
- القسيمة تتبع مسار العلامات، ثم المنتجات، ثم المعاينة، ثم التأكيد؛ ويُسلَّم الرمز عند التأكيد.
- متطلبان مسبقان يتكرران في كل مكان: الوحدة مفعّلة لحساب الشريك الخاص بكم، ورصيد للعمليات المدينة.
لماذا هاتان الخدمتان
في تطبيق مالي، تلعب تعبئة الهاتف وشراء القسائم الرقمية الدور نفسه: فهما تمنحان سببًا لاستعمال الرصيد كثيرًا، بمبالغ صغيرة، ونتيجة مرئية فورًا. وتكمّلان أداء الفواتير ضمن عرض الخدمات ذات القيمة المضافة لدى Chari Money.
ويقدّم مقالانا حول تعبئة الهاتف عبر الإنترنت والقسائم والبطاقات الرقمية هاتين الخدمتين من وجهة نظر المستخدم. أما هذا الدليل فموجّه إلى الفريق الذي يدمجهما.
قبل البدء
تلزم ثلاثة عناصر، في بيئة sandbox كما في الإنتاج:
- مفتاح API صالح، خاص بكل بيئة.
- الوحدة مفعّلة لحساب الشريك الخاص بكم: فتعبئة الهاتف والقسائم تُفعَّلان كلتاهما عند الطلب من طرف فريق Chari Money. وبالنسبة إلى القسائم، يجب أيضًا تزويد الكتالوج في بيئة sandbox.
- رصيد في حساب الوكيل الرئيسي الخاص بكم، لأن هذه العمليات تقتطع من رصيد.
وحساب الوكيل الرئيسي هو الذي يحمل صفتكم كشريك؛ ويشرح مقالنا حول صفة الوكيل الرئيسي ما تشمله. وفي الإنتاج، يتطلب تفعيل كل حالة من حالات الاستخدام هذه الموافقة المسبقة لمديرية الإشراف البنكي.
تعبئة الهاتف، استدعاءً بعد استدعاء
كتالوج العروض
يُرجع كتالوج B2B منتجات التعبئة المتاحة لرقم ومبلغ ومشغّل، ويُشار إلى هذا الأخير برمز رقمي. ويحمل كل منتج رمز منتج فريدًا، يُعاد استعماله في التعبئة، ومؤشرًا للتوفر.
التنفيذ
تُنفَّذ التعبئة برمز المنتج المختار ورمز الوكيل الرئيسي الخاص بكم، الذي يحدد الحساب المقتطَع منه. ويتعايش نوعان من التعبئة: التعبئة الكلاسيكية، المعبَّر عنها بالدرهم، والتعبئة من نوع المنتج، التي تقابل باقة من الكتالوج.
صيغة الزبون
إذا كانت التعبئة تُؤدّى من محفظة الزبون، لا من طرف الشريك، فنستعمل صيغة الزبون. وتبدأ بـمعاينة: المحفظة المقتطَع منها والرقم المعبَّأ مختلفان فيها، ويُرجع الرد الرسوم والمبلغ الإجمالي. وبعد أن يصادق المستخدم على المعاينة، يُعاد استعمال الجسم نفسه في التنفيذ.
السجل
سجل تعبئات الزبون مُرقَّم وقابل للتصفية حسب الحالة، ويمكن الجمع بين عدة حالات في الطلب نفسه.
| التعبئة B2B | صيغة الزبون | |
|---|---|---|
| الحساب المقتطَع منه | حساب الوكيل الرئيسي | محفظة الزبون |
| معاينة مسبقة | لا | نعم، مع الرسوم والمجموع |
| الاستعمال المعتاد | شبكة الوكلاء، تعبئة مُهداة | تطبيق موجّه للعموم |
القسائم، من الكتالوج إلى الرمز
العلامات والمنتجات
لائحة العلامات مُرقَّمة وتتطلب رقم هاتف الزبون. ولعلامة معيّنة، تعرض لائحة منتجاتها السعر، وخاصة المعرّفين المطلوبين لاحقًا: معرّف المنتج لدى المزوّد ومعرّف المزوّد. احتفظوا بهما.
المعاينة
تتحقق المعاينة من إمكانية الشراء. ويحمل جسمها خمسة حقول إلزامية: هاتف الزبون، وهاتف الوجهة، واسم المستفيد، ومعرّفا المنتج. ويُرجع الرد الرسوم والمبلغ الإجمالي: اعرضوهما قبل أي تأكيد.
التأكيد وتسليم الرمز
يعيد التأكيد استعمال الجسم نفسه. ورده هو الذي يحمل المُخرَج: رمز القسيمة، مع اسمها ووصفها ومبلغ الاسترداد النقدي إن وُجد. خزّنوا الرمز بشكل آمن وسلّموه للمستفيد، مثلًا في شاشة الإيصال وفي السجل.
وتعرض API أيضًا كتالوجًا للقسائم المحلية، قابلًا للتصفية حسب العلامة والكلمة المفتاحية، يغذّي مسار شراء ثانيًا مستقلًا: لا تخلطوا بين المسارين في إدماج واحد دون التخطيط لذلك.
الأخطاء والتتبع
تتبع الأخطاء رموز HTTP المعيارية. ويعود خطأ العمل برمز 400 مع رمز خطأ Chari ووصفه في الجسم. وأكثر الحالات تكرارًا أثناء الإدماج:
- خدمة غير مفعّلة: الوحدة غير مفعّلة لحسابكم؛ اطلبوا التفعيل.
- كتالوج فارغ: علامات القسائم غير مزوَّدة في بيئة sandbox؛ وهذا ليس خطأ.
- معامل ناقص: حقل إلزامي من الجسم ناقص، مثل رمز الوكيل أو رمز المنتج أو نوع التعبئة، أو أحد الحقول الخمسة لمعاينة القسيمة.
- 401: مفتاح API غير مأذون له أو مستعمل في البيئة الخطأ.
أدرجوا معرّف طلب فريدًا مع كل استدعاء: فهو يُرجَع في الرد ويسرّع أي تواصل مع الدعم.
تصميم التجربة جيدًا
- اعرضوا الرسوم قبل التأكيد. فلهذا وُجدت المعاينة: يجب أن يكون المجموع المعروض هو المقتطَع.
- احتفظوا بأثر. إيصال لكل عملية، متاح في السجل، مع رمز القسيمة حين يوجد.
- هيّئوا الفشل بشكل سليم. إذا فشل التنفيذ، فلا تعرضوا أي اقتطاع واقترحوا إعادة المحاولة: فالسجل المصفّى حسب الحالة يتيح التحقق مما حدث فعلًا قبل إعادة إطلاق عملية، ويجنّب بذلك تعبئة الخط نفسه مرتين.
- دبّروا الرصيد التشغيلي. من جهة الشريك، راقبوا رصيد الوكيل الرئيسي كي لا تتوقف تعبئات B2B؛ ويتيح الإيداع بالبطاقة، في صيغة الوكيل، إعادة تكوينه.
أين نضع هذه الخدمات في المنتج
هذه الخدمات لا تُباع وحدها: بل توضع حيث يحتاجها المستخدم. ففي تطبيق موجّه للعموم، كثيرًا ما تفعل خانة «تعبئة» في الشاشة الرئيسية، مع الأرقام الأخيرة، أكثر من أي حملة. وبالنسبة إلى القسائم، يساعد قسم لكل مجال (الألعاب، والترفيه، وبطاقات الهدايا) على إيجاد العلامة المناسبة دون تصفح الكتالوج كله.
أما في شبكة الوكلاء، فالمنطق مختلف: الوكيل هو الذي يبيع التعبئة أو القسيمة لزبون عابر، من الرصيد التشغيلي للوكيل الرئيسي. والتعبئة B2B مصمَّمة لهذا الاستعمال، وشبكة الوكلاء لدى Chari Money قناتها الطبيعية.
وفي الحالتين، حافظوا على الانضباط نفسه: معاينة تُظهر المجموع، وتأكيد صريح، وإيصال محفوظ في السجل، ورمز قسيمة يمكن العثور عليه لاحقًا إذا أضاعه المستفيد.
وماذا عن التاجر؟
هذه الإدماجات موجّهة إلى الشركاء الذين يشغّلون محافظ لمستخدميهم. أما التاجر الذي يريد فقط تعبئة خطوط فريقه من مال مبيعاته فلا يحتاج إلى كل هذا: فـChariPay، منصة الدفع التي تشغّلها Chari Money، تتيح ذلك عبر API من رصيد حساب الأداء الخاص بالتاجر. ولتجربة ذلك، افتحوا حسابًا في وضع الاختبار: ابدؤوا في وضع الاختبار.
الخطوة التالية
لتفعيل تعبئة الهاتف والقسائم في بيئة sandbox الخاصة بكم، اطّلعوا على توثيق واجهة API للشركاء واطلبوا من جهة اتصالكم لدى Chari Money تفعيل الوحدات ورصيدًا اختباريًا.
الأسئلة الشائعة
- كيف ندمج تعبئة الهاتف في تطبيق؟
- بواسطة API الخاصة بـChari Money، باستدعاءين للتعبئة التي يؤديها الشريك: استرجاع كتالوج العروض لرقم ومبلغ ومشغّل، ثم تنفيذ التعبئة برمز المنتج المختار. وتوجد صيغة تقتطع من محفظة الزبون، مع معاينة مسبقة للرسوم.
- ما الفرق بين التعبئة B2B وصيغة الزبون؟
- التعبئة B2B تقتطع من حساب الوكيل الرئيسي، أي الشريك. أما صيغة الزبون فتقتطع من محفظة الزبون: نستدعي أولًا المعاينة للتحقق من الإمكانية والمبلغ والرسوم، ثم ننفّذ بالجسم نفسه.
- كيف يتم بيع قسيمة؟
- نتصفح العلامات، ثم نسترجع منتجات علامة ما بمعرّفَي المزوّد الخاصين بها، ثم نعاين الشراء للحصول على الرسوم والمجموع، ثم نؤكد. ورد التأكيد هو الذي يحمل رمز القسيمة الذي يُسلَّم للمستفيد.
- لماذا يكون كتالوج القسائم فارغًا في بيئة sandbox؟
- الكتالوج الفارغ ليس خطأ في الإدماج: فعلامات القسائم يجب أن تزوّدها Chari Money في بيئة sandbox لحسابكم. اطلبوا من جهة اتصالكم تفعيل الوحدة، ورصيدًا اختباريًا للوكيل الرئيسي، لأن الشراء عملية مدينة.
- كيف تُبلَّغ الأخطاء؟
- تتبع الأخطاء رموز HTTP المعيارية؛ ويعود خطأ العمل برمز 400 مع رمز خطأ Chari ووصفه في الجسم. أرسلوا معرّف طلب فريدًا مع كل استدعاء: فهو يعود في الرد ويسهّل التتبع مع الدعم.
- هل يمكن للتاجر تعبئة خطوط من رصيده؟
- نعم، ودون مشروع بنية تحتية: فـChariPay، منصة الدفع التي تشغّلها Chari Money، تتيح للتاجر تعبئة خطوط الاتصالات عبر API من رصيد حساب الأداء الخاص به، مع وصول النتيجة عبر ويب هوك موقَّع.