كيفية إعداد إشعارات إتمام طلبات API

ما الأحداث التي تُعد إتمامًا للطلب

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

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

أنشئ جدول مطابقة الحالات

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

• pending, created, queued — طلب جديد أو في انتظار المعالجة.
• processing, in_progress, running — الطلب قيد التنفيذ.
• completed, delivered, success — طلب منفَّذ.
• partial, partially_completed — طلب منفَّذ جزئيًا.
• cancelled, rejected, failed — طلب ملغى أو انتهى بخطأ.
• refunded, returned — طلب يتطلب إرجاعًا أو تسوية.
• حالة غير معروفة — لا تغيّر البطاقة تلقائيًا وتُحال إلى المراجعة.

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

اختر خطافات الويب أو استطلاع API أو كلا المخططين

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

• خطافات الويب مناسبة للتفاعل السريع: تحديث البطاقة، بدء المرحلة التالية أو إرسال رسالة إلى المسؤول.
• الاستطلاع مناسب إذا لم يدعم المزوّد إشعارات callback أو لم يقبل الخادم طلبات خارجية.
• المخطط المدمج يستخدم خطافات الويب كقناة أساسية، والاستطلاع للبحث عن الطلبات المفقودة أو المعلّقة.

عيب الاستطلاع هو التأخير والحمل الزائد على API. عيب خطافات الويب هو ضرورة حماية endpoint، ومراعاة التكرارات، وعدم الاعتماد على ترتيب تسليم الأحداث.

أعدّ endpoint لاستقبال الأحداث

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

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

قبل التشغيل تحقق من طريقة الطلب وتنسيق الجسم وفق الوثائق. غالبًا يكون POST مع JSON، لكن قد توجد form-data أو معاملات query أو مخطط تسلسل خاص. يجب تسجيل خطأ التحليل في السجل، وإلا سيكون من الصعب التمييز بين حمولة خاطئة وعطل في التطبيق.

احتفظ بالصلة بين الطلب والحدث

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

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

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

استخدم بنية حمولة واضحة

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

{

  "event_id": "evt_7f31",

  "event_type": "order.status_changed",

  "created_at": "2025-01-15T12:40:00Z",

  "data": {

    "order_id": "provider_order_4815",

    "external_id": "internal_order_9021",

    "status": "completed",

    "completed_quantity": 1000,

    "requested_quantity": 1000

  }

}

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

تحقق من التوقيع باستخدام جسم الطلب الأصلي

قد يتلقى عنوان URL المفتوح للمعالج طلبًا ليس من خدمة API فقط. إذا مرّر المزوّد توقيعًا أو سرًا أو رمزًا، فتحقق منها قبل تغيير الطلب. المخطط الشائع هو HMAC-SHA256: يحسب المزوّد التوقيع من بايتات جسم الطلب والسر المشترك، ثم يمرّر النتيجة في ترويسة HTTP.

مبدأ الحساب كالتالي: يُؤخذ جسم الطلب الأصلي، مثل بايتات JSON دون تغيير، والسر الخاص بالتكامل. ثم يُحسب HMAC-SHA256. إذا تطابقت النتيجة بصيغة سداسية عشرية مع قيمة الترويسة، فلم يتغير الجسم بعد التوقيع، والطلب على الأرجح أُرسل من جهة تعرف السر.

مثال افتراضي: HMAC_SHA256(السر, raw_body) = التوقيع من الترويسة X-Signature. يجب أخذ اسم الترويسة والخوارزمية وتنسيق النتيجة من وثائق API فقط. بعض الخدمات تضيف طابعًا زمنيًا أو معرّف حدث إلى السلسلة الموقَّعة. في هذه الحالة لا يمكن التحقق من جسم JSON وحده.

لا تغيّر JSON قبل التحقق من التوقيع

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

لتجنب ذلك، احصل أولًا على raw body كـ bytes أو buffer، واحفظه في الذاكرة، واحسب التوقيع، وبعد التحقق الناجح فقط حلّل JSON. لا تطبّق على الجسم trim أو تحويل الترميز أو فرز المفاتيح أو التنسيق. في middleware الإطار تحقق مما إذا كان JSON يُحلَّل تلقائيًا قبل الوصول إلى الجسم الأصلي.

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

مثال على معالج مع التحقق من HMAC

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

import hmac

import hashlib

import json

from hmac import compare_digest

def handle_webhook(request):

  raw_body = request.body

  received_signature = request.headers.get("X-Signature", "")

  secret = get_webhook_secret()

  expected_signature = hmac.new(

    secret.encode("utf-8"), raw_body, hashlib.sha256

  ).hexdigest()

  if not compare_digest(expected_signature, received_signature):

    log_invalid_signature(request)

    return response(status=401)

  payload = json.loads(raw_body.decode("utf-8"))

  return process_event(payload)

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

اجعل معالجة الأحداث خاملة (idempotent)

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

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

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

احفظ الحدث والحالة في عملية واحدة

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

الاستمرار الافتراضي للمعالج يبدو هكذا:

def process_event(payload):

  event_id = payload["event_id"]

  provider_order_id = payload["data"]["order_id"]

  new_status = map_status(payload["data"]["status"])

  with database_transaction():

    if event_exists(event_id):

      return response(status=200)

    order = find_order_by_provider_id(provider_order_id)

    if order is None:

      save_unmatched_event(event_id, payload)

      return response(status=200)

    apply_status_if_allowed(order, new_status, payload)

    save_processed_event(event_id, provider_order_id)

  enqueue_follow_up_actions(event_id)

  return response(status=200)

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

راعِ اختلال ترتيب الأحداث

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

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

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

أكّد التسليم بسرعة وانقل الإجراءات إلى قائمة انتظار

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

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

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

أعدّ إشعارات للفريق والعميل

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

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

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

احتفظ بسجل وطابق الطلبات غير المكتملة

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

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

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