کلید یکتای درخواست

مشکل

سایت شما فروش یک واحد را ثبت می‌کند و درست در همان لحظه اتصال قطع می‌شود. نمی‌دانید درخواست رسید یا نه. اگر تکرارش نکنید، شاید فروش ثبت نشده باشد؛ اگر تکرار کنید، شاید موجودی دو بار کم شود.

راه‌حل: `Idempotency-Key`

هر درخواست تغییر (POST، PUT، PATCH، DELETE) سرآیند Idempotency-Key لازم دارد؛ یک شناسه‌ی یکتا که خودتان می‌سازید.

برای هر تغییر یک کلید یکتا بسازید؛ بهتر است از کار خودتان ساخته شود، مثلا sale-ORD-58213-84780448، یا یک UUID.
درخواست را با همین کلید بفرستید.
اگر پاسخ نرسید، همان درخواست را با همان کلید دوباره بفرستید. اگر بار اول انجام شده بود، همان پاسخ اول دوباره برمی‌گردد و هیچ چیز دو بار انجام نمی‌شود.

POST /v1/stock/84780448/adjustments HTTP/1.1
Host: api.seller360.ir
Authorization: Bearer s360_live_...
Idempotency-Key: sale-ORD-58213-84780448
Content-Type: application/json

{ "quantity": -1, "reason": "sale", "reference": "ORD-58213" }

قواعد

قاعده	مقدار
طول کلید	۸ تا ۲۵۵ نویسه
مدت نگهداری پاسخ اول	۲۴ ساعت
دامنه	هر کلید برای همان کلید API؛ دو کلید API می‌توانند کلید یکتای یکسان داشته باشند

کد HTTP	خطا	یعنی
`400`	`idempotency_key_required`	تغییر بدون این سرآیند فرستاده شده است.
`409`	`idempotency_mismatch`	همین کلید قبلا با بدنه یا مسیر دیگری استفاده شده است.
`409`	`idempotency_in_progress`	درخواست قبلی با همین کلید هنوز در حال انجام است؛ چند ثانیه بعد تکرار کنید.