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