POST /v1/reservations

scope

write_reservations

リクエストパラメーター

名前	位置	型	必須	説明
Idempotency-Key	ヘッダー	string	必須	冪等キー（必須・ADR-010）。UUID v4 推奨。同一キー再送は保存レスポンスを再生
item_id	ボディ	integer	必須
qty	ボディ	integer	必須
ttl_seconds	ボディ	integer	任意	予約の保持秒数（既定 900 = 15 分）。失効で自動 release

レスポンスの例

{
  "reservation_id": "string",
  "item_id": 0,
  "qty": 0,
  "status": "reserved",
  "expires_at": "string",
  "available": 0
}

解説

在庫を予約（仮押さえ）します。可否は原子判定され、在庫不足なら 409 sold_out を返します（売り越しは発生しません）。予約は ttl_seconds（既定 15 分）で自動失効し在庫が戻ります。Idempotency-Key ヘッダー必須：同一キーの再送は最初の結果を再生します。

エラーレスポンスの例

{
  "error": {
    "code": "insufficient_scope",
    "message": "requires scope 'read_orders'",
    "request_id": "req_01H..."
  }
}

返しうるエラー: 401 / 403 / 404 / 409 / 503