commercetools-api

commercetools API 開発

段階的に読み込み — 必要なものだけを読み込みます：

• SDK またはクライアントを設定しますか？ references/sdk-setup.md を読み込みます
• カートまたはチェックアウトを構築しますか？ references/cart-checkout.md を読み込みます
• 注文を扱いますか？ references/order-management.md を読み込みます
• 顧客を管理しますか？ references/customer-management.md を読み込みます
• 拡張機能またはサブスクリプションを設定しますか？ references/extensions-subscriptions.md を読み込みます
• 割引を実装しますか？ references/promotions-pricing.md を読み込みます
• B2B 機能を構築しますか？ references/b2b-patterns.md を読み込みます
• 検索を実装しますか？ references/search-discovery.md を読み込みます
• パフォーマンスを最適化しますか？ references/performance.md を読み込みます
• コードレビューまたはデバッグを行いますか？ references/anti-patterns.md を読み込みます

commercetools API コードを記述する前に、必ず該当するリファレンスファイルを読み込んでください。SDK クライアントの設定では、必ず references/sdk-setup.md から始めてください。

最優先事項

パターン	ファイル	影響
楽観的同時実行制御とバージョン管理	references/sdk-setup.md	正しいバージョン追跡がなければ、すべての更新／削除が失敗します
カートのライフサイクルと決済前の凍結	references/cart-checkout.md	チェックアウト中の価格変更により、注文が失敗します
決済フロー — Payments を再利用／削除しない	references/cart-checkout.md	監査証跡の喪失、二重請求、PSP の不整合
拡張機能のタイムアウト制約（2s / 10s）	references/extensions-subscriptions.md	タイムアウトすると API 呼び出し全体が失敗し、すべてのクライアントに影響します
割引の併用と並び順	references/promotions-pricing.md	想定外の価格設定、収益の損失、顧客からの苦情
Direct Discounts は Discount Codes をブロックします	references/promotions-pricing.md	Direct Discounts が存在すると、コードが通知なく機能しなくなります

高優先度

パターン	ファイル	影響
クライアントの設定と認証フロー	references/sdk-setup.md	設定を誤ると、認証の失敗やトークン漏えいにつながります
注文のステートマシンと返品	references/order-management.md	無効な状態遷移、不完全なフルフィルメント
顧客認証とメール認証	references/customer-management.md	サインアップ／ログインの不具合、未認証アカウント
サブスクリプションの冪等性と順序制御	references/extensions-subscriptions.md	副作用の重複、古いデータによる上書き
事業単位の階層構造と権限	references/b2b-patterns.md	セキュリティ上の欠陥、承認ワークフローの不具合
Product Search API と Query API	references/search-discovery.md	大規模なカタログでクエリが 10～100 倍遅くなります
N+1 クエリと参照の展開	references/performance.md	一覧ページで遅延が連鎖します

中優先度

パターン	ファイル	影響
税モードの設定	references/cart-checkout.md	税データが不完全なため注文の作成に失敗します
承認ルールと見積もりのライフサイクル	references/b2b-patterns.md	B2B 購買ワークフローが停止します
Connect アプリケーションのパターン	references/extensions-subscriptions.md	デプロイの失敗、リソース制約の問題が発生します
ページネーションとクエリの最適化	references/performance.md	ページの読み込みが遅くなり、不要な API 負荷が発生します
顧客グループと住所の管理	references/customer-management.md	価格帯の誤り、住所データの問題が発生します
ファセットと検索パフォーマンス	references/search-discovery.md	検索応答が遅くなり、関連性が低下します

よくあるアンチパターン（クイックリファレンス）

アンチパターン	ファイル	結果
リクエストごとにクライアントを作成する	references/anti-patterns.md	メモリリーク、トークンの枯渇
更新アクションをまとめて処理しない	references/anti-patterns.md	負荷が高い状況でバージョンの競合が発生します
/product-projections ではなく /products を使用する	references/anti-patterns.md	応答ペイロードのサイズが 2 倍になります
Subscriptions ではなくポーリングを使用する	references/anti-patterns.md	API クォータの浪費、検知の遅延
ConcurrentModification エラーを無視する	references/anti-patterns.md	気付かないままデータが失われ、状態が破損します
念のためすべての参照を展開する	references/anti-patterns.md	応答が肥大化し、クエリが遅くなります
すべての訪問者に空のカートを作成する	references/anti-patterns.md	未使用のカートリソースが数百万件発生します
Subscription の健全性を監視しない	references/anti-patterns.md	7 日間、通知の失敗に気付けません

MCP との併用

このスキルで 適切なパターン を把握してから、Developer MCP で正確なフィールド名とスキーマを調べ、Commerce MCP で CRUD 操作を行います。