توثيق الـ API

Idempotency وإعادة المحاولة

أعد أي طلب POST بأمان دون أن يُرسل الرمز أو يُخصم مرتين.

كل طلبات POST تقبل الترويسة Idempotency-Key: من 1 إلى 255 حرفاً مطبوعاً (ASCII بدون مسافات). استخدم قيمة فريدة لكل عملية، مثل رقم الطلب في نظامك.

curl -X POST https://watsy.me/v1/verify \
  -H "Authorization: Bearer $WATSY_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: signup-8841" \
  -d '{
    "phone": "07701234567"
  }'

القواعد

الحالة	النتيجة
نفس المفتاح ونفس الطلب خلال 24 ساعة	نعيد الرد المخزّن نفسه مع `Idempotent-Replayed: true`. لا إرسال ولا خصم جديد
نفس المفتاح مع مسار أو جسم مختلف	`409 idempotency_conflict`
نفس المفتاح والطلب الأول ما زال قيد التنفيذ	`409 idempotency_conflict`. أعد بعد لحظات
الطلب الأول فشل (أي خطأ)	لا يُخزَّن. يمكنك الإعادة بنفس المفتاح

البصمة تُحسب من الطريقة والمسار والجسم الخام حرفياً. أرسل نفس البايتات عند الإعادة.
المفاتيح خاصة بكل مشروع، وتنتهي بعد 24 ساعة.
إذا تعطل طلب ولم يكتمل خلال دقيقة، يُعتبر متروكاً ويمكن استخدام المفتاح من جديد.

مهم عند فحص الرمز

الرمز يُستهلك مرة واحدة. إذا ضاع رد POST /v1/verify/{id}/check بسبب الشبكة، أعد الطلب بنفس Idempotency-Key لتحصل على الرد الأصلي valid: true. بدون المفتاح سيرجع الفحص الثاني valid: false.