منع التكرار
أعِد إرسال طلبات POST بأمان باستخدام ترويسة Idempotency-Key دون إنشاء مدفوعات أو استردادات مكررة.
الشبكات تتعطل أحيانًا. إذا انتهت مهلة طلب إنشاء دفع أو استرداد، فلن تعرف إن كانت تيرا باي قد استلمته. أرسل ترويسة Idempotency-Key وستستطيع إعادة الطلب نفسه بأمان، إذ تنفّذه تيرا باي مرة واحدة على الأكثر.
curl https://api.teyra.co/v1/payments \
-H "Authorization: Bearer $TEYRA_SECRET_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order-1042-attempt-1" \
-d '{"amount": 12500, "currency": "KWD", "return_url": "https://shop.example.com/thanks"}'كيف يعمل
يقبل كل طلب POST /v1/* هذه الترويسة، وقيمتها أي نص طوله بين حرف واحد و255 حرفًا، وإلا فشل الطلب بالخطأ 422 validation_error.
| ما ترسله | ما تعيده تيرا باي |
|---|---|
| مفتاح جديد | تنفّذ الطلب وتحفظ الاستجابة مع المفتاح. |
| المفتاح نفسه والطلب نفسه (المسار والجسم) | الاستجابة المحفوظة (الحالة نفسها والكائن نفسه) مع الترويسة Idempotent-Replayed: true. لا يُنشأ شيء مرتين. |
| المفتاح نفسه وطلب مختلف | 409 idempotency_conflict. |
| المفتاح نفسه بينما الطلب الأول لا يزال قيد التنفيذ | 409 conflict. أعِد المحاولة بعد قليل بالمفتاح نفسه. |
المفاتيح خاصة بحسابك وبالوضع (اختبار/حي)، وتُحفظ لمدة 24 ساعة. لا تُحفظ الاستجابات ذات الرموز 409 و429 و5xx، لذا تُنفَّذ إعادة المحاولة بالمفتاح نفسه من جديد. أما استجابات 4xx الأخرى، مثل 422 validation_error، فتُحفظ كما تُحفظ الاستجابات الناجحة.
اختيار المفاتيح
- اشتق المفتاح من معرّفاتك أنت ليبقى ثابتًا بين المحاولات:
order-1042-attempt-1أوrefund-order-1042-item-3، أو UUID تحفظه مع الطلب قبل استدعاء الـ API. - استخدم مفتاحًا جديدًا لكل عملية جديدة فعلًا، مثل محاولة العميل الدفع مجددًا بعد فشل الدفع:
order-1042-attempt-2. - لا تُعِد استخدام مفتاح لطلب مختلف، فتغيير الجسم مع المفتاح نفسه يُرفض.
متى تعيد المحاولة
| الحالة | أعِد المحاولة بالمفتاح نفسه؟ |
|---|---|
| انتهاء المهلة أو خطأ في الاتصال | نعم |
429 rate_limited | نعم، بعد تأخير |
500 internal_error و502 gateway_error | نعم، بعد تأخير |
أخطاء 4xx في التحقق أو المصادقة | لا. صحّح الطلب أولًا، والطلب المصحَّح يحتاج مفتاحًا جديدًا لأن جسمه تغيّر. |
استخدم تأخيرًا متصاعدًا، مثل ثانية ثم 2 ثم 4 ثم 8 ثوانٍ، مع قدر بسيط من العشوائية.
طلبات GET وDELETE آمنة من التكرار بطبيعتها ولا تحتاج هذه الترويسة.