POST /v1/reservations

Scope

write_reservations

Request parameters

Name	In	Type	Required	Description
Idempotency-Key	header	string	required	冪等キー（必須・ADR-010）。UUID v4 推奨。同一キー再送は保存レスポンスを再生
item_id	body	integer	required
qty	body	integer	required
ttl_seconds	body	integer	optional	予約の保持秒数（既定 900 = 15 分）。失効で自動 release

Response example

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

Description

在庫を予約する（原子可否判定・売り越しゼロ）(write_reservations)

Error response example

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

Possible errors: 401 / 403 / 404 / 409 / 503