ربط أودو مع فسح باي (Fasah Pay): تجربة عملية من بيئة الإنتاج
إذا كانت شركتك تقدّم خدمات لوجستية أو تخليصاً جمركياً أو نقلاً، فغالباً تُطلب منك الآن إصدار فواتيرك لعملائك عبر فسح باي. وإذا كنت تعمل على أودو، فإدخال كل فاتورة مرتين (مرة في أودو ومرة في فسح) يضيّع الوقت ويفتح باب الأخطاء. في هذا المقال أشارك تجربة ربط أودو مع فسح باي حتى نجحت في بيئة الإنتاج، والأخطاء التي واجهتنا وكيف حللناها.
ما هي فسح باي؟
فسح باي خدمة فوترة ودفع على منصة فسح، تديرها الشركة السعودية لتبادل المعلومات إلكترونياً (تبادل) بالشراكة مع المدفوعات السعودية. يستخدمها مقدمو الخدمات في سلسلة التجارة والخدمات اللوجستية، مثل المخلّصين الجمركيين ومقاولي الموانئ والوكلاء الملاحيين وشركات النقل، لإصدار فواتيرهم للمستوردين. والعميل يدفع الفاتورة برقم سداد.
كل فاتورة تُسجَّل في فسح باي تأخذ رقماً خاصاً يبدأ بـ FP، وتُربط ببيانات الشحنة نفسها، مثل رقم البيان الجمركي أو بوليصة الشحن.
فكرة الربط مع أودو
الفكرة بسيطة: الفاتورة تُنشأ في أودو كالعادة، ثم ترسَل إلى فسح باي بضغطة زر، ويعود رقم FP وحالته ويُحفظان على الفاتورة نفسها. لا إدخال مزدوج، ولا نسخ يدوي للأرقام.
| المكوّن في أودو | دوره |
|---|---|
| إعدادات الاتصال | بيانات الاعتماد وعنوان الـ API لبيئة الاختبار وبيئة الإنتاج، محفوظة في الإعدادات وليس داخل الكود. |
| موصّل (Connector) | يولّد التوكن، ويبني الطلب بالشكل الذي يطلبه توثيق فسح باي، ويرسله ويقرأ الرد. |
| حقول على الفاتورة | فئة الفاتورة، ورقم البيان أو البوليصة، والميناء، ورقم FP، وحالة الفاتورة في فسح باي. |
| زر «إرسال إلى فسح باي» | يتحقق من البيانات أولاً ثم يرسل، ويمنع إرسال نفس الفاتورة مرتين. |
| زر «إلغاء فاتورة فسح باي» | نافذة تطلب سبب الإلغاء، ثم ترسل طلب الإلغاء وتحدّث الحالة. |
اختر فئة الفاتورة الصحيحة
فسح باي تربط كل فاتورة بمستند من الشحنة، وتتحقق من أن هذا المستند موجود فعلاً في نظام فسح. لذلك أهم قرار في الربط هو فئة الفاتورة والبيانات المرجعية التي ترسلها معها، مثل:
- البيان الجمركي (Declaration): رقم البيان، وتاريخه، ونوعه (استيراد أو تصدير)، والميناء.
- بوليصة الشحن (Bill of Lading): رقم البوليصة مع رقم مستند المانيفست والميناء.
خطوات التنفيذ
1. ابدأ ببيئة الاختبار
فسح باي توفّر بيئة اختبار (Sandbox) منفصلة عن الإنتاج، ولكل واحدة بيانات اعتماد وعنوان مختلف. ابنِ الموصّل واختبره هناك أولاً. وتأكد أن عنوان البيئة وبيانات الاعتماد تتغيّر من الإعدادات فقط، بدون تعديل الكود.
2. اقرأ ملف Swagger قبل كتابة أي سطر
توثيق فسح باي يأتي مع ملف Swagger يحدد كل حقل: اسمه بالحرف، ونوعه، وهل هو إلزامي. أغلب الأخطاء التي واجهتنا كان حلها مكتوباً في هذا الملف. التزم بأسماء الحقول كما هي بالضبط، حتى حالة الأحرف الكبيرة والصغيرة.
3. جرّب بسكربت صغير قبل أودو
قبل أن تبني الأزرار والنوافذ، جرّب الطلب نفسه بسكربت curl صغير على الخادم. إذا نجح السكربت، فنقله إلى أودو مضمون. وإذا فشل، فأنت تعرف أن المشكلة في البيانات أو الصلاحيات وليس في كود أودو.
4. اعتماد بيئة الإنتاج
لتفعيل الإنتاج، قد يطلب منك فريق فسح باي إثباتاً عملياً أن نظامك متصل: تصدر فاتورة حقيقية من نظامك في بيئة الإنتاج، وترسل لهم رقم FP مع لقطة شاشة، ثم تلغي الفاتورة. لهذا من المهم أن يكون الإلغاء جاهزاً قبل هذا الاختبار.
أخطاء واجهتنا وحلولها
| رسالة الخطأ | السبب الحقيقي | الحل |
|---|---|---|
bill_number_does_not_exist | فسح باي لم تجد تركيبة البيانات المرسلة، لا الرقم وحده. في حالتنا أُرسل رقم البيان الجمركي في خانة رقم مستند المانيفست، وهما رقمان مختلفان تماماً. | تأكد من معنى كل حقل في التوثيق. وإذا كان الرقم المطلوب غير مطبوع على مستنداتك، فغيّر فئة الفاتورة إلى فئة تملك بياناتها. |
JSV0001 Invalid value type 'object' | حقل البنود (item) مُعرَّف في Swagger كـقائمة، وأُرسل ككائن واحد. | أرسل البنود دائماً داخل قائمة [ ]، حتى لو كانت الفاتورة فيها بند واحد فقط. |
not_register_in_esal | طريقة الدفع «سداد» تتطلب أن تكون منشأتك مسجّلة كمُفوتِر في نظام سداد لدى المدفوعات السعودية، وهذا تسجيل منفصل عن بيانات اعتماد فسح باي. | للاختبار استخدم طريقة الدفع «عرض» (View)، فهي تسجّل الفاتورة وتعطي رقم FP بدون فاتورة سداد. وفعّل التسجيل في سداد قبل التشغيل الفعلي. |
| فشل الإلغاء | طلب الإلغاء أُرسل بطريقة POST وبأسماء حقول مختلفة عن التوثيق. | الإلغاء يكون بطريقة PUT، وبأسماء الحقول كما في Swagger بالضبط، ومنها حقل رقم الفاتورة وحقل سبب الإلغاء. |
وفي كل الحالات: البيانات التي تأتي من مستند حقيقي صادر من نظام الإنتاج، مثل فاتورة سابقة صدرت على نفس البيان، أفضل بكثير من بيانات مكتوبة يدوياً. هي التي فكّت المشكلة عندنا في النهاية.
نصائح قبل أن تبدأ
- تحقق من الرقم الضريبي (15 رقماً) وباقي الحقول الإلزامية داخل أودو قبل الإرسال، بدل انتظار رفض فسح باي.
- امنع إرسال نفس الفاتورة مرتين، فكل إرسال ناجح ينشئ فاتورة حقيقية.
- احفظ كل طلب ورد في سجل داخل أودو، فهذا أول ما يحتاجه الدعم الفني عند أي مشكلة.
- اجعل جداول القيم المرجعية، مثل أكواد الموانئ وأنواع البيانات، جداول قابلة للتعديل وليست ثابتة في الكود.
- لا تكتب كلمات السر وبيانات الاعتماد داخل الكود أو السكربتات المشتركة، وغيّرها فوراً إذا شاركتها مع أي شخص.
- اختبر كل تعديل على قاعدة اختبار قبل رفعه لقاعدة الإنتاج.
تحتاج ربط أودو مع فسح باي؟
بنيت موديول ربط أودو مع فسح باي من الإرسال حتى الإلغاء، وتعاملت مع فريق فسح باي حتى اعتماد بيئة الإنتاج. إذا كانت شركتك تصدر فواتيرها عبر فسح باي وتعمل على أودو، تواصل معي.
تواصل معي واتسابالمصادر
- الموسوعة السعودية: ما خدمة فسح باي؟
- دليل فسح باي التقني وملف Swagger الرسمي المقدَّم للجهات المرتبطة.