# コマースAPIのユースケース:ウィジェットでは作れない7つのビルド

> ストアフロントのウィジェットが合わない場面:SaaS組み込みコマース、マルチサーフェスのカタログ、ホワイトラベルストア、独自UX、AIエージェント、独自BI。Shoprocket JS SDKのコード例も紹介します。

Ryan Badger - 2025年8月4日 - 読了目安 5 分

## 組み込み向けEコマースAPIは何のためにあるのか

多くのEコマースプラットフォームが提供するのはウィジェットです。スクリプトを貼れば、ストアフロントができあがります。ストアの95%はこれで問題なく回ります。

コマースAPIの出番は、ウィジェットではできないことをしたいときです。自社のUIの中に商品を表示する、SaaSのダッシュボードにチェックアウトを組み込む、カタログを複数のサーフェス(Web、モバイル、音声)に配信する、どのプラットフォームも標準では用意していない独自の購入フローを作る、といったケースです。

Shoprocketは両方を提供しています。デフォルトは[ウィジェット](https://v3.shoprocket.io/ja/blog/headless-commerce-the-three-tiers-the-real-options-and-which-one-you-probably-actually-want.md)です。ウィジェットでは足りなくなったとき、あるいは最初からウィジェットが不要なときに使うのが、[`@shoprocket/core` SDK](https://github.com/shoprocket/shoprocket-js)です。

## ウィジェットではなくAPIが必要になるユースケース

ウィジェットでは足りないビルドを挙げます。あなたのアイデアがこの中にあれば、API領域に入っています。

### 1. SaaSプロダクトの中にコマースを組み込む

SaaSのダッシュボードには、すでに独自のUIがあります。そこで、アドオン、クレジットパック、上位プラン、物理的なグッズなどを、アプリを離れずに購入してもらいたい場合です。

ウィジェットは形が合いません。ユーザーのことを知らず、デザインシステムにも馴染まず、ページ全体のストアフロントを前提にしているからです。APIを使えば、自社のコンポーネントで商品カードを描画し、ボタンのクリックで `cart.addItem()` を呼び、自前のチェックアウトパネルを開けます(コンプライアンス対応を先送りしたいなら、ホスト型チェックアウトにリダイレクトする手もあります)。

```
import { ShoprocketCore } from '@shoprocket/core'

const sr = new ShoprocketCore({ publicKey: 'pk_...' })

// SaaSダッシュボード内にアドオンのタイルを描画する
const addons = await sr.products.list({ category: 'addons' })

// ユーザーが「クレジットを追加」ボタンをクリックしたとき
await sr.cart.addItem(addon.id, 1)
```

### 2. マルチサーフェスのカタログ(Web、ネイティブアプリ、音声、チャット)

商品カタログは1つで、表示のしかたは場所ごとに変わります。Webのストアフロントでは商品の詳細をすべて見せ、ネイティブのiOSアプリでは簡潔な一覧にし、音声アシスタントは商品を読み上げ、チャット連携は購入できるリンクを返します。

4つのサーフェスはどれも同じAPIを呼びます。Shoprocketのダッシュボードで商品の価格を更新すれば、次回の取得ですべてのサーフェスに反映されます。サーフェスごとにコンテンツを同期する必要はありません。

### 3. ホワイトラベル / パートナーのストアフロント

他の人が商品を販売するプラットフォームを運営している場合です。コミュニティのマーケットプレイス、パートナーのディレクトリ、個々のディーラーがサイトを持つフランチャイズ網などが当てはまります。各パートナーが使うのは、御社ではなくパートナー自身のブランドです。

各パートナーのサイトは御社のフレームワークで動き、そのパートナーの `publicKey` でコマースAPIを呼び出します。商品も注文も支払いもアカウントごとに分離されます。ウィジェットがパートナーのブランディングの邪魔をすることもありません。

### 4. 完全にオリジナルの購入体験

インタラクティブな商品コンフィギュレーター(カスタムPC、パーソナライズジュエリー、受注生産の家具)。3D商品ビューア。画像の一部をクリックするとその商品がカートに入る「ルームをまるごとショップ」型のフォトギャラリー。メールの中で使えるクイック再注文ボタン。

ウィジェットにこれらはできませんが、APIならできます。デザイナーが思い描いたUIをそのまま描画し、コマースの仕組みはAPIが裏で処理します。

### 5. AIエージェントとエージェント型コマース

ユーザーに代わって商品を探し、購入まで完了するAIエージェント(ChatGPT、Claude、自作のエージェントなど)です。エージェントに必要なのは、カタログとカートへのプログラムからのアクセスであって、解析しなければならないDOMウィジェットではありません。

Shoprocketは、標準のAPIアクセスに加えて、AIコマースプロトコル向けのフィードも提供しています。エージェントが「在庫があって、50ドル以下で、送料無料の商品は?」と尋ねたとき、画面をスクレイピングするのではなく、構造化された答えが返ります。

### 6. コンテンツツールへのコマース組み込み

購入できるブロックを置けるNotionのページ。クリックで購入できるホットスポットを持つFramerのデザイン。購読者がメールを離れずに商品カードをタップして支払えるニュースレターツール。どれもAPIの上に作られます。

### 7. 独自のレポートとBIダッシュボード

Shoprocketのダッシュボードには、売上、コンバージョン、売れ筋商品が表示されます。表示されないのは*あなた独自の*指標です。顧客コホート別のLTV、流入元ごとの注文数、仕入れ原価を引いたあとの利益率などです。APIは注文と顧客のデータを公開しているので、自社のBIツール、スプレッドシート、社内ダッシュボードに流し込めます。

## 現時点でSDKにできること

`@shoprocket/core` の例です。

```
// Products
sr.products.list({ limit, offset, sort, category })
sr.products.get(productId)

// Cart
sr.cart.get()
sr.cart.addItem(productId, quantity)
sr.cart.updateItem(itemId, quantity)
sr.cart.removeItem(itemId)

// Session
sr.session.create()
sr.setSessionToken(token)
```

SDKがまだラップしていないもの(注文、顧客、割引、商品の書き込み)には、フルのREST APIを使えます。完全なリファレンスは[api.shoprocket.io/docs](https://api.shoprocket.io/docs)をご覧ください。

## APIファーストが間違いになる場面

ウィジェットが正解で、APIは大げさすぎるケースがいくつかあります。

- **商品数が10〜200点程度のシンプルなストアフロント。** ウィジェットで十分きれいに表示できます。自前でカタログUIを書くのは、解決済みの仕事をやり直すことです。
- **フロントエンド専任のエンジニアリング体制がない。** APIファーストでは、ローディング状態、バリエーションのUI、エラー処理、アクセシビリティ、21ロケール分のi18nを、自分で作って保守する必要があります。ウィジェットなら、数週間分のその作業が最初から含まれています。
- **最優先事項がローンチの速さ。** ウィジェットなら数分、APIファーストなら最低でも数週間かかります。

基本はウィジェットです。ウィジェットでできないことにぶつかったときに、APIに手を伸ばしてください。

## 現実的な最初のプロジェクト

「APIが必要だ」となるプロジェクトで最も多いのは、自社のダッシュボードの中でクレジット、サブスクリプション、単発のアドオンを販売したいSaaSプロダクトです。

進め方は次のとおりです。

1. フロントエンドに `@shoprocket/core` をインストールする
2. Shoprocketに「アドオン」などのカテゴリを作る
3. 希望どおりの価格と説明で商品を追加する
4. 自社のコンポーネントライブラリで、ダッシュボードに商品リストを描画する
5. クリックされたらカートに追加し、Shoprocketのホスト型チェックアウトにリダイレクトする(追加の作業が苦にならなければ、チェックアウトをインラインで埋め込んでも構いません)
6. `order.paid` イベントを受け取るWebhookエンドポイントを設定し、購入で解放されるもの(クレジット、アクセス権、出荷)を付与できるようにする

以上です。必要なのは数ファイルで、APIの呼び出しに慣れた人なら1日で済みます。ウィジェットもiframeも使わず、プロダクトのUIに妥協はありません。

## おすすめしないこと

ウィジェットがすでにやっていることとそっくりなカタログUIを、一から作り直すのはやめましょう。「フィルターと検索付きの商品グリッド」に何週間もかけているなら、ウィジェットが数分で提供するものを自作しているだけです。その形ならウィジェットを使い、本当に違う形のときだけAPIを使ってください。

> **ヒント:**ウィジェットの標準スタイルがブランドに合わないという理由でAPIファーストを考えているなら、まず[ウィジェットのスタイリングフック](https://github.com/shoprocket/shoprocket-js)を試してください。ウィジェットは、見た目以上に幅広いCSSのカスタマイズに対応しています。APIで全面的に作り直すのは、はるかに大きな負担です。

## 要点

- **ウィジェット** はデフォルトで、ストアの95%をカバーします
- **API / SDK** は、ウィジェットが合わないとき(SaaS組み込みコマース、マルチサーフェス、ホワイトラベル、独自UX、AIエージェント、独自BI)に使います
- **現在のSDKの範囲:** 商品、カート、セッション。注文 / 顧客 / 割引はフルのREST APIで扱えます
- **最初のプロジェクトの型:** SDKとWebhook駆動の付与処理で、SaaSのダッシュボードからクレジットやアドオンを販売する
- ウィジェットが得意なことを**APIで作り直さない** こと。自分の形を見極めましょう

[無料トライアルを始めて](https://app-v3.shoprocket.io/signup)公開キーを取得しましょう。SDKはどのShoprocketプランでも無料で使えます。14日間、カード不要です。

---

- HTML version: https://v3.shoprocket.io/ja/blog/commerce-api-use-cases-seven-builds-you-cant-do-with-a-widget
- Language: 日本語 (ja)
- Also in: [العربية](https://v3.shoprocket.io/ar/blog/commerce-api-use-cases-seven-builds-you-cant-do-with-a-widget.md), [Deutsch](https://v3.shoprocket.io/de/blog/commerce-api-anwendungsfaelle-sieben-builds-ohne-widget.md), [Ελληνικά](https://v3.shoprocket.io/el/blog/commerce-api-use-cases-seven-builds-you-cant-do-with-a-widget.md), [English](https://v3.shoprocket.io/blog/commerce-api-use-cases-seven-builds-you-cant-do-with-a-widget.md), [Español](https://v3.shoprocket.io/es/blog/casos-de-uso-api-de-comercio-siete-proyectos-que-un-widget-no-puede-hacer.md), [Français](https://v3.shoprocket.io/fr/blog/api-commerce-sept-cas-usage-impossibles-avec-un-widget.md), [עברית](https://v3.shoprocket.io/he/blog/commerce-api-use-cases-seven-builds-you-cant-do-with-a-widget.md), [हिन्दी](https://v3.shoprocket.io/hi/blog/commerce-api-use-cases-seven-builds-you-cant-do-with-a-widget.md), [Bahasa Indonesia](https://v3.shoprocket.io/id/blog/kasus-penggunaan-commerce-api-tujuh-hal-yang-tidak-bisa-dilakukan-widget.md), [Italiano](https://v3.shoprocket.io/it/blog/api-commerce-sette-casi-duso-che-un-widget-non-copre.md), [Lietuvių](https://v3.shoprocket.io/lt/tinklarastis/prekybos-api-panaudojimo-atvejai-septyni-sprendimai-kuriu-nepadarysite-su-valdykle.md), [Norsk](https://v3.shoprocket.io/nb/blogg/handels-api-sju-ting-du-ikke-kan-bygge-med-en-widget.md), [Nederlands](https://v3.shoprocket.io/nl/blog/commerce-api-use-cases-zeven-projecten-zonder-widget.md), [Polski](https://v3.shoprocket.io/pl/blog/api-do-e-commerce-siedem-zastosowan-ktorych-nie-zrobisz-widzetem.md), [Português](https://v3.shoprocket.io/pt/blog/casos-de-uso-api-de-commerce-sete-projetos-que-widget-nao-faz.md), [Română](https://v3.shoprocket.io/ro/blog/cazuri-de-utilizare-api-comert-sapte-proiecte-fara-widget.md), [Русский](https://v3.shoprocket.io/ru/blog/commerce-api-use-cases-seven-builds-you-cant-do-with-a-widget.md), [ไทย](https://v3.shoprocket.io/th/blog/commerce-api-use-cases-seven-builds-you-cant-do-with-a-widget.md), [Türkçe](https://v3.shoprocket.io/tr/blog/commerce-api-kullanim-senaryolari-widget-ile-yapilamayan-yedi-proje.md), [中文](https://v3.shoprocket.io/zh/blog/commerce-api-use-cases-seven-builds-you-cant-do-with-a-widget.md)