HTTP 200 لا يعني نجاح المهمة: كيف تتحقق من الأثر النهائي في الأتمتة؟

الاستجابة الناجحة ليست نهاية القصة

قد يرسل نظام أتمتة طلبًا إلى API فيحصل على HTTP 200 أو 202، ثم يعلن أن المهمة اكتملت. لكن ماذا لو قبل الخادم الطلب ووضعه في طابور لم يُعالج بعد؟ وماذا لو أعاد 200 مع حقل يوضح أن التحديث رُفض منطقيًا؟ أو حدث التغيير في خدمة أولى ولم يصل إلى قاعدة التقارير؟ نجاح النقل عبر HTTP يجيب عن سؤال محدود: كيف استقبل الطرف الآخر الطلب؟ أما نجاح المهمة التجارية فيحتاج دليلًا على تحقق الحالة المطلوبة. لهذا يجب الفصل بين نجاح الاتصال، وقبول الأمر، وتنفيذ الأثر، وإمكانية ملاحظته من جهة موثوقة.

فرّق بين أربع طبقات للنجاح

الطبقة الأولى هي نجاح الاتصال: DNS و TLS وإرسال الطلب واستلام استجابة. الثانية هي قبول الأمر وفق بروتوكول API؛ قد تعني 202 أن المعالجة ستحدث لاحقًا. الثالثة هي نجاح المعالجة داخل الخدمة المالكة للبيانات. الرابعة هي تحقق النتيجة التي يريدها المستخدم، مثل تغيير حالة طلب أو إنشاء فاتورة أو نشر محتوى. قد تنجح طبقة وتفشل أخرى. ضع لكل طبقة اسمًا وحالة مستقلة في سجل التشغيل. لا تختصرها في Boolean واحد اسمه success؛ فهذا يجعل التقارير تبدو مطمئنة بينما توجد مهام لم تصل إلى أثرها النهائي.

اقرأ دلالة HTTP 202 بدقة

توضح دلالة 202 Accepted أن الطلب قُبل للمعالجة لكن التنفيذ لم يكتمل بالضرورة، وقد لا يكتمل أصلًا. إذا أعادت الخدمة رابط حالة أو معرف Job، احتفظ به واستخدمه للاستعلام وفق سياسة مناسبة. لا تعامل 202 على أنه 201 Created، ولا تجعل إعادة إرسال الطلب هي الوسيلة الوحيدة لمعرفة النتيجة. حتى مع 200 قد يحمل جسم الاستجابة حالة أعمال مختلفة بحسب تصميم API، لذا اقرأ عقد الواجهة. وفي المقابل لا تفترض أن كل 5 xx يعني عدم تنفيذ الأثر؛ قد يكون الخطأ حدث بعد الكتابة وقبل إرسال الاستجابة.

حدد معيار الأثر قبل بدء المهمة

قبل استدعاء API اكتب النتيجة المتوقعة بصيغة قابلة للفحص: «الطلب رقم X أصبح shipped بعد إسناد رقم تتبع» أو «المقال رقم Y أصبح published بالنسخة Z». لا يكفي «استدعاء endpoint تحديث الطلب». حدد المصدر الذي يملك الحقيقة: قاعدة بيانات الخدمة الأساسية أو واجهة حالة موثوقة أو حدث مؤكد. إذا كان النظام موزعًا، اكتب مدة التأخير المقبولة قبل الحكم على النتيجة. تجنب اختبار النجاح بمراقبة شاشة قديمة تعتمد على Cache غير محدث. معيار الأثر ينبغي أن يعكس غرض المستخدم، لا تفاصيل تقنية داخلية فقط.

استخدم معرف ارتباط عبر الرحلة

أنشئ correlationId أو operationId يرافق الطلب عبر طبقات الأتمتة والخدمات والرسائل. اربط به معرف الطلب المنطقي ومفتاح عدم التكرار عند الحاجة. عندما تعود استجابة 202 احتفظ بمعرف المهمة البعيدة، ثم اربط نتائج الاستعلامات اللاحقة به. إذا كان هناك Webhook، تحقق من أنه يخص العملية نفسها ولا تعتمد على آخر حدث وصل. لا تضع معرفًا جديدًا لكل محاولة من دون ربطه بالعملية الأصلية. هذا الترابط يساعدك على تفسير اختلاف الأرقام بين سجل الوكيل وسجل الخادم، ويمنع احتساب محاولات إعادة الإرسال كإنجازات مستقلة.

صمم تحققًا بعد الكتابة

بعد استدعاء تحديث حالة سجل، اقرأ السجل من مصدر مناسب وتحقق من القيمة الجديدة ومن رقم الإصدار إن كان متاحًا. قد تعيد بعض الأنظمة استجابة قبل أن تظهر التغييرات في نسخة قراءة مؤجلة، لذلك حدد مهلة اتساق معقولة بدل إعلان فشل فوري. لكن لا تجعل الانتظار بلا نهاية؛ سجل حالة pending_verification عند انتهاء المهلة، مع إمكانية مصالحة لاحقة. إذا كانت العملية لا توفر واجهة قراءة، ابحث عن إقرار حدث موثق أو آلية تأكيد أخرى. لا تستخدم نجاح Toast في واجهة المستخدم بديلًا وحيدًا عن التحقق من حالة السجل.

متى تستخدم Polling ومتى تستخدم Webhook؟

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

احذر الاتساق النهائي بين الخدمات

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

مثال: نشر مقال عبر API

ترسل أداة تحرير أمر نشر مقال، وتستقبل HTTP 200. قد يكون المقال معتمدًا لكنه مجدولًا للمستقبل، أو منشورًا بنسخة أقدم، أو مستبعدًا من الفهرس. معيار النجاح الصحيح يتضمن articleId و publicationStatus و publishedVersion وموعد النشر، ثم تحققًا من الرابط العام عند حلول الموعد. إذا كان النشر مجدولًا، فالحالة الصحيحة الآن هي scheduled لا published. وإذا أُنشئت مواصفات صورة ولم يُستورد ملفها إلى مكتبة الوسائط، فلا يصح احتساب الصورة ضمن الإنجاز. المثال يوضح أهمية فصل حالة التحرير عن حالة العرض وعن ملفات الوسائط المرتبطة.

مثال آخر: إرسال طلب شراء

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

جدول الحالات المقترح

استخدم transport_failed عندما لم يثبت وصول الطلب، و accepted عندما أقر الطرف الآخر بالاستلام دون اكتمال، و processing عندما توجد مهمة جارية، و completed_verified عندما تحقق الأثر من مصدر مناسب، و failed_confirmed عندما ثبت الفشل، و unknown عندما لا تتوفر أدلة كافية. لا تحول unknown إلى failed فقط لتسهيل الرسم البياني. يمكن إضافة completed_with_warning إذا تحقق الأثر الأساسي وتأخرت طبقة ثانوية مثل فهرس البحث. كل حالة تحتاج انتقالات مسموحة ومسؤولًا عن التحقق التالي، حتى لا تظل الطلبات في حالة انتظار بلا نهاية.

اختبر الادعاءات في ظروف فشل واقعية

جهز اختبارًا يعيد 202 مع تأخير التنفيذ، واختبارًا يعيد 200 مع خطأ أعمال في الجسم، واختبارًا ينجح فيه الأثر ثم تضيع الاستجابة، وآخر يتأخر فيه تحديث فهرس القراءة. اختبر وصول Webhook مكررًا وانقطاع الاتصال قبل التحقق. قارن بين «عدد الطلبات التي استجابت بنجاح» و«عدد الآثار المؤكدة» و«عدد الحالات المجهولة». إذا اختلفت الأرقام فذلك ليس بالضرورة عيبًا في القياس؛ قد يكون دليلًا على حالات انتقالية يجب إظهارها. وثق مهلاتك ومصادر التحقق ولا تعد بإنجاز لا يمكنك إثباته.

المراجع والخلاصة

يوضح معيار HTTP Semantics دلالة 202 في https://www.rfc-editor.org/rfc/rfc9110.html ، وتقدم MDN شرحًا عمليًا في https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/202 . ولمفاهيم تتبع الرحلات راجع OpenTelemetry في https://opentelemetry.io/docs/concepts/signals/traces/ . اقرأ أيضًا دليل إيجي تاج عن تعطل الدفع واستعادة الطلب: https://egytag.com/ar/articles/ecommerce-payment-timeout-recovery-no-duplicate-charge-order-2026 ، ودليل سياسة إعادة المحاولة: https://egytag.com/ar/articles/كيف-تبني-retry-policy-مختلفة-للنقر-والتحميل-وطلبات-api . الخلاصة أن HTTP 200 شهادة على طبقة من الرحلة، أما النجاح الذي يهم المستخدم فيحتاج أثرًا موثقًا ومصدر حقيقة محددًا.