v1 API からの移行ガイド

従来の BASE API（https://api.thebase.com の /1/ 系エンドポイント。以下 v1）から、新しい BASE API（https://apiv2.thebase.com の /api/ 系。以下 v2）への移行に必要な変更点をまとめます。v2 は v1 の後継として設計し直した API で、URL の書き換えだけでは移行できません。認証、エラー、データ表現といった共通の変更に加えて、リソースごとにエンドポイントとフィールドの対応が変わります。このガイドが扱うのは v1 にある機能の差分だけで、v2 で新たに追加された機能は扱いません。v2 の機能一覧はAPI リファレンスを参照してください。

v2 で未対応の機能

次の機能は v2 のβ版には含まれません。これらの機能は引き続き v1 で利用できます。

• OAuth 2.0 の認可フロー（/1/oauth/authorize / /1/oauth/token）
• 商品検索 GET /1/items/search
• 引き出し申請情報 GET /1/savings

OAuth 2.0 による認証と引き出し申請関連の API は、正式リリースに合わせて提供する予定です。 商品検索 API に相当する API の提供予定はありません。

共通の変更点

URL とリクエスト形式

URL は https://apiv2.thebase.com/api/items のように、パスの prefix を /api とします。api.thebase.com は v1 のまま残り、v2 のエンドポイントは提供しません。各エンドポイントのパスとメソッドはAPI リファレンスを参照してください。

認証とトークン

v1 は OAuth 2.0（authorization_code / refresh_token グラント）のアクセストークンを使い、トークンの有効期限は 1 時間でした。v2 の初期リリースでは OAuth フローを提供せず、Personal Access Token のみでアクセスします。Personal Access Token は BASE Developers の「API」タブから発行します。リクエストヘッダーは v1 と同じ Authorization: Bearer <token> です。トークンの取得と更新のためのコード（認可リダイレクト、/1/oauth/token の呼び出し、リフレッシュ処理）は不要になります。

curl -H "Authorization: Bearer <your-token>" \
  https://apiv2.thebase.com/api/user

スコープ

スコープは Personal Access Token の発行時に選びます。v2 のスコープは v1 より細かく、リソースの読み取りと書き込みの 2 択ではなく、作成、更新、削除、公開、発送、キャンセルといった操作ごとに分かれています。v1 の write_items や write_orders で一括して許可していた操作のうち、削除や公開、発送やキャンセルのような影響の大きい操作は、それぞれ別のスコープとして選ぶ必要があります。v1 のスコープに対応する v2 のスコープは次のとおりです。一覧はスコープを参照してください。

v1 でスコープ不要だった GET /1/users/me と GET /1/delivery_companies に相当する v2 エンドポイントは、それぞれ user.read と orders.read を要求します。トークン発行時に必要なスコープを含めてください。

エラーレスポンス

v2 のエラーは、事象に応じたステータスコード（認証エラーは 401、スコープ不足は 403、対象なしは 404 など）と、RFC 9457 (Problem Details) に沿った application/problem+json のボディで返します。v1 から形式が変わっていることに注意してください。存在しない商品の詳細を取得したときの応答を比べると、次のようになります。

v1

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
  "error": "no_item",
  "error_description": "商品が見つかりませんでした。"
}

v2

HTTP/1.1 404 Not Found
Content-Type: application/problem+json

{
  "type": "/errors/items/not-found",
  "title": "Item not found",
  "status": 404
}

type はエラー種別ごとに固定の識別子、title はその英語の短い要約で、事象によっては開発者向けの説明 detail や、バリデーションエラーのフィールド単位の詳細 errors が加わります。v1 の error 値で分岐しているコードは、ステータスコードと type による分岐に書き換えてください。構造とエラー種別の一覧はエラーレスポンスを参照してください。

データ表現

日時は形式だけでなく基準も変わります。v2 の値はタイムゾーンが Z（UTC）で明示されるため、日本時間で表示する場合は利用側で変換してください。

エンドポイント対応表

v1 の各エンドポイントと v2 の対応です。各エンドポイントの仕様はAPI リファレンスを参照してください。

商品の移行

レスポンス構造の変更

v1 の item はフラットなオブジェクトに画像キー（img1_origin など）を並べた構造でした。v2 の商品詳細は、商品種別（type）ごとに構造が分かれ、画像、種類、カテゴリ、オプションを同じレスポンスの配列として含みます。また、v1 では別エンドポイント（GET /1/item_categories/detail/:item_id）だった所属カテゴリも含まれます。

商品種別は type フィールド（normal / digital / takeout / subscription / lottery）で判別します。種別固有の設定（デジタルコンテンツ、定期便、抽選販売）は該当種別のときだけ、同名のフィールドに入ります。digital（デジタルコンテンツ）は読み取りのみで、作成と編集の type には指定できません。v2 では販売状態を表す sales_status（販売開始前、販売中、販売終了後）が追加されています。

フィールド対応表

画像の表現

v1 の商品詳細は、20 枠 × 8 サイズの画像キー（img1_origin, img1_76, … img20_sp_640）を未設定分の null も含めて常に返していました。v2 は登録済みの画像だけを images 配列で返します。

// v1
{
  "img1_origin": "https://.../foo.jpg",
  "img1_76": "https://.../foo_76.jpg",
  "img2_origin": null,
  ...
}

// v2
{
  "images": [
    {
      "id": 123,
      "url": "https://.../foo.jpg",
      "scaled_url": "https://.../foo.jpg?width=640",
      "square_url": "https://.../foo.jpg?width=900&height=900"
    }
  ]
}

固定サイズのキーを選ぶ代わりに、scaled_url / square_url の URL に含まれる寸法の値を書き換えて必要なサイズを取得します。v1 の 8 サイズに対応する固定キーはありません。

商品の作成と公開

v1 の POST /1/items/add は visible を受け付け、省略時は公開（1）で作成しました。v2 の POST /api/items は visible を受け付けず、作成した商品は常に非公開（visible: false）です。公開するには、作成後に PUT /api/items/{id}/visibility で visible を true にしてください。このエンドポイントには items.publish スコープが必要です。作成と同時に公開していた実装は、作成と公開の 2 回の呼び出しに書き換えてください。編集 POST /api/items/{id} でも visible は受け付けないため、公開状態の変更は常に PUT /api/items/{id}/visibility で行います。

画像の追加

v1 の POST /1/items/add_image は画像の URL（image_url）を受け取る API でした。v2 は画像の URL を受け取らず、利用者がファイル本体を送信し、その参照を商品に紐付ける 3 段階になります。

1. POST /api/files に用途 item_image と content_type を送り、送信先（upload_url と upload_fields）とファイルの参照（file_id）を取得
2. upload_url へ、upload_fields のすべての項目とファイル本体を multipart/form-data で送信
3. POST /api/items/{id}/images に { "file_id": "..." } を送り、商品の末尾に画像を追加

1 段階目の POST /api/files には files.write スコープが必要です。2 段階目の送信先は BASE API ではなくファイルの保管先です。URL を渡すだけで画像を登録していた実装は、画像を自分で取得して送信する形に書き換えてください。image_no による位置の指定はなくなり、追加した画像は常に末尾に並びます。位置を変えるには PUT /api/items/{id}/images に image_ids を表示順で送ります。1 商品あたりの上限は v1 と同じ 20 枚です。

注文の移行

一覧から検索へ

v1 の一覧 GET /1/orders は、v2 では POST /api/orders/search になります。期間、キーワード、状態などの条件を JSON ボディで渡し、レスポンスは注文の概要（orders）とページ情報（pagination）を返します。概要に含まれない明細や金額内訳は、unique_key で詳細 GET /api/orders/{unique_key} を取得してください。

詳細レスポンスの構造変更

v1 の注文詳細はトップレベルに多数のキーを平らに並べていましたが、v2 は関連する情報をオブジェクトに集約されています。v2 の注文詳細の骨格と、各オブジェクトに入る v1 のキーは次のとおりです。

{
  "unique_key": "...",
  "status": "...",
  "ordered_at": "...",

  // 購入者。v1 の first_name / last_name / mail_address と住所の各キー
  "customer": { "name": { ... }, "mail_address": "...", "address": { ... } },

  // 配送先。v1 の order_receiver
  "shipping": { "name": { ... }, "address": { ... } },

  // 金額の内訳。v1 の shipping_fee / cod_fee / total / order_discount / order_header_coin など
  "amounts": { "subtotal": 0, "shipping_fee": 0, "cod_fee": 0, "total": 0, "coupon_discount": { ... }, ... },

  // 商品明細。v1 の order_items
  "lines": [ { ... } ],

  // 発送。v1 の delivery_company_id / tracking_number / dispatched など
  // dispatches は v1 で別エンドポイントだった部分発送履歴
  "delivery": { "delivery_company_id": 0, "tracking_number": "...", "dispatched_at": "...", "dispatches": [ ... ] },

  // 決済。v1 で決済手段ごとに分かれていたキー
  "payment": { "method": "...", "transactions": [ ... ] },

  // ショップ用メモ。v1 では別エンドポイント
  "shop_memo": { "text": "..." },
  ...
}

lines の 1 要素は、ある商品（種類）を N 個購入した 1 明細です。amounts.total は v1 の total と同じく割引相殺後の最終額です。

フィールド対応表

移行時の注意

v1 では order_receiver が無いとき「配送先 = 購入者」とみなすフォールバックが必要でしたが、v2 は shipping を常に返すので不要です。あわせて、order_receiver の有無で「お届け先が購入者と同じか」を判定する方法も成り立たなくなります。customer.address と shipping.address を比較して判定してください。

税区分は名前と値の両方が変わります。v1 の item_tax_type: 1 は「税率 1%」ではなく「標準税率対象」の意味でした。v2 では名前が tax_mode、値が "standard" / "reduced" になります。実際の税率は consumption_tax_rate を参照してください。

status の値体系は v1 と同じです。v1 の dispatch_status の値を文字列のまま引き継ぎます。v1 で廃止済みの値（shipping / arrived など）は v2 でも返りません。

customer.mail_address の未登録は v1 と同じく空文字です。null チェックではなく空文字チェックを使ってください。

カテゴリの移行

v1 ではカテゴリ本体が /1/categories、商品との紐付けが /1/item_categories と別リソースでした。v2 はカテゴリ本体を /api/item_categories に置き、商品との紐付けはその配下（/api/item_categories/{id}/items/{item_id}）で操作します。v1 の POST /1/categories/edit は name と list_order を同時に受け付けましたが、v2 では表示名を POST /api/item_categories/{id}、並び順を PUT /api/item_categories/{id}/list_order で個別に変更します。並び順は数値ではなく、同じ親を持つカテゴリの先頭、末尾、または指定したカテゴリの直前、直後として指定します。

商品に紐付いたカテゴリの取得（v1 の GET /1/item_categories/detail/:item_id）は、商品詳細 GET /api/items/{id} の categories フィールドに統合しました。紐付け ID（item_category_id）の取り回しは不要になり、カテゴリ ID と商品 ID の組み合わせで紐付けを操作します。

v1 の /1/categories 系エンドポイントは、呼び出すとショップのカテゴリ機能が有効になりました。v2 のエンドポイントを呼び出しても有効にはなりません。

ショップ情報の移行

GET /1/users/me は GET /api/user になります。スコープ不要だった v1 と異なり、user.read スコープが必要です。

配送会社の移行

GET /1/delivery_companies は GET /api/delivery_companies になります。スコープ不要だった v1 と異なり orders.read スコープが必要です。レスポンスの delivery_company_id は id に改名しています。取得した id は v1 と同じく発送登録（POST /api/orders/{unique_key}/dispatch）で使います。