معالجة حالة «قيد التنفيذ» عند التحقق من الطلب عبر API

ماذا تعني processing في استجابة API

الحالة processing أو in_progress أو أي حالة مكافئة أخرى تعني أن المزوّد قبل الطلب للتنفيذ لكنه لم يثبّت النتيجة النهائية. بالنسبة لخدمات الترويج قد يكون ذلك التحقق من الرابط، أو انتظار الدور، أو بدء المهمة، أو التسليم التدريجي للحجم المطلوب.

لا تؤكد processing التنفيذ الناجح ولا تعني حدوث خطأ. بعدها قد ينتقل الطلب إلى completed أو partial أو canceled أو failed. طالما يعيد المزوّد حالة وسيطة، فلا تنشئ طلبًا جديدًا لنفس الرابط ونفس الحجم.

HTTP 200 مع حالة processing يعني استجابة API ناجحة، وليس إتمام الطلب بنجاح. يجب تخزين هذين الحدثين ومعالجتهما بشكل منفصل.

ما البيانات اللازمة للتحقق من الطلب

للـ polling تحتاج إلى المعرّف الخارجي للطلب الذي أعاده المزوّد عند الإنشاء. احفظه مع المعرّف الداخلي والحجم الأصلي ومعاملات الخدمة والرابط ووقت الإنشاء واستجابة API الأصلية. البحث عن الطلب بالاسم أو الرابط أو الحجم غير موثوق: قد تتطابق هذه القيم في عدة طلبات.

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

عيب تخزين الحالة الحالية فقط هو أنه عند النزاع يستحيل استعادة متى انتقل الطلب إلى processing، وهل كان هناك تقدّم، وما الاستجابات التي وصلت سابقًا.

مثال على طلب الحالة عبر curl

خذ العنوان الدقيق وطريقة التفويض وأسماء الحقول من وثائق المزوّد. فيما يلي قالب: القيم بين الأقواس الزاوية يجب استبدالها ببيانات API المحدد.

طلب GET لطلب واحد

curl -X GET "https:///orders//status" \

-H "Authorization: Bearer " \

-H "Accept: application/json"

مثال على الاستجابة:

{

"order_id": "",

"status": "processing",

"completed_quantity": 250,

"remains": 750,

"updated_at": "قيمة_الوقت"

}

الحقلان completed_quantity و remains مذكوران فقط كمثال على البنية. قد يستخدم المزوّد progress أو start_count أو balance أو أسماء أخرى. عيب نهج GET هو أن بعض واجهات API تقبل التحقق من الحالة عبر POST فقط.

مثال على طلب POST والتحقق الدفعي

طلب POST لحالة طلب واحد

curl -X POST "https:///orders/status" \

-H "Authorization: Bearer " \

-H "Content-Type: application/json" \

-d '{"order_id":""}'

لا تمرّر مفتاح API في سلسلة URL. عناوين الطلبات تصل إلى سجلات الوسيط وأنظمة التحليلات وسجل المتصفح والسجلات التقنية. عيب POST أنه أصعب في التحقق اليدوي عبر شريط العنوان، لكن هذا ليس سببًا لنقل السر إلى URL.

طلب دفعي للطلبات النشطة

إذا كان API يدعم التحقق الدفعي، أرسل عدة معرّفات في طلب واحد:

curl -X POST "https:///orders/statuses" \

-H "Authorization: Bearer " \

-H "Content-Type: application/json" \

-d '{"order_ids":["",""]}'

طابِق الاستجابة مع الطلب الداخلي بالمعرّف الخارجي، لا بموضع العنصر في المصفوفة. عيب التحقق الدفعي: قد لا يعيد المزوّد كل الطلبات، أو يحدّ من حجم القائمة، أو يبلّغ عن خطأ لمعرّف واحد فقط.

كيفية جدولة polling لـ processing

بعد أول استجابة processing ضع التحقق التالي في قائمة الانتظار. اختر الفاصل الزمني وفق وثائق API وحدود المعدل وطبيعة الخدمة. للمهام التي تتغير حالتها بسرعة يُقبل تحقق أكثر تكرارًا في البداية. للترويج التدريجي، الطلبات القصيرة المتكررة عادةً لا تعطي معلومات جديدة.

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

• بعد إنشاء الطلب لا تتحقق من الحالة فورًا مرات كثيرة متتالية: قد تحتاج الخدمة وقتًا لوضعه في قائمة الانتظار.
• عند تكرار processing زد الفاصل بين الطلبات، ولا تُبقِ ترددًا ثابتًا.
• أضف انحرافًا عشوائيًا صغيرًا إلى وقت تشغيل المهام حتى لا تستعلم الطلبات عن API في الوقت نفسه.
• إذا مرّر المزوّد Retry-After أو توصية مشابهة، فاستخدمها كأولوية.
• للطلبات التي لها webhooks أبقِ polling تحكميًا: قد لا يصل الإشعار.

عيب polling النادر أن الواجهة قد تعرض حالة قديمة بعد الإتمام الفعلي. عيب polling المفرط في التكرار هو خطر الاصطدام بحدود API وتلقي 429 وإنشاء حمل زائد.

ما الأوقات التي يجب حفظها لمراقبة processing

للتمييز بين التنفيذ العادي والتعليق لا تكفي حالة حالية واحدة. لكل طلب نشط احفظ وقت الإنشاء، وأول استلام لـ processing، وآخر استجابة API ناجحة، وآخر تغيير في الحالة الخارجية، وآخر تغيير في التقدّم.

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

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

ماذا تفعل إذا لم تتغير processing

processing الطويل لا يثبت وجود خطأ. تحقق أولًا مما إذا كانت استجابات API الناجحة قد وصلت، وهل تغيّر completed_quantity أو remains، وهل وصلت webhooks، وهل تغيّرت قواعد الخدمة. غياب النمو المرئي قد يكون بسبب تأخر إحصاءات المنصة أو لأن المزوّد يحدّث التقدّم في النهاية فقط.

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

• سجّل وقت آخر استجابة مؤكدة وكامل استجابة API.
• تحقق مما إذا تغيّر التقدّم منذ الاستعلام السابق.
• خفّض تردد الطلبات التلقائية بعد بلوغ العتبة الداخلية.
• مرّر إلى الدعم المعرّف الخارجي والرابط ومعاملات الخدمة وسجل الحالات والأخطاء التقنية.
• لا تُعد تشغيل المتبقي قبل رد المزوّد أو حالة نهائية واضحة.

عيب التحقق اليدوي أن الطلب يتطلب انتباه الدعم. لكن الإلغاء التلقائي أو التكرار أخطر: قد يستمر التنفيذ لدى المزوّد.

كيفية فصل فشل الطلب عن حالة الطلب

خطأ الشبكة والمهلة وHTTP 429 والاستجابة 5xx لا تخبر عن حالة الطلب نفسه. إنها تعني فقط أن الحالة الموثوقة الجديدة لم تُستلم. في هذه الحالة أبقِ آخر حالة مؤكدة، وسجّل الخطأ التقني، وجدول تحققًا جديدًا.

عند 429 راعِ Retry-After إن كان الترويسة مُمرّرة. عند أخطاء الشبكة المؤقتة و5xx زد التوقف بين المحاولات. عند خطأ التفويض أو التوقيع أو صلاحيات الوصول لا تُجرِ إعادات متكررة: يجب فحص المفتاح وصلاحية الرمز وقيود IP وإعدادات الوصول.

إذا أعاد API رمز HTTP 200 لكن JSON لا يُحلَّل أو لا توجد في الاستجابة order_id و status، فاحفظ جسم الاستجابة كاملًا وعلّم التحقق بأنه غير صحيح. لا تستبدل غياب الحالة بـ completed أو canceled أو processing.

متى تتوقف الطلبات التلقائية المتكررة

لا يجب أن يكون polling لا نهائيًا. حدّد عدد المحاولات التقنية للأخطاء المؤقتة وراقب بشكل منفصل المدة الإجمالية لبقاء الطلب في processing. بعد استنفاد حد المحاولات انقل مهمة التحقق إلى قائمة المراجعة، ولا تنشئ طلبات جديدة كل دقيقة دون نتيجة.

إعادة طلب الحالة آمنة عادةً إذا كانت الطريقة تقرأ البيانات فقط. طرق الإنشاء والإلغاء والتعبئة وإعادة التشغيل والإرجاع لا يجوز تكرارها آليًا بعد المهلة. بدون مفتاح idempotent أو تأكيد صريح من المزوّد، قد يغيّر هذا التكرار الطلب مرتين.

عيب تحديد المحاولات أن بعض التحديثات ستصبح مهمة يدوية. الإعادات اللانهائية أسوأ: فهي تخفي العطل وتستهلك الحدود وتُعقّد تحليل السجلات.

كيفية قبول الحالة النهائية بعد processing

امنع الانتقال العكسي من completed إلى processing بسبب استجابة polling متأخرة أو webhook قديم. عند كل تحديث قارن وقت الحدث من المزوّد، ورقم الإصدار إن وُجد، والحالة الداخلية الحالية.

• new و pending قد تنتقلان إلى processing أو canceled أو failed.
• processing قد تنتقل إلى completed أو partial أو canceled أو failed.
• partial لا يجب اعتبارها completed تلقائيًا.
• completed و canceled و failed تُعتبر عادةً نهائية وتمنع الرجوع التلقائي.
• الحالة غير المعروفة أو الانتقال غير المسموح يتطلبان فحصًا منفصلًا.

جدول الانتقالات الصارم له عيب أيضًا: قد يضيف المزوّد حالة جديدة صحيحة. لذلك احفظ الحالة الأصلية ولا تطمسها بالتصنيف الداخلي.

كيفية معالجة partial ومتبقي الطلب

partial تعني أن جزءًا فقط من الحجم الأصلي قد تأكد. قد تتضمن استجابة API الكمية المنفّذة فعليًا والمتبقي والسبب وبيانات التعويض. احفظ هذه القيم منفصلة: لا يجوز استبدال الحجم الأصلي للطلب بالكمية المنفّذة.

قد تبدو الاستجابة النهائية هكذا:

{

"order_id": "",

"status": "partial",

"completed_quantity": 700,

"remains": 300,

"refund": "قيمة_أو_غياب_الحقل"

}

حدّد أولًا ما يؤكده API بالضبط: هل تم الإرجاع فعليًا، أم أنه مجرد مخطط، أم أُلغي المتبقي، أم يلزم التواصل مع الدعم. إذا لم يوجد حقل الإرجاع، فلا تعتبر المتبقي معوَّضًا تلقائيًا.

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

webhooks لا تحل محل التحقق التحكمي

يتيح webhook تحديث بطاقة الطلب فور الحدث دون انتظار polling التالي. في المعالج ابحث عن الطلب بالمعرّف الخارجي، وتحقق من التوقيع أو السر، واحفظ معرّف الحدث، وطبّق الانتقال فقط بعد التحقق من جوازه.

يجب أن يكون التسليم المتكرر لـ webhook آمنًا: لا يجوز اعتبار الحدث نفسه تغييرًا جديدًا. قد تصل الأحداث أيضًا بغير ترتيبها، لذلك لا تُعِد الطلب النهائي إلى الوراء استنادًا فقط إلى processing متأخرة.

polling التحكمي مطلوب حتى مع webhooks مستقرة. عيب webhooks هو الإعداد الأكثر تعقيدًا: يتطلب معالجًا متاحًا وحماية من الطلبات المزيفة وإزالة التكرار وسجل أحداث.

ماذا تعرض للعميل عند processing والتعليق

في الواجهة لا حاجة لعرض كامل JSON التقني. بالنسبة لـ processing تكفي حالة «الطلب قيد التنفيذ». إذا مرّر API تقدّمًا موثوقًا، فاعرض الحجم المؤكد منفصلًا عن الأصلي ولا تقدّمه كنتيجة نهائية.

للطلب الذي تجاوز مهلة المراقبة الداخلية استخدم حالة مفهومة مثل «نتحقق من التنفيذ». لا تُبلّغ عن الإلغاء أو الإرجاع أو الإتمام الكامل حتى يؤكد ذلك رد المزوّد.

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

ما السجلات اللازمة في سجل المعالجة

يساعد سجل الاستجابات في تحليل processing المعلّق وwebhook المفقود والنزاع حول التنفيذ الجزئي والتباين بين الواجهة وAPI. لكل استدعاء احفظ المعرّف الخارجي ومصدر التحديث ووقت الطلب والاستجابة ورمز HTTP والحالة الأصلية والحالة المطبّعة والتقدّم والمتبقي ونص الخطأ التقني.

لا تكتب في السجلات العادية مفاتيح API والرموز والتواقيع والأسرار الأخرى. قيّد الوصول إلى الاستجابات الخام: قد تحتوي على بيانات لا يجب أن تظهر في واجهة الدعم.

قبل الإطلاق اختبر السيناريوهات ذات processing المتكررة وغياب التقدّم والمهلة و429 وخطأ 5xx وJSON غير الصحيح وwebhook المتأخر وwebhook المكرر وpartial وcanceled والحالة غير المعروفة. الوضع التجريبي مفيد لبنية التكامل، لكن عيبه أنه قد لا يحاكي قوائم الانتظار والتأخيرات الفعلية لـ API الإنتاجي.