إلغاء طلب API إذا أرسل العميل رابطًا غير صحيح

تحقق أولًا مما إذا كان الطلب قد أُرسل إلى المورّد

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

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

حدّد حالة الطلب لدى المورّد

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

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

عيب التحقق من الحالة الداخلية فقط هو أنها قد تتحدث بتأخير. اعتمد على آخر رد من API ووقت استلامه.

ألغِ الطلب قبل بدء الخدمة

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

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

عيب هذا الخيار هو أن المورّد قد لا يتمكن من إزالة الطلب من المعالجة في الوقت المناسب. عندها سيعيد الإلغاء رفضًا أو سيعمل فقط على الجزء غير المنفّذ.

لا تغيّر الرابط في طلب أُنشئ بالفعل دون تأكيد

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

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

عيب التعديل هو أنه حتى مع توفر الطريقة، قد تكون بعض الإجراءات قد ذهبت إلى الصفحة القديمة قبل التحديث. الرابط المصحّح لا ينقل النتيجة التي حُصل عليها بالفعل.

ماذا تفعل عند التنفيذ الجزئي

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

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

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

إذا اكتمل الطلب، فقدّم التصحيح كطلب منفصل

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

بعد ذلك هناك مسارَان: مناقشة التعويض مع المورّد وفق قواعده، أو إنشاء طلب جديد على الرابط الصحيح بعد الاتفاق مع العميل. يجب أن يكون للطلب الجديد معرّف منفصل ومبلغ وملاحظة واضحة عن سبب الإنشاء.

عيب التشغيل الجديد أنه يتطلب ميزانية إضافية، وقد لا يكون التعويض عن خدمة مكتملة متاحًا.

أبلغ العميل بالوضع قبل إعادة التشغيل

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

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

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

احفظ السجلات والأدلة الخاصة بالعملية

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

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

عيب الاحتفاظ اليدوي بالسجلات أنه يستغرق وقتًا. لكن بدون سجل يصعب تأكيد حالة الإلغاء وشرح للعميل لماذا لا يمكن استرداد المبلغ بالكامل.

تحقق من معالجة الأخطاء في التكامل

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

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

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

اضبط سيناريو إلغاء واضحًا للفريق

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

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

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