Idempotency

لماذا هذا مهم

تفشل الشبكات في منتصف الطلب. إذا قمت بـ POST /v1/activations وانقطع الاتصال قبل أن ترى الاستجابة، فلن تعرف ما إذا تم إنشاء التفعيل. إعادة المحاولة الساذجة قد تُحاسبك مرتين.

رأس Idempotency-Key يحل ذلك: أرسل نفس المفتاح عند إعادة المحاولة، احصل على نفس النتيجة.

كيفية الاستخدام

أنشئ UUID لكل عملية منطقية، وأرسله مع كل إعادة محاولة لنفس العملية:

KEY=$(uuidgen)
curl -X POST https://api.eveses.com/v1/activations \
  -H "Authorization: Bearer $EVESES_API_KEY" \
  -H "Idempotency-Key: $KEY" \
  -d '{"country":"ua", "service":"telegram"}'

إعادة تشغيل نفس الاستدعاء بنفس Idempotency-Key يُرجع الاستجابة الأصلية — لا تفعيل ثانٍ، ولا فوترة ثانية.

TTL

تُحفظ المفاتيح لمدة 24 ساعة. بعد ذلك يتم تحرير الفتحة ويمكن إعادة استخدام نفس المفتاح كمفتاح جديد.

أين تنطبق

جميع نقاط POST /v1/* التي تنشئ أو تفوتر: التفعيلات، الإيجارات، الإيداعات، التمديدات. نقاط القراءة (GET) idempotent بالفعل وتتجاهل الرأس.

التعارضات

إذا أعدت استخدام نفس المفتاح مع body مختلف، تُرجع الـ API 409 idempotency_conflict. حافظ على body مطابقاً عند إعادة المحاولة، أو أنشئ مفتاحاً جديداً.

سلوك SDK

تُنشئ SDKs الرسمية مفاتيح idempotency تلقائياً لكل استدعاء إنشاء وتعيد استخدامها في إعادات المحاولة التلقائية. يمكنك التجاوز بمفتاح صريح إذا لزم.