StardDevelopersداشبورد

Idempotency: تکرار امن درخواست

با هدر Idempotency-Key می‌توانی درخواست ثبت سفارش را بعد از قطعی شبکه بدون خطر خرید دوباره تکرار کنی.

چطور کار می‌کند

برای هر سفارش یک کلید یکتا (مثلاً شماره فاکتور خودت) در هدر Idempotency-Key بفرست. اگر همان درخواست با همان کلید دوباره برسد، Stard سفارش تازه نمی‌سازد و پاسخ قبلی را با هدر Idempotent-Replayed: true برمی‌گرداند.

curl -X POST "https://stard-market.ir/api/v1/orders" \
  -H "Authorization: Bearer $STARD_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-INV-1042" \
  -d '{"type": "product", "product_id": 4518}'

قواعد

  • کلید برای هر کلید API جداست و حداکثر ۶۴ کاراکتر از حروف، عدد و _-:..
  • همان کلید با بدنه‌ی متفاوت → 409 idempotency_key_reused.
  • اگر درخواست اول هنوز در جریان باشد → 409 request_in_progress؛ کمی بعد دوباره بفرست.
  • خطای ۵xx ذخیره نمی‌شود، پس تکرار با همان کلید امن است.