ربط MyFatoorah مع Flutter يمكن تنفيذه عبر فاتورة ينشئها خادمك ورابط دفع يفتحه التطبيق، بدل تضمين رمز التاجر في الهاتف. هذا المقال يراجع هذا المسار تحديدًا، مع توضيح الفرق بين الحزمة المجتمعية my_fatoorah المستخدمة في المثال القديم وحزمة myfatoorah_flutter المشار إليها في توثيق المزوّد الرسمي.
اختر تكاملًا واحدًا واضحًا
الواجهات بين الحزمتين ليست بديلًا مباشرًا؛ تغيير اسم الاعتماد مع الإبقاء على MyFatoorah.startPayment لا يحول المثال إلى SDK الرسمي. عند مراجعة SDK الرسمي ظهر myfatoorah_flutter 3.3.2، ومرجع الترحيل من الإصدارات القديمة يوضح اختلاف التنفيذ الأصلي. إذا اخترت SDK فاتبع واجهته وإعداداته وقيود منصاته، ولا تنقل مقاطع من حزمتين إلى ملف واحد.
سنستخدم هنا رابط فاتورة من Backend، لذلك لا يتطلب مثال Flutter مفتاح MyFatoorah سريًا. يمكن للخادم استخدام مسار SendPayment الموثق لإصدار رابط، مع الإعداد الذي يعيده في الاستجابة بدل إرسال رسائل بريد أو SMS إذا لم تكن تلك تجربة المنتج المطلوبة. اختيار وسيلة الإرسال وفعلها شأن الخادم وإعداد الحساب، وليس نتيجة تلقائية لعرض زر في الهاتف.
عقد الخادم مع التطبيق
ينشئ الخادم الطلب ويحسب قيمته ويتحقق من المستخدم، ثم يتواصل مع MyFatoorah ويحفظ Invoice ID أو المرجع المناسب. يعيد للتطبيق orderId وcheckoutUrl وexpiresAt وفق عقد المكوّن المشترك. المسار /orders/{id}/checkout في المثال مسار يخص نظامك، وليس عنوانًا رسميًا لـMyFatoorah ولا خدمة متاحة جاهزة.
المكوّن BackendCheckoutApi معرّف في درس ربط Paymob لكنه لا يستدعي Paymob مباشرة؛ يمكن إعادة استخدامه عندما يطبق خادمك العقد نفسه مع MyFatoorah. اضبط قائمة النطاقات لتطابق رابط الفاتورة الموثق في منطقتك، ولا تسمح بأي نطاق لمجرد أن اسمه يحتوي كلمة invoice أو payment.
import 'package:dio/dio.dart';
import 'package:flutter/material.dart';
import 'checkout.dart';
import 'checkout_page.dart';
Widget myFatoorahCheckoutPage({
required Dio authenticatedBackend,
required String orderId,
required Set<String> documentedCheckoutHosts,
}) => CheckoutPage(
orderId: orderId,
api: BackendCheckoutApi(authenticatedBackend, documentedCheckoutHosts),
);
يتطلب المقطع ملفات checkout.dart وcheckout_controller.dart وcheckout_page.dart من الدروس المرتبطة. مرر Dio موثقًا بعنوان HTTPS لخادمك، ومعرّف طلب يخص الحساب الحالي، والنطاقات الموثقة. لا تعِد استخدام أمثلة مفاتيح أو معرّفات فواتير تخص مؤلف درس أو حسابًا عامًا، ولا تسجل رابط الفاتورة كاملًا إذا حمل بيانات جلسة.
احذف استثناءات HTTP العامة
التعليمات القديمة كانت تضيف NSAllowsArbitraryLoads وusesCleartextTraffic:true على مستوى التطبيق. هذه ليست خطوة لازمة عامة لتكامل دفع حديث عبر HTTPS. أزل الاعتماد عليها من المثال، وشخّص الشهادة أو النطاق أو إعداد WebView إذا ظهرت مشكلة بدل تعطيل حماية النقل على جميع الاتصالات.
لا تنقل استثناءات تطوير إلى نسخة منشورة دون حاجة محددة ومراجعة. كذلك io.flutter.embedded_views_preview من أمثلة قديمة لا يمثل إعدادًا مطلوبًا تلقائيًا لكل إصدار Flutter. اتبع دليل إصدار الحزمة والمسار الذي اخترته، ولا تستبدل ملفات المنصة كاملةً لأن لقطة شاشة قديمة استخدمت إعدادًا مختلفًا.
كيف تُؤكد الفاتورة؟
تعيين successUrl إلى صورة مكتوب عليها نجاح لا يثبت دفع الفاتورة. بعد العودة اطلب حالة الطلب من خادمك، واجعل التحديث النهائي مبنيًا على استعلام موثق أو Webhook متحقق من توقيعه، مع مطابقة المعرّف والمبلغ والعملة. قد يغلق العميل الصفحة قبل الرجوع، ولذلك يجب أن ينجح تحديث الخادم دون بقاء شاشة Flutter مفتوحة.
احتفظ بحالات انتظار وفشل وانتهاء مستقلة، وتجنب تحويل كل استثناء إلى إلغاء دفع. في حال وسائل دفع غير فورية قد تحتاج متابعة لاحقة، كما يجب ألا تنفذ webhook مكررًا مرتين. المثال لا يجمع أرقام بطاقة أو يخزن CVV، ووجود فاتورة ليس ترخيصًا لعرض بياناتها لأي مستخدم يعرف المعرّف.
اختبار المسار قبل النشر
اختبر رفض إنشاء الفاتورة، وعودة رابط غير موثوق، والرجوع دون دفع، ونجاحًا يؤكده الخادم متأخرًا، وتكرار الإشعار. طابق بيئة الاختبار مع مفتاحها والمنطقة ووسيلة الدفع المفعلة. اختبارات Dart لا تثبت تفعيل حساب التاجر أو قبول بنك معين، ولم تُنفذ هنا أي عملية مالية أو إرسال بريد دفع إلى عميل.
الخصوصية عند عرض الفاتورة
قد يحتوي رابط الفاتورة أو استعلام الحالة على بيانات عميل، لذلك لا ترسله تلقائيًا إلى أدوات التحليلات أو سجلات الأعطال. إذا أضفت مشاركة للرابط، اجعلها إجراءً مقصودًا للمستخدم ووضح ما سيشاركه. احتفظ بتفاصيل الدفع الحساسة خارج نموذج الواجهة، ولا تتعامل مع حقل قابل للتعديل في الهاتف باعتباره دليلًا على المبلغ المقبوض.
يمكن استخدام صفحة المتابعة المشتركة المبيّنة في صفحة دفع Paymob في Flutter وقراءة نتيجة الطلب من الخادم مع رابط الفاتورة الذي يعيده خادم MyFatoorah الخاص بك وفق العقد المذكور.





