Skip to main content
الشبكات غير موثوقة. قد ينجح الطلب على الخادم لكن لا تصلك الاستجابة — فتبقى غير متأكّد إن كان عليك إعادة المحاولة. يزيل معرّف عدم التكرار هذا الخطر: تُرفِق مفتاحًا فريدًا بكل عملية كتابة، وتضمن الواجهة حدوث العملية مرة واحدة على الأكثر.

​
ترويسة Idempotency-Key

كل عملية POST (الفواتير والعملاء والأصناف وغيرها) تتطلّب ترويسة Idempotency-Key. وهي سلسلة فريدة يولّدها العميل وتُعرّف هذه العملية تحديدًا:
إذا غابت ترويسة Idempotency-Key، يُرفَض الطلب برمز HTTP 400. لا توجد قيمة افتراضية ضمنية.
استثناء واحد: الطلب POST /invoices/{id}/validate (ونظيره لإشعارات الخصم) فحص للقراءة فقط لا يغيّر شيئًا، لذلك لا يتطلّب ترويسة Idempotency-Key — استدعِه بحرّية أثناء تصحيح المسودّة.

​
اختيار المفتاح

  • اجعله فريدًا لكل عملية منطقية — مثلًا مفتاح واحد لكل فاتورة تنوي إنشاءها. يصلح كلٌّ من قيمة UUID أو معرّف عمل ثابت مثل invoice-2026-00042.
  • لا تُعِد استخدام مفتاح لعملية مختلفة. فالمفتاح هو ما يعتمده الخادم للتعرّف على التكرار.
  • ولّده على جهة العميل قبل المحاولة الأولى، وأعِد استخدام القيمة نفسها في كل إعادة محاولة للعملية ذاتها.

​
ماذا يحدث عند إعادة المحاولة

عندما ترسل طلبًا بمفتاح Idempotency-Key سبق أن عالجه الخادم، فإنه لا يُنشئ سجلًّا ثانيًا. بل يُعيد بأمان النتيجة الأصلية للطلب الأول:
1

الطلب الأول

ينشئ POST /invoices مع Idempotency-Key: invoice-2026-00042 الفاتورة ويُعيدها.
2

ضياع الاستجابة

تعني المهلة المنتهية أو الاتصال المقطوع أنك لم ترَ الاستجابة، فلا تعرف إن نجح الطلب.
3

إعادة المحاولة بالمفتاح نفسه

تُعيد إرسال الطلب ذاته تمامًا بنفس Idempotency-Key. تتعرّف الواجهة على المفتاح وتُعيد الفاتورة الأصلية — دون إنشاء أي نسخة مكرّرة.
تحمل الاستجابة المُعادة الترويسة Idempotency-Replayed: true لتميّزها عن تنفيذ جديد.
هذا يجعل إعادة المحاولة آمنة تمامًا. أعِد المحاولة دائمًا بالمفتاح نفسه بدلًا من توليد مفتاح جديد، وإلا اعتبره الخادم عملية جديدة كليًا وقد تُنشئ نسخة مكرّرة.
إعادة استخدام المفتاح مع جسم طلب مختلف تُرفَض برمز HTTP 409 Conflict — فالخادم يرفض التخمين أيّ نسخة قصدت. يجب أن تُعيد إعادةُ المحاولة إرسال الجسم نفسه تمامًا؛ أما العملية الجديدة فتحتاج مفتاحًا جديدًا. راجع الأخطاء.