CMS API Plugin（`CmsApiPlugin`）¶

概要¶

CmsApiPlugin は、WordPress などの外部 CMS から Vendure データを検索するための 検索専用 REST API プラグインです。CMS 側で GraphQL スキーマや Vendure の内部モデルを直接理解しなくても、SKU・商品・コレクション・キャンペーンをサジェスト検索できます。

実装パス: packages/plugins/src/cms-integration/cms-api/
有効化箇所: apps/vendure-server/src/vendure-config.shared.ts
ベースパス: /cms-api
主用途: CMS 記事編集時の関連商品・カテゴリ・販促ルールの候補検索

CmsIntegrationPlugin は WPGraphQL から CMS コンテンツを取得するためのプラグインです。
CmsApiPlugin は逆に、CMS 側から Vendure を検索しやすくする補助 API を提供します。

責務¶

SKU / 商品 / コレクション / キャンペーンの部分一致検索
デフォルトチャネル・既定言語に基づく検索結果の返却
CMS 共通トークンを使った署名付き API 認証
CMS 向けに扱いやすいフラットな JSON 形式への整形

本プラグインは 検索専用 です。商品更新や CMS への push 同期、GraphQL 拡張、認可ルール評価の正本化は担いません。

認証¶

すべてのエンドポイントは、共有トークン CMS_API_TOKEN を使って生成した 署名付きリクエストを要求します。

使用ヘッダ: x-ritsubi-signature, x-ritsubi-timestamp
使用環境変数: CMS_API_TOKEN
Secrets Manager 正本: b2b-ecommerce/{env}/shared（Vendure / WordPress 共用）
CMS_API_TOKEN 未設定時: 503 { "error": "cms_api_token_not_configured" }
署名不一致時: 401 { "error": "unauthorized" }

また、take パラメータは 1〜50 件 に制限され、未指定時は 20 が使われます。term が空文字の場合は 200 [] を返します。

エンドポイント¶

メソッド	パス	用途	主な返却項目
`GET`	`/cms-api/sku-search`	SKU / バリアント名 / 商品名で検索	`sku`, `productVariantName`, `productName`, `productVariantId`, `productId`, `slug`, `featuredAssetPreview`
`GET`	`/cms-api/product-search`	商品 slug / 商品名で検索	`slug`, `name`, `productId`, `featuredAssetPreview`
`GET`	`/cms-api/collection-search`	コレクション slug / 名称で検索	`slug`, `name`, `collectionId`
`GET`	`/cms-api/campaign-search`	商流ルール code / 名称で検索	`campaignId`, `name`, `id`

sku-search / product-search は customer visibility policy を通さず、 product.enabled / variant.enabled をクエリ条件にした catalog 商品だけを候補として返します。WordPress の商品選択 UI を storefront の policy seed 状態から切り離すためです。実装の正本は packages/plugins/src/cms-integration/cms-api/cms-api.plugin.ts の skuSearch() / productSearch() です。

リクエスト例¶

timestamp=$(node -e 'console.log(Date.now())')
resource='/cms-api/sku-search?take=10&term=abc'
payload=$(printf '%s\n%s\n%s\n%s' "$timestamp" GET "$resource" '')
signature=$(printf '%s' "$payload" | openssl dgst -sha256 -hmac "$CMS_API_TOKEN" -hex | sed 's/^.* //')

curl \
  -H "x-ritsubi-timestamp: ${timestamp}" \
  -H "x-ritsubi-signature: ${signature}" \
  'https://<vendure-host>/cms-api/sku-search?term=abc&take=10'

実装メモ¶

すべての検索は RequestContextService で作った admin API コンテキスト 上で実行されます。
チャネルは ChannelService.getDefaultChannel() を基準に解決されます。
言語はデフォルトチャネルの defaultLanguageCode、なければ Vendure の defaultLanguageCode、さらに未設定なら ja を使用します。
campaign-search は CommercialRuleEntity を検索対象にしており、CMS 上で販促ルールとの関連付け候補を返す目的です。

運用上の注意¶

CMS 単位の共通トークンを使う署名認証なので、公開ネットワークに出す場合は WAF / IP 制限 / 監視ログを併用してください。
書き込み API ではないため、CMS 側で保持した参照先 ID の正本は引き続き Vendure 側です。
画像は featuredAssetPreview を返しますが、存在しない場合は null を返すため、CMS 側でフォールバック表示を用意してください。

CMS API Plugin（CmsApiPlugin）¶

概要¶

責務¶

認証¶

エンドポイント¶

リクエスト例¶

実装メモ¶

運用上の注意¶

関連ドキュメント¶

CMS API Plugin（`CmsApiPlugin`）¶