تكامل طلبات Salla مع Twelve

بنيت هذا التكامل لعميل تُنفذ طلبات متجره على Salla عبر Twelve، مزود المنتجات الرقمية. تستقبل الخدمة أحداث المتجر، وتضع الطلبات المؤهلة في طابور معالجة، ثم تشتري خدمة الشحن أو القسيمة المطلوبة وتسجل النتيجة لدى المتجر.

المشكلة

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

الميزات الرئيسية

• يستقبل مسار webhook الموقع من Salla أحداث الطلبات وتفويض المتاجر.
• تتحقق الخدمة من تكرار الحدث قبل إضافة مهمة التنفيذ إلى الطابور.
• يفحص العامل رصيد Twelve، ويحدد حزم المنتجات من البيانات المخزنة.
• تتحقق عملية الشحن من بيانات الوجهة قبل الشراء، بينما تستخدم القسائم مسار شراء المزود.
• يجدد النظام رموز OAuth الخاصة بـ Salla عند الحاجة إلى استدعاء واجهة المتجر.
• تعالج إشعارات Twelve اللاحقة عمليات الشراء التي تكتمل بصورة غير متزامنة.
• تزامن الخدمة حزم المنتجات في ذاكرة مؤقتة داخل MongoDB.
• يمكن تسجيل إخفاق نهائي في ملاحظة خاصة ضمن سجل طلب Salla.

البنية التقنية

تستقبل خدمة Express الإشعارات وتتحقق من بنية الطلبات. تحفظ MongoDB بيانات تفويض المتاجر والمنتجات المخزنة والطلبات وسجلات منع التكرار. يشغل Redis طابور BullMQ. يقرأ عامل مستقل مهام الطلبات، ويتصل بـ Twelve، ثم يحدث حالة الطلب عبر واجهة Salla البرمجية. يعالج مسار آخر نتائج Twelve المتأخرة. يوجد تكامل منفصل مرتبط بالمشروع باسم description_salla_generator؛ يستقبل أحداث المنتجات من Salla، ويطلب من Gemini وصفًا عربيًا لها، ثم يكتب الوصف عبر واجهة Salla.

جوانب هندسية

• تتحقق الخدمة من توقيع Salla باستخدام بايتات الطلب الأصلية ومقارنة ثابتة الزمن.
• تحفظ رموز OAuth بعد تشفيرها بخوارزمية AES-256-GCM، وتجدد عند انتهاء صلاحيتها أو رفض طلب الواجهة.
• تميز معالجة الطابور بين فشل الشبكة المؤقت ورفض المزود النهائي.
• تمنع سجلات MongoDB الخاصة بمنع التكرار إنشاء عمل جديد عند إعادة إرسال webhook.

دوري

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