عدم التكرار

أحيانا تقطع الشبكة الطلب ولا يتضح هل وصل أم لا. لإعادة POST دون تنفيذ العمل (ودفع ثمنه) مرتين، أرسل الترويسة Idempotency-Key: قيمة فريدة لكل عملية منطقية. معرّف UUID خيار جيد.

curl -X POST https://developers.grem.capital/api/v1/valuation/express \
  -H "Authorization: Bearer gsk_live_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3f1c8a90-1e2b-4c77-9a10-2b6d0f9e4a11" \
  -d '{"propertyCategory":"apartment","addressText":"Torstraße 12, Berlin","totalArea":64}'

كيف يعمل

• الطلب الأول بالمفتاح يُنفذ كالمعتاد، ويُحفظ رده الناجح.
• الإعادة بالمفتاح نفسه تعيد الرد المحفوظ: لا تعمل الأداة من جديد ولا يُخصم مرة أخرى.
• ما دام الطلب الأول قيد التنفيذ، يتلقى طلب ثان بالمفتاح نفسه 409 مع title: idempotency_conflict. انتظر وأعد المحاولة بالمفتاح نفسه.
• إذا انتهى الطلب الأول بخطأ يُحرَّر المفتاح: تُنفذ الإعادة من جديد. والطلب الذي لم يصل إلى الخدمة أصلا (رُفض الاتصال) يحرر المفتاح أيضا.
• بعد انتهاء مهلة (502 provider_error) أداة أو إنشاء عقار أو إنشاء عميل محتمل يبقى المفتاح محجوزا 15 دقيقة، كي لا تنفذ الإعادة العمل مرتين. تحقق من النتيجة قبل الإعادة: للأدوات GET /works، وللإنشاء GET /objects وGET /leads. نتائج تحسين الصور والموقع والمسودة لا تُحفظ في GET /works، فتحقق منها في لوحة التحكم أو بين عقاراتك. والإعادة بعد الدقائق الخمس عشرة تنفذ العمل (وتخصم ثمنه) مرة أخرى.
• الاستثناء هو التقييم السريع: بعد انتهاء المهلة يُحرَّر المفتاح، فأعده فورا بالمفتاح نفسه، ويُعاد التقييم المكتمل مجانا: لا يُخصم ثمن التقييم ولا استدعاء API مرة أخرى.
• يُحفظ المفتاح 24 ساعة ويرتبط بمفتاح API الخاص بك وبالعملية، أي بالطريقة والمسار الفعلي: القيم المتطابقة تحت مفاتيح API مختلفة، والمفتاح نفسه على أداة أخرى، وكذلك POST /objects/property وPOST /objects/rental، طلبات مختلفة.

أين يُطبق

في SDK يكون المفتاح آخر وسيط في الدالة.

مقالات ذات صلة

• الأخطاء: ما الذي يُعاد ومتى.
• الحدود والفوترة: ما الذي يُخصم.