مطابقة مدفوعات سلة: الطلب ليس دفتر معاملات

يمثل الطلب المدفوع ومعاملة الدفع حقيقتين مترابطتين، لكنهما ليسا السجل نفسه. يشرح الطلب ما ينوي التاجر تنفيذه، بينما تسجل المعاملة حركة عبر مسار دفع. قد يحتوي الطلب أكثر من وسيلة دفع، وقد يكون الاسترداد جزئيًا، وقد يصل الـWebhook مرتين، وقد يترك انتهاء مهلة الشبكة نتيجة العملية مجهولة. إذا اختصر ERP أو نظام مالي كل ذلك في `order.is_paid = true`، فقد الدليل اللازم لتفسير الفروقات لاحقًا.

تعرض وثائق سلة الحالية ثلاث زوايا مفيدة. تحتوي تفاصيل الطلب على وسيلة الدفع ومجموعة `payment_methods` في الاستجابة الموثقة ومبالغ الطلب. وتكشف قائمة المعاملات وتفاصيل المعاملة معرفات المعاملة ومراجع الطلب والمبلغ والعملة والمزود والوسيلة والحالة والأفعال المتاحة. كما تشمل Webhooks المتجر الحدثين `order.payment.updated` و`order.refunded`. يجب أن تتقارب هذه الزوايا، لكن لكل منها غرض تشغيلي مختلف.

هذا شرح مبني على الوثائق الحالية، وليس ادعاءً بأن ميزة مطابقة المدفوعات أطلقت اليوم. جرى التحقق من الوثائق في 28 سبتمبر 2026. ويركز المقال على هندسة التطبيق؛ أما المعالجة المحاسبية وتقارير التسوية والالتزامات الضريبية فتحتاج أدلتها المالية والتنظيمية المناسبة.

مثّل الأموال بدفتر لا يحذف التاريخ

احتفظ بطلب المنصة ككيان للتجارة، وأنشئ دفتر مدفوعات محليًا مستقلًا. يجب أن يكون مفتاح صف المعاملة هو التاجر مع معرف معاملة سلة، لا الطلب وحده. خزّن مرجع الطلب ومرجع معاملة المزود عند توفره والمبلغ بوحدات العملة الصغرى والعملة ووسيلة الدفع والحالة الموحدة وتوقيت المصدر وآخر حالة رُصدت وبصمة الدليل الخام.

لا تستبدل التاريخ المالي كلما وصل Webhook جديد. أضف Observation أو انتقال حالة، ثم اشتق العرض الحالي. قد تنتقل المعاملة نفسها من حالة وسيطة إلى نهائية، بينما يجب أن يبقى الاسترداد مرتبطًا بعملية الخصم الأصلية. يتيح السجل الإلحاقي معرفة من رصد الانتقال، ومن أي حمولة، وأي تشغيل مطابقة أكده.

استخدم أعدادًا صحيحة للأموال بعد التحقق من منازل كل عملة. تجنب Floating Point الثنائية، ولا تقارن نصوصًا منسقة. عرّف ثوابت صريحة لكل طلب: المبلغ المحصل، والمسترد، وصافي المدفوع، وإجمالي الطلب المستحق؛ ويجب أن تشترك في العملة قبل الحساب. العملات المختلطة أو غير المتوقعة تذهب إلى طابور استثناءات، لا إلى تحويل تلقائي.

اعتبر الـWebhooks إشارات لا دليلًا نهائيًا

اشترك في أصغر مجموعة أحداث تصلح عرضك: غالبًا `order.payment.updated` و`order.refunded` مع أحداث الطلب اللازمة أصلًا للتكامل. تحقق من توقيع سلة فوق النص الخام للطلب، واكتب الحدث في صندوق وارد دائم، ونفذ Commit، ثم أعد نجاحًا سريعًا. لا يجب أن يرسل الـEndpoint العام قيودًا إلى ERP أو يصدر استردادًا.

ابنِ مفتاح منع التكرار من التاجر ونوع الحدث ومرجع الطلب أو المعاملة الثابت والحقول المستقرة المتاحة في النموذج الموثق، واحتفظ ببصمة الحمولة. ومع ذلك، اجعل كل انتقال لاحق Idempotent لأن حدثين مختلفين قد يصفان النتيجة نفسها بصورة صحيحة.

يجب أن يستخدم Worker الحدث سببًا لقراءة الدليل الحالي. إذا توفر معرف معاملة، فاقرأ تفاصيلها. وإلا فاستعلم عن المعاملات بمرجع الطلب. خزّن وقت الحدث منفصلًا عن وقت سجل المنصة ووقت الرصد لديك؛ تساعد الساعات الثلاث في تشخيص اختلاف الترتيب. الحدث الذي يقول إن الدفع تغير لا يأذن وحده بالتنفيذ إذا تعذرت القراءة اللاحقة أو تناقضت.

طابق الطلبات مع المعاملات

احسب لكل طلب متغير Snapshot للمطابقة من صفوف المعاملات. تربط استجابة المعاملة الموثقة في سلة المعاملة بـ`reference_id` و`order_id` و`cart_id`، وتشمل المبلغ والعملة ووسيلة الدفع والحالة. وتوثق واجهة القائمة فلاتر منها معرف الطلب والحالة والوسيلة والمبلغ وآخر أربعة أرقام. استخدم معرف الطلب للإصلاح الحتمي، وتعامل مع بيانات العميل وأجزاء البطاقة كوسائل بحث حساسة لا كمفاتيح أعمال.

قارن أربعة أبعاد على الأقل. الهوية تسأل هل ترتبط كل معاملة محلية بالتاجر والطلب المقصودين. العملة تسأل هل الأموال المجموعة قابلة للمقارنة. الحالة تسأل هل التوحيد المحلي يطابق Slug الحالي في المنصة. والمبلغ يسأل هل العمليات المحصلة ناقص الاستردادات المؤكدة تساوي صافي الدفع المتوقع. النتيجة ليست `matched` أو `failed` فقط؛ استخدم `temporarily_incomplete` و`ambiguous` و`overpaid` و`underpaid` و`currency_mismatch` و`manual_review` أيضًا.

تبقى تفاصيل الطلب مفيدة لجانب التجارة، لكن لا تربط المطابقة بالاستجابة الموسعة المتوقفة. توثق سلة أن الاستجابة القديمة `expanded` انتهت في 1 سبتمبر 2026، وأن الصيغة الخفيفة تستبعد موارد متداخلة عدة. اقرأ فقط حقول الدفع والمبالغ الموثقة من واجهة الطلب، واستخدم واجهات المعاملات المخصصة لحقيقة المعاملة.

اجعل الاسترداد أمرًا ذا نتيجة دائمة

تدعم واجهة تحديث المعاملة الأفعال `refund` و`void` و`reverse`، ومنها الاسترداد الجزئي، ضمن صلاحية `transactions.read_write`. وتحذر الوثائق من ضرورة توفر رصيد كافٍ لدى المتجر لتنفيذ الاسترداد. هذا أمر يحرك أموالًا، لذلك فإن حلقة Retry عامة غير آمنة.

قبل الاستدعاء، أنشئ أمر استرداد بمفتاح أعمال فريد مثل: التاجر، والمعاملة الأصلية، ومرجع الإرجاع أو الحالة، والمبلغ، والعملة. انقله بين `requested` و`dispatching` و`observed_succeeded` و`observed_failed` و`unknown`. إذا انتهت مهلة الطلب، فلا تصدر استردادًا ثانيًا مباشرة. اقرأ تفاصيل المعاملة ودليل الاسترداد الحالي في الطلب ثم طابق. لا تسمح بمحاولة مضبوطة إلا بعد إثبات الغياب.

تحقق من المبلغ المطلوب مقابل الرصيد القابل للاسترداد المحسوب من قيود مؤكدة، لا من صفحة قديمة. اشترط تطابق العملة مع المعاملة الأصلية. وسلسل أوامر الاسترداد المتزامنة لكل معاملة، واستخدم قيود قاعدة البيانات لمنع Workerين من حجز المبلغ نفسه. وافصل الموافقة عن التنفيذ عندما تتطلب ضوابط التاجر ذلك.

شغّل مطابقة محدودة باستمرار

يوفر الإصلاح القائم على الأحداث زمن استجابة منخفضًا، بينما توفر المطابقة المجدولة الاكتمال. احتفظ بعلامة تقدم لكل تاجر، وامسح نافذة حديثة محدودة من المعاملات مع كل أمر لم يُحسم. اجعل النوافذ متداخلة كي تُرى التحديثات المتأخرة مجددًا، ودع Upsert المقاوم للتكرار يمتص النسخ. احفظ تقدم الصفحات واحترم ترويسات الحدود حتى لا يحتكر متجر كبير العمال.

نفذ المطابقة على طبقات: حلقة سريعة للطلبات الجديدة أو المتغيرة، وأبطأ للاستثناءات المفتوحة، وملخص يومي لتواريخ الأعمال المغلقة. أعطِ الأولوية لنتائج الاسترداد المجهولة والطلبات المدفوعة المنتظرة للتنفيذ قبل التطابقات التاريخية. لا تصحح ERP تلقائيًا من صف ملتبس؛ افتح حالة تتضمن الطلب والمعاملة والمبلغ المتوقع والمرصود والعملة وتوقيتات المصدر.

من المؤشرات المفيدة: تأخير الـWebhook إلى الدفتر، والطلبات المدفوعة غير المطابقة، والمعاملات بلا طلبات، وعمر الاسترداد المجهول، والأحداث المكررة الممنوعة، وفروقات المبلغ حسب المزود، ووقت التراجع بسبب Rate Limit، ونسبة الحالات التي تُحل تلقائيًا. أنذر عند نمو عمر الاستثناء، لا حجم الطابور وحده.

اختبر بمستوى يليق بالأموال

اختبر Webhooks مكررة وغير مرتبة، ودفعًا ناجحًا تتبعه إشارة فشل متأخرة، ووسائل دفع مقسمة، واستردادات جزئية، وطلبي استرداد متزامنين، وانتهاء المهلة بعد قبول سلة للأمر، وتعذر قراءة المعاملة، واختلاف العملة، وانتهاء Token، وإعادة صفحة مطابقة بعد تعطل. أسقط حدثًا عمدًا وأثبت أن المسح المجدول يصلحه.

ابدأ في وضع Shadow. استقبل الأحداث، وابنِ الدفتر، وقارنه بالتقرير التشغيلي الحالي للتاجر من دون تغيير التنفيذ أو المحاسبة. فسّر كل فرق قبل تفعيل الأتمتة. ثم اسمح بتحديثات الحالة منخفضة المخاطر مع إبقاء الاستردادات خلف موافقة، وأخيرًا فعّل أوامر آلية محدودة مع مفتاح إيقاف.

القاعدة العملية بسيطة: يخبر الطلب النشاط التجاري بما سينفذه، وتخبر المعاملة خدمة الدفع بما حدث، ويسجل دفتر المطابقة لماذا يعتقد نظامك أن الاثنين متفقان. تجعل Webhooks هذا الاعتقاد سريعًا، وتجعله القراءات المتكررة وثوابت الأموال ونتائج الأوامر الدائمة جديرًا بالثقة.

إعداد: Noor Yasser