bagisto-api-admin

Bagisto Admin API 上に管理アプリを構築する

Bagisto の Admin API（/api/admin/* REST + POST /api/admin/graphql）を使って、任意の管理／バックオフィス用インターフェースを実装します。API は Bagisto 管理パネルのメニューをメニュー単位で反映しているため、あらゆる管理画面を再構築できます。このスキルはルーターです。作業の流れを示し、メニューごとのリファレンスページを案内します。各リファレンスページには、エンドポイント、UI/UX、チェックリストが記載されています。

⚠️ コードを書く前に、まず以下を読み込んでください

1. reference/connecting-to-the-api.md — 管理者認証（Integration Bearer token）、{data,meta} の一覧用エンベロープ、一覧→詳細→アクションのパターン、権限、エラー、コーディング前の検証手順。
2. reference/graphql.md — クライアントが GraphQL を選んだ場合：管理者用エンドポイント、結果フィールド／id のルール、camelCase の入力とフィルター引数、カーソルページネーション。

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

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

1. プラットフォーム — Web、モバイル（ネイティブ／クロスプラットフォーム）、デスクトップのどれですか？
2. フレームワーク／技術スタック — React/Next、Vue/Nuxt、Flutter、React Native、プレーンな JS のどれですか？
3. 対象の管理メニュー — Sales、Catalog、Customers、Marketing、CMS、Settings、Configuration、Dashboard/Reporting のどれですか？それとも、まずは 1 つから始めますか？
4. 通信方式 — REST と GraphQL のどちらですか？（一覧／詳細／アクション画面には REST、1 回の往復で多数の関連フィールドが必要な画面には GraphQL を使用します。どちらも完全にサポートされています。）
5. 最初の画面／フロー — 注文一覧＋アクション、商品管理、Create-Order、ダッシュボードなど、どれですか？

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

管理画面の基本パターン：一覧 → 詳細 → アクション

ほぼすべての管理画面は同じ構成です（詳細は connecting-to-the-api.md を参照してください）。

• 一覧 — GET /api/admin/<resource> → { data, meta } エンベロープ。?page= + ?per_page= と画面のフィルターを使ってテーブルを表示します。
• 詳細 — GET /api/admin/<resource>/{id} → 関連データが埋め込まれた完全なレコード（追加の呼び出しは不要）。
• アクション — 作成／更新／削除には POST/PUT/DELETE を使用し、レコードごとのアクション（注文のキャンセル、請求書の作成、一括更新など）も実行します。それぞれに固有の実行条件があります。

ステップ 2 — メニューのリファレンスを開く

主要なフロー

ページ	構築するもの
reference/flows/create-order.md	管理者向け Create-Order フロー（下書きカートを使って顧客の注文を作成）

メニュー（管理サイドバーを反映）

ページ	対象範囲
reference/menus/sales.md	注文（一覧／詳細＋キャンセル／コメント／請求書／配送／返金）、請求書、配送、返金、取引、予約、CSV エクスポート
reference/menus/catalog.md	商品（データグリッド＋CRUD＋画像／在庫／顧客グループ価格＋一括アクション）、カテゴリー（＋ツリー）、属性（＋オプション）、属性ファミリー
reference/menus/customers.md	顧客（CRUD＋住所／メモ／代理ログイン）、グループ、レビュー、GDPR
reference/menus/marketing.md	カートルール（＋クーポン）、カタログルール、メールテンプレート、イベント、キャンペーン、購読者、検索語／同義語、URL リライト、サイトマップ
reference/menus/cms.md	CMS ページ
reference/menus/settings.md	通貨、チャネル、ロケール、為替レート、在庫ソース、税率／カテゴリー、ロール、ユーザー、テーマ、データ転送インポート
reference/menus/configuration.md	ストア設定（スキーマ／値／更新）
reference/menus/dashboard-reporting.md	ダッシュボード統計＋レポート（売上／顧客／商品＋エクスポート）

検出 — ナビゲーションや権限をハードコードしないでください

2 つの読み取り専用エンドポイント（REST + GraphQL）から、現在のトークンで実行できる操作を確認できます。ハードコードするのではなく、これらを使ってナビゲーションやアクションの制御を行ってください。

• GET /api/admin/menu (getAdminMenu) — 権限でフィルタリングされたツリー形式の管理サイドバーです。各ノードは API エンドポイント（apiResource: { rest, graphql }、またはグループ見出しやパネル専用画面の場合は null）に対応します。
• GET /api/admin/permissions (getAdminPermissions) — トークンに有効な { permissionType, permissions }（完全なアクセス権限の場合は ["*"]）を返します。

詳細は reference/connecting-to-the-api.md を参照してください。

重要なルールのまとめ

• コーディングの前に確認してください。 一時停止 → エンドポイントのドキュメントページを開く（または MCP に問い合わせる）→ メソッドとフィールドを確認する → 実装する → 型を確認する。
• 認証： すべての呼び出しで Authorization: Bearer <id>|<token>（事前発行された管理者用 Integration トークン）を送信します。ログインエンドポイントはありません — トークンはストアの管理パネルで作成します。管理者用 GraphQL エンドポイントは POST /api/admin/graphql です（管理者トークンのみ。ショップのエンドポイントではなく、ストアフロントキーも不要です）。
• 権限： トークンの権限は、そのトークンを発行した管理者のロールによって制限されます。ロールでアクセスできないエンドポイントは 403 を返します。この動作を考慮して実装してください。
• 一覧の形式は { data, meta }（および X-Total-* ヘッダー）です。ページネーションには ?page=／?per_page=（デフォルトは 10、上限は 50）と、各画面のフィルターを使用してください。
• GraphQL のアクションミューテーション（キャンセル／請求書／配送／返金／注文作成／カートへの書き込み／一括アクション）は、汎用的な id ではなく、結果フィールドを返します。入力は camelCase です。カスタムフィルター引数は各ページに記載されています。reference/graphql.md を参照してください。
• 動的データをハードコードしないでください（注文作成で使う配送方法や支払い方法、設定オプションなど）。取得して使用してください。