bagisto-api-shop

Bagisto Shop API でストアフロントを構築する

Bagisto Shop API（/api/shop/* REST + POST /api/graphql）を使用して、顧客向けのストアフロント（カタログ、カート、チェックアウト、アカウント、ウィッシュリスト、比較）を実装します。このスキルはルーターです。フローを案内し、各機能のリファレンスページを示します。リファレンスページには、アーキテクチャ、UI/UX、エンドポイント、チェックリストが記載されています。

⚠️ まず最初に（コードを書く前に）読み込んでください

1. reference/connecting-to-the-api.md — 認証（ストアフロントキー + カート／顧客トークン）、{data,meta}／ヘッダーによるページネーション、エラーコード、コーディング前の確認プロトコル。
2. reference/graphql.md — クライアントが GraphQL を選択した場合：結果フィールド／id のルール、camelCase の入力、カーソルによるページネーション。

リクエスト／レスポンスの正確な形式の参照元は api-docs です — https://api-docs.bagisto.com とその /llms.txt インデックスを確認してください。リファレンスページにはエンドポイントとフローが記載されています。呼び出しを記述する前に、リンク先のドキュメントページを開いて正確なボディ／レスポンスを確認してください。記憶を頼りにペイロードを作らないでください。

ステップ 1 — クライアントに確認する（構築前に必ず実施）

1. プラットフォーム — Web、モバイル（ネイティブ／クロスプラットフォーム）、デスクトップのどれですか？
2. フレームワーク／スタック — React/Next、Vue/Nuxt、Flutter、React Native、Swift/Kotlin、プレーンな JS のどれですか？
3. 通信方式 — REST と GraphQL のどちらですか？（シンプルな画面には REST、関連フィールドを一度に多く必要とする画面には GraphQL が適しています。どちらも完全にサポートされています。）
4. 最初の機能／フロー — カタログ、カート + チェックアウト、アカウントなど。

回答を確認してから、それに合わせてすべてを調整してください。スタックを決めつけないでください。

ステップ 2 — 機能のリファレンスを開く

フロー（複数ステップの操作／ページ）

ページ	構築するもの
reference/flows/product-listing.md	カテゴリ、商品一覧、検索、フィルター
reference/flows/product-details.md	商品ページ（商品タイプごとのオプション検出、レビュー、関連商品）
reference/flows/add-to-cart.md	商品タイプごとのカート追加
reference/flows/cart.md	ミニカート + カートページ（取得／更新／削除／統合／合計）
reference/flows/checkout.md	住所 → 配送 → 支払い → 注文確定
reference/flows/order-confirmation.md	注文後のお礼ページ
reference/flows/authentication.md	登録、ログイン、ログアウト、認証、パスワードの再設定／変更
reference/flows/account.md	プロフィール + アドレス帳
reference/flows/customer-orders.md	注文履歴、詳細、キャンセル、再注文、請求書、ダウンロード可能な商品

機能（単一の機能）

ページ	構築するもの
reference/features/coupons.md	クーポンの適用／削除
reference/features/wishlist.md	ウィッシュリストへの追加／切り替え／一覧表示／カートへの移動
reference/features/compare.md	比較リスト
reference/features/reviews.md	商品レビュー + 顧客自身のレビュー
reference/features/newsletter.md	ニュースレターの購読
reference/features/contact-us.md	お問い合わせフォーム
reference/features/storefront-context.md	国／州、チャネル、通貨、ロケール、CMS ページ、テーマ

各ページは概要 → フローのアーキテクチャ → UI/UX → API の手順（正確なエンドポイントを含む）→ エラー → チェックリストで構成されています。内容に従ってください。正確な形式については api-docs を参照します。

重大なルールのまとめ（つまずきやすいポイント）

• 実装前に確認してください。 一旦停止 → エンドポイントのドキュメントページを開く（または MCP に問い合わせる）→ メソッドとフィールドを確認する → 実装する → 型を確認する、の順に進めてください。エンドポイント名やリクエストボディを推測しないでください。
• 利用箇所ごとの認証。 すべてのショップ呼び出しで X-STOREFRONT-KEY を送信します。カート／アカウント／チェックアウトの呼び出しでは、さらに Authorization: Bearer <cartToken | customerToken> も送信します。ゲストの場合は、まずカートトークンを発行します（POST /api/shop/cart-tokens）。
• カート／チェックアウトを変更する呼び出しでは、更新後のカート全体が返されます。ローカルで変更せず、レスポンスを基に UI を更新してください。
• ログイン時にゲストのカートを顧客のカートに統合します（merge-carts）。統合しないと、ゲストのアイテムが失われます。
• 注文後のクリーンアップ — 注文が確定したら、カートの状態をクリアし、ゲストのカートトークンを破棄してください。そうしないと、カートのポップアップに古いアイテムが表示されます。
• GraphQL： アクションのミューテーションでは、汎用的な id ではなく、ドキュメントに記載された結果フィールド（success／message／orderId／合計金額）を選択してください。入力はキャメルケースにし、各フィールドを1行ずつ記述してください。reference/graphql.md を参照してください。
• 動的なデータ（配送方法／支払い方法、価格、オプション）をハードコードしないでください — API から取得してください。