Idempotency مُخطط
الأعطال الشبكية تحدث. إعادة المحاولة يجب ألا تخصم من العميل مرتين، ولا تضيف نقاطاً مكرّرة، ولا تُصدر استردادين لنفس الفاتورة. header Idempotency-Key يجعل إعادة المحاولة آمنة.
هذه الآلية مبنية لكنها لم تُربَط بعد بأي endpoint حيّ. وهي محجوزة لنقاط الكتابة المتزامنة القادمة — التحقق من الاستبدال وتأكيده وإلغاؤه، وفحص الإرجاع. أما الـ endpoint الوحيد الذي تستدعيه اليوم، POST /api/partner/v1/events، فهو آمن أصلاً لإعادة المحاولة: يمنع التكرار على eventId في الجسم (راجعأنواع الأحداث)، فلا يحتاجIdempotency-Key. توثّق هذه الصفحة كيف سيتصرف الـ header بمجرد إطلاق تلك النقاط.
آلية العمل
- ترسل طلباً مع header
Idempotency-Keyفريد. - ينفّذ قروش الطلب ثم يخزّن الاستجابة الكاملة (رمز الحالة + الجسم) مفهرَسة بـ
(apiKeyId, idempotencyKey)لمدة ٢٤ ساعة. - أي إعادة محاولة بنفس المفتاح تُعيد الاستجابة المخزّنة فوراً — منطق الأعمال يُنفَّذ مرة واحدة تماماً.
أي الاستجابات تُخزَّن؟
| فئة الحالة | تُخزَّن؟ | السبب |
|---|---|---|
2xx | نعم | نجاح — إعادة المحاولة يجب ألا تُكرّر الأثر. |
4xx | نعم | خطأ في طرف العميل — إعادة المحاولة بدون تغيير ستفشل بنفس الطريقة. |
422 | نعم | خطأ تحقق — نفس المدخل يُنتج نفس الفشل. |
5xx | لا | خطأ في الخادم — يُفترض أن تُعيد المحاولة، وقد تنجح. |
المفتاح الجيد فريد لكل عملية أعمال، لا لكل محاولة HTTP. لأحداث الكسب من فاتورة استخدم معرّف الفاتورة (INV-2026-000123) أو معرّف الحدث (ULID/UUID يُنتَج مرة واحدة في النظام المصدر). المفاتيح العشوائية لكل محاولة تُبطل الغرض.
قواعد المفتاح
- اسم الـ header:
Idempotency-Key. - الطول: من ١ إلى ٢٥٥ رمزاً.
- النطاق: لكل مفتاح API. شريكان يستخدمان نفس القيمة لا يتصادمان — الذاكرة مفهرَسة بـ
(apiKeyId, idempotencyKey). - المدة: ٢٤ ساعة من الطلب الأول. بعدها يمكن إعادة استخدام المفتاح.
المفتاح المُعاد استخدامه يُعيد تشغيل الاستجابة المخزّنة كما هي — حتى لو أرسلت جسماً مختلفاً. استخدم دائماً مفتاحاً جديداً لكل عملية جديدة؛ فإعادة استخدام مفتاح عبر طلبين مختلفين تُرجِع نتيجة الأول لا الثاني.
أي endpoints ستتطلبه؟
نقاط الكتابة المتزامنة القادمة — التحقق من الاستبدال وتأكيده وإلغاؤه، وفحص الإرجاع — ستكون مُلزِمة بالـ header؛ والطلب بدونه يُرفَض بـ 400 MISSING_IDEMPOTENCY_KEY. أما endpoint استقبال الأحداث فلا يستخدمه (يمنع التكرار على eventId).