BASE API

API リファレンス / 商品

画像追加

指定した商品に画像を 1 枚追加します。 追加した画像は、表示順の末尾に並びます。

画像を追加するまでの手順は次のとおりです。

  1. POST /api/files に用途 item_image を指定して、アップロード先と file_id を取得します。
  2. 発行されたアップロード先に画像ファイルを送信します。
  3. このエンドポイントに file_id を指定します。

画像は 1 商品あたり最大 20 枚です。 上限に達している場合は追加できません。 また、次の場合も画像を追加できません。

  • file_id が無効な場合
  • ファイルがまだアップロードされていない場合
  • ファイルの中身が、アップロード先の発行時に宣言した形式と異なる場合
POST /api/items/{id}/images
スコープ items.readitems.update

リクエスト例

curl 
curl -X POST "https://apiv2.thebase.com/api/items/123/images" \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{
  "file_id": "string"
}'

パラメータ

id string · path 必須
商品 ID（1 以上の整数を文字列で表したもの）

リクエストボディ application/json

  • file_idstring必須1 文字以上 / 1024 文字以下
    追加する画像の参照。POST /api/files に用途 item_image を宣言して発行し、ファイル本体の送信を終えてから、返された file_id をそのまま指定します。内容を解釈せず、受け取った文字列のまま送ってください。

レスポンス

201 追加成功。追加された画像を返します。

201 のレスポンスボディ（application/json）:

  • idinteger必須≥ 0
    画像 ID
  • urlstring (uri)必須
    画像の公開 URL。アップロードされたままのサイズで返します。
  • scaled_urlstring (uri)必須
    縦横比を保ったまま幅を変えた画像の URL。幅 640px を指定した例です。URL に含まれる幅の値を変えると、任意の幅で取得できます。
  • square_urlstring (uri)必須
    中央を切り抜いて正方形にした画像の URL。一辺 900px を指定した例です。URL に含まれる寸法の値を変えると、任意の大きさで取得できます。

エラー

エラーは application/problem+json の Problem 形式で返します。 認証・スコープ・予期しない内部エラーなど、すべてのエンドポイントに共通のエラーと 構造・判別方法は エラーレスポンス を参照してください。

このエンドポイントが返すその他のエラーは次のとおりです。

400 /errors/request/malformed-body リクエストボディをこのエンドポイントが要求する形式として解釈できない場合に返します。
400 /errors/request/invalid-params 1 つ以上のパスパラメータがエンドポイントのスキーマを満たさない場合に返します。
400 /errors/items/invalid-body リクエストボディがエンドポイントのスキーマを満たさない場合に返します。
404 /errors/items/not-found 指定した商品が存在しない、または呼び出し元から参照できない場合に返します。1 リクエストで複数の商品を指定するエンドポイント（並び順の変更など）では、そのいずれかが参照できない場合に返します。
413 /errors/request/body-too-large JSON リクエストボディが 1 MiB の上限を超える場合に返します。
415 /errors/request/unsupported-media-type JSON 形式のリクエストボディを要求するエンドポイントに、対応していない Content-Type が指定された、または Content-Type が指定されていない場合に返します。
422 /errors/items/image-limit-exceeded 1 商品あたりの画像数が上限（20 枚）に達しているため画像を追加できない場合に返します。既存の画像を削除してから追加してください。
422 /errors/items/invalid-file-id 指定したファイルの参照が受け付けられない場合に返します。参照の期限が切れている、そのエンドポイントが受け取る用途と異なる用途で発行された、といった場合が該当します。`POST /api/files` で発行し直してください。
422 /errors/items/file-not-uploaded ファイルの参照は有効だが、ファイル本体がまだ送信されていない場合に返します。`POST /api/files` が返した `upload_url` へファイル本体を送信してから、あらためて指定してください。
422 /errors/items/file-content-mismatch 送信されたファイルの中身が、`POST /api/files` で宣言した形式と一致しない場合に返します。ファイルの中身は送信の時点では確認されないため、この確認はファイルを使うときに行われます。宣言した形式のファイルを送信し直してください。
422 /errors/items/write-rejected 商品の作成・編集・削除を業務ルールにより実行できない場合に返します (型整合性違反、種別不可変、ドメイン制約違反など)。細分化された Problem type に対応しない理由のときに返します。
502 /errors/internal/bad-gateway BASE API が処理を完了するために必要な内部処理で不整合が発生した場合に返します。
504 /errors/internal/gateway-timeout BASE API が処理を完了するために必要な内部処理が制限時間内に完了しなかった場合に返します。