メインコンテンツまでスキップ

POST /v1/items/{id}/images

scope​

write_items

リクエストパラメーター​

名前位置型必須説明
idパスinteger必須
Idempotency-Keyヘッダーstring必須冪等キー（必須・ADR-010）
source_urlボディstring必須画像の取得元 URL（https のみ・jpeg/png・2MB まで。実バイトで MIME 判定）
typeボディenum(mainadditional)任意
orientationボディenum(landscapesquare)任意

レスポンスの例​

{
  "item_id": "string",
  "type": "main",
  "key": "string",
  "url": "string",
  "sort": 0,
  "orientation": "landscape"
}

解説​

商品画像を URL 指定で登録・差し替えます。source_url（https のみ）から画像を取得し、実バイトで JPEG / PNG を判定（拡張子ではなく中身で検証・2MB まで）して既存の商品画像ストレージに保存します。type: main はメイン画像の差し替え（orientation で向きも変更可）、type: additional は追加画像として末尾に追加されます。画像を設定すると商品を active（公開）にできるようになります。Idempotency-Key 必須。

エラーレスポンスの例​

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

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