الطلبات الآمنة عند التكرار

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

أرسل الترويسة Idempotency-Key مع كل طلب POST وPATCH. وإذا كان Sursa قد رأى من قبل طلبًا بهذا المفتاح، فلا ينفّذ العملية مرة أخرى، بل يعيد الاستجابة التي حفظها في المرة الأولى.

curl -X POST https://api.sursa.com/v1/cards/text \
  -H "Authorization: Bearer $SURSA_API_KEY" \
  -H "Idempotency-Key: 6f1d2c9e-7b0a-4c43-9a51-0d6c1c1f8e21" \
  -H "Content-Type: application/json" \
  -d '{"title": "Refund policy", "body_markdown": "Refunds are processed within 14 days."}'

يحصل الطلب المكرر على الحالة والنص نفسيهما اللذين حصل عليهما الأول، مع ترويسة إضافية:

HTTP/1.1 200 OK
Idempotency-Replayed: true
X-Request-Id: 01JB7R…

وللطلب المكرر قيمة X-Request-Id خاصة به.

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

استخدم قيمة عشوائية جديدة، مثل UUID v4، لكل عملية منطقية: «أنشئ هذه البطاقة»، «سجّل خطاف الويب هذا». واستخدم القيمة نفسها لكل إعادة محاولة لتلك العملية، ولا تستخدمها أبدًا لعملية مختلفة.
المفتاح الجيد يُشتق من بياناتك حين تتوفر لديك، مثل sync-2026-10-24-record-1042. وعندها حتى مهمة المعالجة التي أُعيد تشغيلها وفقدت ذاكرتها ترسل المفتاح نفسه مرة أخرى.
يتكون المفتاح من 1 إلى 255 حرفًا من حروف ASCII القابلة للطباعة. وأي شيء آخر يعيد الحالة 400 مع الرمز api.idempotency_key_invalid.

ما يفعله Sursa بالمفتاح

الحالة	الاستجابة
الطلب الأول بهذا المفتاح	تُنفَّذ العملية كالمعتاد.
المفتاح نفسه والطلب نفسه، وانتهى الأول بالحالة `2xx` أو `4xx`	الاستجابة المحفوظة، مع `Idempotency-Replayed: true`. ولا تُنفَّذ العملية مرة أخرى.
المفتاح نفسه، والطلب الأول لا يزال قيد التنفيذ	الحالة `409` مع الرمز `api.idempotency_in_progress` والترويسة `Retry-After: 1`. انتظر ثم أعد المحاولة.
المفتاح نفسه، لكن بأسلوب أو مسار أو `Content-Type` أو نص مختلف	الحالة `409` مع الرمز `api.idempotency_mismatch`. فالمفتاح مستخدم من قبل لطلب آخر.
انتهى الطلب الأول بالحالة `5xx` أو `429`	يُحرَّر المفتاح: الطلب التالي به ينفّذ العملية مرة أخرى.

المفتاح صالح مدة 24 ساعة. وبعدها يبدأ المفتاح نفسه عملية جديدة.
المفاتيح منفصلة لكل مؤسسة ولكل مستدعٍ: يمكن لمفتاحَي API مختلفين استخدام القيمة نفسها دون أن يؤثر أحدهما في الآخر.
تُحفظ أيضًا استجابة الخطأ ذات الحالة 4xx. والطلب الذي فشل في التحقق من صحة البيانات يفشل بالطريقة نفسها عند تكراره بالمفتاح نفسه؛ أصلحه وأرسله بمفتاح جديد.

الطلبات التي تحتاج إليه

الأسلوب	الترويسة Idempotency-Key
الأسلوبان `POST` و`PATCH`	أرسلها. وكل نقطة نهاية تحفظ استجابتها للتكرار تذكر الترويسة في مرجع API.
الأساليب `GET` و`PUT` و`DELETE`	غير لازمة: تكرار هذه الأساليب آمن بطبيعتها. والترويسة مقبولة ولا أثر لها.
الطلب `POST` الذي يقرأ فقط، مثل البحث والتقارير المالية و`POST /v1/catalog/resolve`	مقبولة، لكن لا يُحفظ شيء: يُنفَّذ الطلب ببساطة مرة أخرى.

بعض العمليات آمنة عند التكرار حتى بلا الترويسة:

تنشئ العملية PUT /v1/cards-by-external-id/{external_id} البطاقة بمعرّفك أو تستبدلها؛ والتكرار بالمحتوى نفسه لا يغيّر شيئًا.
تُعرَّف مستندات المصدر المخصص بقيمة external_id الخاصة بك؛ وإرسال المستند نفسه مرة أخرى يعيد unchanged.
الإجابة المتدفقة من POST /v1/chat تستخدم الحقل request_id في نص الطلب بدل الترويسة. انظر بناء روبوت أسئلة وأجوبة.

إعادة المحاولة بأمان

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