commercetools-connect

commercetools Connect

本番環境対応の Connect アプリケーションを構築するための、意図に基づいたガイダンスです。このスキルでは、本番環境対応レビューに耐える意思決定のフレームワーク、プラットフォームの契約、ベストプラクティスを解説します。特定のコネクターのコードを扱うものではありません。実際のコネクターで見られるパターンを一般化し、アンチパターンには注意を促すとともに、プラットフォームに関する事実はすべて公式ドキュメントに基づいています。

言語の対象範囲： Connect アプリケーションは JavaScript/TypeScript または Java で記述できます（ドキュメント）。create-connect-app テンプレートは JS と TS に対応しています。このスキルの対象は TypeScript/Node です。意思決定のフレームワーク、プラットフォームの契約（タイムアウト、ACK のセマンティクス、スコープ、ライフサイクル）、connect.yaml のガイダンスは言語に依存せず、Java コネクターにも同様に適用されます。一方、コードスニペットと supertest + msw のテストスタックは Node/Express 固有です。

ツール：Connect CLI を使い、独自に作成しないでください。 公式 Connect CLI（@commercetools/cli）を使って、スキャフォールディング、実行、リリースを行います。すべての CLI コマンド、ブートストラップフロー、固定された依存関係のバージョンは、Connect CLI のリファレンスにまとめられています。Merchant Center のカスタムアプリケーション／ビューは例外です。これらは別のフロントエンドツールチェーン（@commercetools-frontend/*）を使用し、デプロイ時とディレクトリー構造でのみ Connect CLI を利用します。merchant-center-cli.md と merchant-center-customizations.md を参照してください。

ワークフロー

このスキルを呼び出したら、必ず次の手順に従ってください。

1. ドキュメントの検索（必須、最初に実行） — セッション中にこのスキルを初めて使用する際は、回答する前にこれを実行してください。このスキルが対象とする製品に絞って最新の検証済みドキュメントを収集し、主要な根拠として使用します。このスキルの作業中にドキュメントを検索する際はこのスクリプトを使い、それ以外には Knowledge MCP を使ってください。スキルのテキストだけに頼らず、取得したドキュメントで必ず詳細を確認してください。

   node "<this skill's directory>/scripts/docs-search.mjs" \
     --query "<extract key terms from user's question>" \
     --app-name "<host app: claude-code, claude-chat, cursor, codex, copilot — or the host's own name>" \
     --model "<current-model>" \
     --commercetools-project-key "<if known>" \
     --commercetools-region "<if known>" \
     --limit 10
   

   commercetools のプロジェクトキーとリージョン（api.{region}.commercetools.com の形式）は、すでにコンテキストにある場合に限り指定してください。そうでなければ、どちらも省略してください。ファイルを検索したり、ユーザーに尋ねたりしないでください。

2. 意思決定のフレームワーク（以下）に沿って振り分ける — コードを書く前に、アプリケーションの種類を選び、同期／非同期の契約を確定してください。この契約によって、その後のほぼすべての判断が決まります。

3. ./references/ にある該当するリファレンスを開き、そのパターンと ## Checklist に従って構築します。

4. コネクターの完成を宣言する前に、以下の本番環境対応チェックリストを通過させます。

任意のスクリプト

GraphQL スキーマの取得 — commercetools の GraphQL クエリやミューテーションに関するコンテキストが必要な場合に実行します。たとえば、クエリを作成する前にリソースのフィールド、型、利用可能な操作を調べる場合や、生成した GraphQL クエリ／ミューテーションを実際のスキーマと照合して検証する場合です。単一の commercetools リソースの部分的な GraphQL SDL を取得します。

node scripts/graphql-schemata.mjs \
  --resource-name "<commercetools resource, e.g. Cart, Product, Order>" \
  --app-name "<host app: claude-code, claude-chat, cursor, codex, copilot — or the host's own name>" \
  --model "<current-model>"

出力は、そのリソースの GraphQL SDL です。リソース名が認識されない場合、スクリプトは有効なリソース名の一覧を表示します。正しい名前を選んで再実行してください。注： SDL にはスタブ型が含まれる場合があります。これは参照先のリソースをスタブとして示したもので、コメントに実際の型名が記載されています。必要なものは、このスクリプトをその型名を --resource-name に指定して再実行し、個別に取得してください。

OpenAPI（REST）スキーマの取得 — commercetools の REST エンドポイント、リクエスト／レスポンスのペイロード、または更新アクションに関するコンテキストが必要な場合に実行します。たとえば、リクエストを作成する前にリソースの REST 操作を調べる場合や、生成した REST リクエスト／ペイロードを実際の仕様と照合して検証する場合です。単一の commercetools リソースの部分的な OpenAPI 仕様を取得します。

node scripts/openApi-schemata.mjs \
  --resource-name "<commercetools resource, e.g. api-Cart-write, api-Customer-read, checkout-Application>" \
  --app-name "<host app: claude-code, claude-chat, cursor, codex, copilot — or the host's own name>" \
  --model "<current-model>"

出力は、そのリソースの OpenAPI 仕様（YAML）です。REST リソース名は読み取り用と書き込み用に分かれた形式を使用します（例：api-Cart-read、api-Cart-write）。リソース名が認識されない場合、スクリプトは有効なリソース名の一覧を表示します。正しい名前を選んで再実行してください。注： 仕様には参照先展開スキーマは含まれません。参照先リソースのスキーマが必要な場合は、そのリソースを --resource-name に指定してこのスクリプトを再実行し、個別に取得してください。

---

Step 1 — 判断フレームワーク：アプリケーションのタイプを選ぶ

Connector は、connect.yaml で1つ以上のアプリケーションを宣言する1つのリポジトリです。各アプリケーションのタイプは、何をするかではなく、コードがどのように呼び出されるか、またデータがどちら向きに流れるかで選んでください。

まず、次の2点を確認します。

• 方向。 変更の発生源は commercetools ですか（commercetools → 外部システム）、それとも外部システムですか（外部システム → commercetools）？どちらも一般的ですが、処理の経路は異なります。
• service は単なる HTTP エンドポイントであり、必ずしも API Extension ではありません。 service アプリは HTTP エンドポイントを公開します。このエンドポイントは API Extension として登録することも（commercetools が操作中に同期的に呼び出します）、データをプッシュするために外部システムから呼び出される通常の インバウンド Webhook / REST API として使うこともできます。これらは契約が異なる2つのモードです。

トリガー／ニーズ	タイプ	コードの呼び出し方法	厳守すべき契約
commercetools の操作が永続化される前にブロックまたは変更する（カートの検証、税額の追加、注文の拒否）	API Extension としての service	API リクエスト中に commercetools がエンドポイントを同期的に呼び出します（Extension として登録）	Extension の応答時間制限：デフォルトで2秒、セルフサービスで最大10秒（プロジェクトごとの上限引き上げは、サポートへのリクエストで利用可能。パフォーマンスレビューの対象）。レイテンシとダウンタイムはプラットフォームのものになります。
変更に応じて外部システムから commercetools にデータをプッシュする（システム A が商品を更新 → commercetools にアップサート）	インバウンド Webhook / API としての service	外部システムがエンドポイントを呼び出します	service リクエストのタイムアウトは5分です。呼び出し元の認証を行い、commercetools API を自分で呼び出します。Extension は登録されません。
変更の発生後にcommercetools の変更に対応する（確定した注文を WMS に同期する、メールを送信する、商品をインデックス化する）	event（Subscription ハンドラー）	commercetools が Subscription メッセージをキューに配信 → ハンドラー	少なくとも1回の配信、順序保証なし、未確認応答時は再配信されます。冪等性が必要です。
スケジュール実行またはオンデマンドのバッチ処理（外部システムを夜間にポーリングしてアップサートする、整合性を確認する、クリーンアップする、一括インポートする）	job	cron スケジューラー（properties.schedule）	リクエストは30分後にタイムアウトします。並行実行を防ぐ仕組みはありません。ロックは自分で管理してください。
Merchant Center 内に UI を追加する	merchant-center-custom-application（全ページ）／merchant-center-custom-view（埋め込みパネル）	MC CLI で構築し、Connect 経由でデプロイするホスト型 React アプリ	フロントエンドツールチェーン（@commercetools-frontend/*）と設定ファイルの契約が別途必要です。connect.yaml の merchant-center-* アプリとして提供されます。→ merchant-center-cli.md、merchant-center-customizations.md
静的ファイル／CDN バンドルを配信する	assets	静的ホスト	—

1つの Connector で複数のタイプを組み合わせることはよくあります（例：カートの税額を計算する service API Extension と、注文時にトランザクションを確定する event ハンドラーを組み合わせる、またはリアルタイムのプッシュに対応する service インバウンド Webhook と、夜間の全件整合性確認に使う job を組み合わせる）。

詳しい内容とトレードオフについては、architecture-decisions.md を参照してください。

Connector タイプ別の統合サブエリア

このスキルのビルド側のガイダンスは、Connector のタイプに依存しません（service/event/job のいずれにも対応します）。一部の Connector タイプには、タイプに関する作業全体を「既存の Connector があるか」の確認から、設定、フォークまたは構築、アプリケーションのバックエンドに至るまで一貫して扱う、特化したエンドツーエンドのサブエリアもあります。これらのサブエリアは、このスキルとともに提供される commercetools-integrations スキルが管理しています。表から該当するサブエリアに直接案内しているため、ここでコピーを探すのではなく、リンク先で確認してください。

コネクターの種類	対象範囲	移動先
決済（Stripe、Adyen、Mollie、PayPal など）	カスタムストアフロントにおける決済ライフサイクル全体：認定済み／公開コネクターが適合するか判断 → 設定する、またはフォークする、あるいは決済連携テンプレートから新規作成する → バックエンドを構築する（セッション BFF、承認後の Order、プロセッサー経由のキャプチャ／返金／キャンセル、Webhook による照合）。さらに、往復処理のデバッグも対象です	commercetools-integrations: payment/overview.md
税（Avalara、Vertex、TaxJar など）	税連携全体：認定済みコネクターが適合するか判断する（Avalara／Vertex にはありますが、TaxJar にはありません） → 設定する、フォークする、または税連携テンプレートから構築する → 2 つのアプリ（ExternalAmount モードで税額を計算するカート API Extension と、取引を記録／確定する OrderCreated Subscription）。さらに、サンドボックスでは永続化されないこと、およびネクサスがなければ税額がゼロになることへの注意点も対象です	commercetools-integrations: tax/overview.md
CRM（Salesforce、HubSpot、Dynamics 365、Zoho など）	顧客関係管理連携全体：公開コネクターが適合するか判断する（従来型の CRM には通常コネクターがないため、構築が必要です） → 設定する、フォークする、または定義した CRM 向けに構築する → まず 同期方向＋信頼できる情報源 を選び、それに応じた顧客同期アプリ（外向きのイベント同期、内向きの Webhook／ポーリング、一度限りの移行ジョブ）を決めます。これらはすべて externalId で関連付けられます。さらに、重複連絡先、同期ループ、PII／削除に関する注意点も対象です	commercetools-integrations: crm/overview.md
PIM（Akeneo、inriver、Bluestone、Pimcore など）	商品データ同期ジョブ全体：公開 PIM コネクターが適合するか判断する → 設定する、フォークする、または構築する → PIM モデルを Product Types／属性／カテゴリ／メディアにマッピングし、価格と在庫を別々に管理して、同期アーキテクチャ（Import API と HTTP API、イベント Webhook とジョブ）を選びます	commercetools-integrations: pim/overview.md
注文管理（OMS。Fluent Commerce、kbrw、OneStock、NewStore、Pipe17 など）	commercetools を OMS に接続します：公開コネクターをインストールするか判断する → 設定する、またはフォーク／カスタマイズする、あるいは独自の注文管理サービス向けに新規作成する（fulfilment-integration テンプレートからスキャフォールドを作成します） → 同期を設計します（OrderCreated による注文エクスポート、ステータス／出荷／フルフィルメントの受信 Webhook、在庫同期、照合ジョブ）。固定のコネクター契約はありません。種類に依存しないイベント／サービス／ジョブの構築側を組み合わせて構成します	commercetools-integrations: order-management/overview.md
ERP（SAP S/4HANA や ECC、Microsoft Dynamics 365、Oracle NetSuite、Infor、Odoo、Sage、自社開発の ERP など）	ERP 連携全体：「ERP 連携」が単一の連携になることはありません。商品、価格、在庫、顧客／B2B、注文、請求書を、方向、頻度、冪等性がそれぞれ異なる別個のフローとして範囲設定し、コネクターが実際に接続する先（通常は ERP ではなく ミドルウェア）を明確にします → 次に、公開コネクターをそのまま使用するか、設定で差分を埋めるか、カスタマイズ／フォークするか、定義した ERP またはミドルウェアのエンドポイント向けに構築するかを ユーザーに確認します（ERP テンプレートはありませんが、レジストリの検索には erp が有効な IntegrationType です） → 各フローを構築します（OrderCreated による注文エクスポートと SyncInfo の書き戻し、Import API と HTTP API のどちらかを使ったマスターデータの取り込み、バッファー／しきい値を設けた在庫、Business Units／Associates としての B2B アカウント、Order Custom Fields への請求書記録）。さらに、接続性、古いデータによる上書き、在庫のずれに関する注意点も対象です	commercetools-integrations: erp/overview.md
ギフトカード（Voucherify、社内ストアクレジットなど）	ギフトカード連携全体：公開コネクター（Voucherify）をそのまま使用する、カスタマイズ／フォークする、または定義したギフトカードシステム向けにギフトカードテンプレートから新規作成するか判断します → 2 つのアプリ（残高を確認し、金額を利用して、セッション認証による残高確認／利用と Payment Intents による返金／取消を通じて Payment を管理するイネーブラー UI とプロセッサー）。さらに、フォールバックとの併用が必須であること、およびサンプルではシミュレーションのみ行われることへの注意点も対象です	commercetools-integrations: giftcard/overview.md
メール（SendGrid、Mailgun、AWS SES、Postmark など）	トランザクションメール連携全体：既製コネクターが適合するか判断します（メール連携はテンプレート優先で、ほとんどの ESP にはコネクターがありません） → 設定する、フォーク／カスタマイズする、またはトランザクションメールテンプレートから 1 つの event アプリを構築する → アプリを構築します（Customer／Order Messages の Subscription → ESP 経由で送信）。冪等でない送信について、最大 1 回と最低 1 回のどちらにするかが重要な判断点です。さらに、トークンメール、注文状態によるフィルタリング、ローカライズに関する注意点も対象です	commercetools-integrations: email/overview.md
マーケットプレイス — マルチベンダー、または外部マーケットプレイスでの販売（Marketplacer、Mirakl、Convictional、チャネルマネージャーなど）	マーケットプレイス連携全体：役割（運営者か、他社マーケットプレイスで販売する側か）とドメインごとの方向を明確にします → 公開コネクターをそのまま使用するか、カスタマイズ／フォークするか、定義したサービス向けに構築するかを ユーザーに確認します（マーケットプレイスの掲載情報の多くはパートナー連携であり、マーケットプレイス用テンプレートはありません） → 出品者とオファーをモデル化します（出品者ごとに Channel／Store／CustomObject、出品者ごとの価格＋在庫、共有 SKU には 1 つの Product） → 同期アプリを構築します（出品者＋オファーの同期、注文のインポートまたは syncInfo を使った出品者ごとのルーティング、フルフィルメントステータス、照合）。さらに、チャネルなしの価格、集約された在庫可用性、削除できない Channel に関する注意点も対象です	commercetools-integrations: marketplace/overview.md
プロモーション／ロイヤルティ（Talon.One、Voucherify、Dovetech、Eagle Eye、NULogic など）	プロモーション連携全体：まず、ネイティブの Cart Discounts／Discount Codes／Discount Groups（段階 0）で対応できないか確認します → 次に、公開コネクターをそのまま使用するか、カスタマイズ／フォークするか、定義したプロモーションサービス向けに構築するかを ユーザーに確認します（プロモーション用テンプレートはありません） → 2 つのアプリを構築します（setDirectDiscounts を使ってエンジンの割引を適用するカート API Extension と、ポイントを利用し付与する OrderCreated Subscription）。さらに、直接割引を使うと Discount Codes が無効になるルール、および二重利用と放棄されたカートに関する注意点も対象です	commercetools-integrations: promotion/overview.md
アナリティクス — データウェアハウス／CDP／製品分析ツールへのエクスポート（BigQuery、Snowflake、Redshift、Databricks、Segment、mParticle など）	アナリティクスの外向き連携全体：すぐに使えるアナリティクスコネクターも Export API もありません。そのため（ライブレジストリを確認した後に）Product export テンプレートから構築します（CLI --template product-ingestion） → 2 つの基本要素からなる一方向の外向きパイプラインを構築します。Subscriptions／Messages 上の event ストリーマー（ほぼリアルタイム）および／または lastModifiedAt によるウィンドウ処理＋カーソルページネーションで API をクエリする job（バッチ／バックフィル） → イベントから行への変換と、resource.id＋sequenceNumber による 送信先側の重複排除。さらに、Platform Insights（APM）および Change History（ガバナンス）との違い、クライアント側トラッキングの境界、重複行／イベント欠落／payloadNotIncluded に関する注意点も対象です	commercetools-integrations: analytics/overview.md
検索／商品ディスカバリー（Algolia、Constructor、Bloomreach、Coveo、Elasticsearch、Typesense など）	検索連携全体（外向き、バックエンドのみ — API Extension は不要です）：まずネイティブの Product Search（段階 0）で対応できないか確認します → 次に、公開コネクターを使うか、フォークするか、Product export テンプレートからスキャフォールドを作成します（CLI --template product-ingestion） → Product Projection をフラットな検索ドキュメントにマッピングします（価格コンテキスト、ロケール、カテゴリの非正規化、Store の品揃え） → 2 つのアプリを構築します（カタログ全体をアトミックに再インデックスする全件取り込み用の service／job と、ProductPublished／ProductUnpublished／ストア選択の Subscriptions 上で動作する差分更新用の event）。さらに、ゴーストレコード、不完全な再構築、結果整合性に関する注意点、およびベンダーホスト型連携はコネクターではないというルールも対象です	commercetools-integrations: search/overview.md
配送（運送業者、料金比較エンジン、ラベル／配送実行プラットフォーム。DHL、UPS、FedEx、ShipperHQ、Sendcloud、nShift など）	配送連携全体：まずネイティブの Shipping Methods（段階 0）で対応できないか確認します。ゾーン、カートスコアに基づく段階的料金、述語、凍結＋setCustomShippingMethod のパターンで、「動的な配送」に関する要望の大半に対応できます → 次に、公開コネクター（integrationTypes=shipping で検索）を使うか、カスタマイズ／フォークするか、定義した配送サービス向けに構築するかを ユーザーに確認します（Checkout の配送コネクター契約も配送テンプレートもなく、多くのベンダーはベンダーホスト型連携を提供しています） → 次に、すべての前提となる採用方式を決定します。ネイティブの段階的料金での setShippingRateInput と、matching-cart に決して表示されない setCustomShippingMethod／addCustomShippingMethod のどちらを使うかです	commercetools-integrations: shipping/overview.md
あらゆる決済、税務、CRM、PIM、注文管理、ERP、ギフトカード、メール、マーケットプレイス、プロモーション、アナリティクス、検索、配送コネクター関連のタスクでは、デプロイ済みコネクターの統合でも、構築やフォークでも、該当する overview.md から始めてください。各判断ラダーが次のように案内します。段階 1 は設定、段階 2 は設定でギャップを解消、段階 3 はフォーク、段階 4 はテンプレートから構築です（プロバイダー固有の注意点はプロバイダーファイルにあります — payment/stripe.md、tax/avalara.md、email/providers.md。CRM と PIM のサブエリアはベンダーに依存しません — コネクターを最新の情報で調べてください。OMS のサブエリアには固定のコネクター契約がなく、構築側を直接組み合わせます。ERP のサブエリアはベンダーに依存せず、複数のドメインにまたがります — リクエストをデータドメインごとに分割し、設計に入る前にミドルウェアの境界を明示します。テンプレートはないため、注文エクスポートには fulfilment-integration から、マスターデータのインバウンドには通常のスターターテンプレートからスキャフォールディングします（product-ingestion は エクスポート 用の形をしたテンプレートであり、インバウンド読み込みには適さないもう一方のテンプレートです）。ギフトカードのサブエリアには、公開コネクターが 1 つ（Voucherify）と、社内システム向けのテンプレートからの構築パスがあります。マーケットプレイスのサブエリアはベンダーに依存せず、テンプレートもありません — フォーク候補は最新のリポジトリで評価してください。プロモーションのサブエリアには、公開されている MIT ライセンスの統合が 2 つあり、テンプレートはありません — promotion/public-connectors.md で、本番環境で実際に使用されている成果物を確認してください。アナリティクスのサブエリアにはすぐに使えるコネクターも Export API もありません — それでもレジストリの最新情報を確認してから、Product エクスポートテンプレート（--template product-ingestion）を使って、方向性のあるイグレスパイプラインを構築します — analytics/destinations.md で、データウェアハウス、CDP、プロダクトアナリティクス、BI の選択を案内します。検索のサブエリアはベンダーに依存せず、まずネイティブの Product Search が使えるかを判断し、Product エクスポートテンプレート（--template product-ingestion。上記と同じもう一方のテンプレート）からアウトバウンド構築のスキャフォールディングを行います。配送のサブエリアはベンダーに依存せず、まずネイティブの Shipping Methods が使えるかを判断します。Checkout のコネクター契約もテンプレートもありません — shipping はレジストリ検索で有効な IntegrationType ですが、コネクターの形を定めるものはないため、tax-integration および／または fulfilment-integration からスキャフォールディングします）。詳細な、タイプに依存しない公開／認定ライフサイクルと本番対応のゲートについてのみ、構築側のワークフローと上記のリファレンスに引き継ぎます。

プロモーション、検索、配送の各サブエリアには段階 0 があります。 commercetools には、独自のディスカウントエンジン（Cart Discounts、Discount Codes、Discount Groups）、独自の検索（Product Search）、そして独自の配送モデル（Zones、Shipping Methods、shippingRateInput に基づく段階料金、述語）があります。そのため、この 3 つの領域では、決済、税務、その他の領域とは異なり、「そもそもコネクターが必要か」は現実的な問いです。コネクターを推奨する前に、ネイティブ機能では不十分であることを明示してください。

各サブエリアは commercetools-integrations スキル内の references/<type>/ にあり、それぞれ独自の overview.md を持ちます。正本は 1 つで、そこで管理され、ここからリンクされています。後からコネクタータイプを追加する場合は、そのスキルに兄弟ツリーを追加し、上記の表に 1 行追加します。構築側のガイダンスは変わりません。

マーケットプレイスの掲載項目がすべて Connect コネクターとは限りません — 推奨する前に確認してください

既存のコネクターを探すために commercetools marketplace を確認するよう求められた場合は、コネクターの種類やベンダーを問わず、次のルールを適用してください。

• マーケットプレイスは候補を見つける情報源としては便利ですが、掲載されている統合機能が必ずしも commercetools Connect コネクターとは限りません — パートナー運営のサービス、SaaS 製品、iPaaS ミドルウェアも、デプロイ可能な Connect アプリケーションと並んで掲載されています。また、実際の Connect コネクターレジストリと同期していない場合もあります（Connect 経由ではデプロイできないものが掲載されていたり、バージョンが異なっていたりする可能性があります）。特定のベンダー（Akeneo、Stripe など）がいつでも掲載されているとは限りません — 名前の挙がったコネクターが存在すると決めつけないでください。
• 候補をインストール／設定／フォークするものとして推奨する前に、それが実際に commercetools Connect コネクターかどうかを必ず再確認してください。Connect の利用を示す情報（公開コネクターリポジトリ、connect.yaml、Connect のデプロイ操作など）を探し、マーケティング上の掲載情報よりもConnect CLI／コネクターレジストリを正しい情報源として扱ってください。
• 次に、どうするかをユーザーに尋ねてください — 黙って選んではいけません。要件への適合性と Connect でデプロイ可能かどうかを示してください。
• ユーザーが Connect 以外の統合を使いたい場合は、このスキルでは Connect 以外のコネクターの使用方法を扱わないことを警告してください。このスキルの構築／設定／デプロイのパターン（connect.yaml、Connect CLI、ライフサイクルスクリプト、Connect のデプロイモデル）は適用されません。ベンダー／パートナー独自の導入手順を案内し、スキル内の代替案として Connect コネクターの構築またはフォークを提案してください。

各サブエリアでは、尋ねられる前に選択肢を示してください

上記のいずれかのサブエリアにリクエストが振り分けられた場合、ユーザーは統合したい対象を伝えています。しかし、方法までは伝えておらず、こちらが決めつけてはいけません。要件の確認や設定、コードの作成に着手する前に、選択肢を示し、ユーザーに選んでもらってください。

0. 第 0 段階がある場合は、まずネイティブ機能を確認する（販促、検索、配送。ERP には同様の確認手順があります）。commercetools がすでにその機能を提供している場合は、そのことを明確に伝えて、そこで止めてください。プラットフォームで実現できる機能を前提に設計してはいけません。
1. 既存の公開コネクターをそのままデプロイする — 記憶ではなく、最新のレジストリ／マーケットプレイスの確認に基づいて判断し、上記のルールに従って Connect でデプロイ可能かどうかを検証してください。
2. 既存のコネクターをフォークして変更する — 設定だけでは解消できない実際の不足がある場合に選びます。
3. 新規に構築する — サブエリアのテンプレートを使います。テンプレートがない場合は、種類を問わず使える service／event／job のパターンを使います。

どの段階を推奨するか、その理由とともに伝えたうえで、ユーザーに選択を尋ねてください。必要な作業量はそれぞれ大きく異なります。決めるのはユーザーであり、こちらではありません。

これを促される前に、サブエリアでの最初の実質的な応答で行ってください — 特に、ユーザーの言い方がすでに答えを前提としているように聞こえる場合も同様です。「X の統合を構築して」「Y を commercetools に同期して」や、すでに利用しているサービスの名前を挙げることは、この選択手順を省略する指示ではありません。「構築して」と言うユーザーも、たいていは「これを動くようにしてほしい」という意味であり、インストール可能なものがあれば喜んで利用します。要件への適合性を判断する情報が本当に足りない場合は、先に確認の質問を 1 つか 2 つしてもかまいません。ただし、要件の確認を理由に選択肢の提示を遅らせないでください。まず利用可能なものを早い段階で示し、その後、要件に応じて段階を選びましょう。

各サブエリアの overview.md には、適合基準と構築に使うテンプレートを含む、順序付けられた一連の確認手順（Step 1.4/1.5）がすべて記載されています。このルールは、すべてのサブエリアに適用されます。

ステップ 2 — 構築前に契約のコストを見積もる

選択した契約のコストを見積もっていないと、重大なミスにつながります。

• service を API Extension として使う場合、可用性とレイテンシーが commercetools の操作に左右されます。Extension の応答が遅い、または停止すると、カートや注文の処理も遅くなったり、不可能になったりします。そのため、Extension のタイムアウトより短い外部呼び出しのタイムアウトを設定し、フェイルオープンとフェイルクローズのどちらにするかを慎重に決め、ホットパスでの処理を最小限に抑えます（冗長な外部呼び出しは省略します）。
• service を受信 Webhook として使う場合、commercetools の操作とは連動しません（2 秒の Extension 制限ではなく、5 分のサービス タイムアウトが適用されます）が、あらゆる責任を負います。呼び出し元の認証、ペイロードの検証、書き込みの冪等性の確保が必要です（同じ商品更新が 2 回届くことがあります）。キーを使ってアップサートし、無条件に新規作成しないでください。書き込みに失敗した場合に何を返せば、呼び出し元が安全に再試行できるかを決めておきます。
• **非同期（event）**では、即時性と引き換えに回復性が高まりますが、少なくとも 1 回の配信、順序が保証されないこと、再配信に対応する必要があります。そのため、安定した識別子をキーとする冪等性、「再送しない」ことを示す再配信に安全な ACK（2xx）、古い、または省略されている可能性のあるペイロードを信頼せず ID でリソースを再取得すること、ループを防ぐための自身による変更のフィルタリングが必要です。
• **job**では、独自のスケジュール上の余裕、重複実行のロック、再起動に安全なチェックポイント管理が必要です。再実行や重複実行が二重書き込みにつながらないよう、作業単位ごとに冪等性を確保します。

レイテンシー予算（Extension）、冪等性戦略（受信 Webhook／イベント／ジョブ）、失敗時の動作と再試行の方針を、それぞれ 1 文で説明できないのであれば、ハンドラーを書く準備ができていません。

---

本番環境への対応チェックリスト（合格基準）

適用される項目をすべて満たすまで、コネクターは完成していません。各項目には、実装パターンを示すリファレンスが対応しています。

信頼性

• 冪等性戦略が明確にされ、実装されている — ステートレスに。 メッセージを再処理しても、対象システム独自の冪等性機能、commercetools のリソースの再取得と状態の再確認、または安定したキーによるアップサートによって何も起きないようにします。ローカルの重複排除ストアは使用しません。→ event-applications.md
• 再配信に安全なレスポンス。 イベントのエンドポイントは、処理済みおよび無関係だが ACK 済みのメッセージに対して、肯定 ACK（102/200/201/202/204）を返します。102、200、201、202、204 以外のレスポンスは再試行を引き起こします。→ event-applications.md
• ペイロードを信頼せず、ID で再取得する。 ハンドラーは resource.id を使って最新のリソースを取得します。payloadNotIncluded が設定されている場合は必須です。→ event-applications.md
• ホットパスの処理を最小限に抑える（同期）。 Extension は関連データに変更がない場合（保存済みハッシュなど）は外部呼び出しを省略し、早期に処理を終了します。→ service-applications.md

セキュリティ

• インバウンドエンドポイントを認証します。 サービス拡張機能では、authentication.type に識別値 AuthorizationHeader（スキーマの型名 AuthorizationHeaderAuthentication ではありません。指定すると InvalidJsonInput で失敗します）または AzureFunctions を指定した宛先を登録し、アプリ内でそのシークレットを検証します。外部システムからの Webhook では、完全な JWT（署名、発行者、オーディエンス、サブジェクト、有効期限、アルゴリズム）を検証します。この誤記を含む postDeploy はデプロイ失敗として表面化しないことがあるため、GET /{projectKey}/extensions を呼び出して、拡張機能が実際に登録されたことを確認してください。→ security.md、service-applications.md パターン 1
• CT スコープは最小権限にします。 アプリに必要なスコープ（例：manage_orders、manage_subscriptions、manage_extensions）だけを指定して inheritAs.apiClient.scopes を使用し、管理者用または manage_project のクライアントは使用しないでください。→ security.md
• シークレットは securedConfiguration に保存します。 API キー、クライアントシークレット、JWT シークレットを standardConfiguration に設定したり、ハードコードしたりしないでください。→ security.md
• レスポンスにスタックトレースやシークレットを含めません。 エラーミドルウェアは、本番環境では汎用的なメッセージを返します。→ security.md

正確性

• エンベロープを検証します。 注入された宛先の型に応じてエンベロープをデコードし（CONNECT_SUBSCRIPTION_DESTINATION を条件分岐します。Pub/Sub では message.data は base64 形式で、SNS には独自のエンベロープがあります）、処理の前に（→ JSON → リソース参照 → notificationType の順に）検証します。不正なエンベロープは拒否します。→ event-applications.md
• メッセージタイプをフィルタリングします。 必要なメッセージタイプだけをサブスクライブし、それ以外（プラットフォームのテストメッセージやサブスクリプションメッセージを含む）は ack して無視します。→ event-applications.md
• 自身による変更をフィルタリングします。 コネクター自身が行った更新によって、ループが発生しないようにします。→ event-applications.md
• ルートパスを connect.yaml の endpoint と一致させます。 Express ルーターは、アプリの endpoint と同じベースパスにマウントします（例：endpoint: /service ↔ app.use('/service', router)）。一致しない場合、プラットフォームからのトラフィックは 404 になります。→ project-structure.md
• SDK とクライアントのバージョンを固定します。 JS/TS：@commercetools/platform-sdk@^8 と @commercetools/ts-client@^4（レガシーの @commercetools/sdk-client-v2 は使用しません）。Java：spring-boot-starter-parent 3.5.15 以降、commercetools Java SDK 19 以降を使用します。最初から最後まで型付けし、any による回避をせず、境界でマッピングします。→ connect-cli.md (Step 3)。

可観測性

• 相関 ID 付きの構造化ログを記録します。 JSON ログでは、リクエストごとのすべてのログ行に、メッセージ／リソースの相関キー（拡張機能では X-Correlation-ID、イベントでは resource.id と sequenceNumber）を含めます。→ observability-operations.md
• ヘルスエンドポイントを用意します。 /status のようなルートが、稼働確認に対して 200 を返すようにします。→ observability-operations.md

運用

• 冪等なライフサイクルスクリプト。 postDeploy でリソースを作成する際は、取得してから更新し（存在しない場合にのみ作成）、無条件に削除して再作成することはありません。preUndeploy でリソースをクリーンアップします。→ lifecycle-scripts.md
• デプロイ時の依存関係検証。 postDeploy で外部サービスへの接続テストを行い、無効な認証情報があればすぐに通知します。→ lifecycle-scripts.md
• フェイルオープンとフェイルクローズについて説明されている。 README には、ユースケースごとに外部依存関係が停止した場合の動作が記載され、外部への呼び出しにはタイムアウトの上限が設定されています。→ service-applications.md
• ポイズンメッセージ／再実行手順書。 繰り返し失敗するメッセージの処理方法（DLQ／保持期間後に破棄）と、再実行方法が記載されています。→ observability-operations.md

品質

• 実際の動作をテストでカバーし、commercetools connect application test で実行する。 最低限、パラメーター化された認証拒否マトリックス（欠落／期限切れ／発行者不一致／対象者不一致／alg:none）、エンベロープ／ACK のエッジケース（イベント）、または純粋なビジネスロジックとレスポンスアクション（サービス）、冪等性／重複配信テスト、冪等な postDeploy 登録を含めます。正常系のテストを数件用意するだけでは不十分です。→ testing.md
• デッドコードや any による型回避がない。 コメントアウトされたコードブロックがなく、SDK の型がエンドツーエンドで維持されています。→ project-structure.md
• Connect CLI でスキャフォールディングして実行する。 プロジェクトは commercetools connect init で作成し、commercetools connect validate に合格しています。→ connect-cli.md (Step 2)

生成されるコネクターのドキュメント

• コネクターに README が含まれている。 フェイルオープン／フェイルクローズの方針、必要なスコープ、設定テーブル（connect.yaml のすべてのキー）、ポイズンメッセージ／再実行手順書が記載されています。→ deployment-installation.md

---

リファレンス一覧

項目	リファレンス
Connect CLI の仕組み：インストール／認証、connect init のテンプレート、バージョンの固定、ビルド／テスト／検証、ステージング／プレビュー／公開／デプロイのコマンド	connect-cli.md
Merchant Center CLI：create-mc-app によるひな形の作成、mc-scripts による実行／ビルド／配信／ログイン／config:sync、@commercetools-frontend/* のバージョン固定	merchant-center-cli.md
カスタムアプリとカスタムビューの違い、設定ファイルの契約、ローカルでの開発／テスト、Connect によるデプロイ（connect.yaml の merchant-center-* タイプ、操作順序）	merchant-center-customizations.md
コネクターとストアフロントを含むモノレポ：ルート直下の兄弟構成、npm workspaces を使わない理由、独立した 2 つのデプロイライフサイクル	monorepo-with-storefront.md
event／service／job の違い、同期／非同期の契約コスト	architecture-decisions.md
CLI によるひな形作成とローカル開発、モノレポ構成、クライアントのセットアップ（ts-client）、connect.yaml の構成、ルートとエンドポイントの対応、環境変数のフェイルファスト検証	project-structure.md
サブスクリプション：エンベロープ、ACK のセマンティクス、冪等性、再配信、再取得、注入されるサブスクリプション宛先（Pub/Sub または SNS）	event-applications.md
API 拡張機能：認証済みの登録、トリガー、タイムアウトの予算、フェイルオープン／フェイルクローズ、ホットパス	service-applications.md
スケジュール実行／オンデマンドのジョブ：スケジュール、タイムアウト、同時実行、チェックポイント	job-applications.md
デプロイ後／デプロイ解除前：冪等な登録、スキーマのコード化、デプロイ時の検証	lifecycle-scripts.md
エンドポイント認証、最小権限のスコープ、securedConfiguration、エラーの衛生管理	security.md
構造化ログと相関 ID、ヘルスチェック、機能フラグ、ランブック、DLQ	observability-operations.md
認証／エンベロープのテストマトリクス、supertest と msw のパターン、モック対象	testing.md
connect.yaml の設定、サンドボックス→プレビュー→公開、インストール、再デプロイ、認定、リージョン、CLI	deployment-installation.md

デプロイ済みの決済コネクターを統合する（サブエリア）

概要から始めると、ほかの項目（統合、設定、フォーク、または新規作成）に案内されます。上記のコネクタータイプ別の統合サブエリアセクションも参照してください。

概要	リファレンス
まずはこちら — バックエンドに焦点を当てたワークフロー：要件 → 認定コネクターで十分か → 設定 → BFF／Order／キャプチャ・返金／Webhook	commercetools-integrations: payment/overview.md
認定コネクターで十分か？ライブのマーケットプレイス／ドキュメントデータを使って、ユースケースと公開コネクターの適合性を確認します	commercetools-integrations: payment/connector-selection.md
要件 → connect.yaml の設定マッピング、実例	commercetools-integrations: payment/config-from-requirements.md
バックエンド：セッション／BFF、決済後のOrder、プロセッサー経由のキャプチャ／返金／キャンセル、Webhookによる照合、Paymentの所有者	commercetools-integrations: payment/backend-integration.md
バックエンドをテストファーストで試す：各要素でアサーションとモックを使い分け、回帰テストとして不変条件を検証します	commercetools-integrations: payment/backend-tdd.md
実際にデプロイされたコネクターとテストカードを使ったフルフロー統合テスト	commercetools-integrations: payment/integration-test.md
プロバイダーに依存しないフロントエンド契約：セッション本文、イネーブラーの読み込み、プロセッサーのルートと認証、落とし穴の一覧	commercetools-integrations: payment/connector-contract.md
Stripe固有の情報：正確なconnect.yamlキーとデフォルト値、イネーブラーバンドル、テストカード、Webhookの設定	commercetools-integrations: payment/stripe.md
公開決済コネクターのデプロイ（CLI認証、スコープ、deployment create、connectorstagedではない）	commercetools-integrations: payment/deploy-public-connector.md
フォークまたはカスタムの決済コネクターのデプロイ（connectorstaged → publish → deployment create）	commercetools-integrations: payment/deploy-custom-connector.md
往復を検証し、使い捨てのハーネスでデプロイ済みコネクターを実証します	commercetools-integrations: payment/verification.md, commercetools-integrations: payment/test-harness.md

税コネクターの統合または構築（サブエリア）

概要から始めてください。そこから、その他の項目（認定コネクターの設定、フォーク、またはテンプレートから両方のアプリを構築）に進めます。上記の［コネクタータイプ別の統合サブエリア](#connector-type-integration-sub-areas)のセクションも参照してください。

検討事項	リファレンス
ここから開始 — 2 アプリのワークフロー：要件 → 認定コネクターで十分か → 設定 → 計算＋記録	commercetools-integrations: tax/overview.md
認定コネクターで十分か？ エンジン別（Avalara／Vertex は認定済み、TaxJar はテンプレートから構築）、ライブのマーケットプレースデータを利用	commercetools-integrations: tax/connector-selection.md
要件 → connect.yaml：税モード（ExternalAmount 対 External）、ネクサス、税コードの取得元、免税、スコープ、具体例	commercetools-integrations: tax/config-from-requirements.md
2 アプリの契約：計算用 API Extension（税に関する 4 つすべてのアクション、200-not-202、失敗モード、呼び出し削減）＋注文同期 Subscription（確定／取消／返金、冪等性）、落とし穴の完全な一覧	commercetools-integrations: tax/tax-contract.md
Avalara の実態（認定済みオープンソースコネクターに基づく）：正確なキー、AvaTax の createTransaction における見積もりと確定、税コード／エンティティ使用区分のマッピング、MC 設定アプリ — テンプレートから構築する場合との対比としての TaxJar も紹介	commercetools-integrations: tax/avalara.md
ラウンドトリップを検証する：カートの taxedPrice、トランザクションの記録、サンドボックスではデータが保持されない場合と、ネクサスがないと税額がゼロになる場合の落とし穴	commercetools-integrations: tax/verification.md

CRM コネクターの統合または構築（サブエリア）

概要から始めてください。そこから、その他の項目（公開コネクターの設定、フォーク、または定義した CRM 向けの構築）に進めます。上記の［コネクタータイプ別の統合サブエリア](#connector-type-integration-sub-areas)のセクションも参照してください。

検討事項	リファレンス
ここから開始 — 同期ワークフロー：要件 → 方向＋信頼できる情報源 → 公開コネクターで十分か → 設定 → 同期アプリの構築	commercetools-integrations: crm/overview.md
公開コネクターで十分か？ 従来型の CRM（Salesforce／HubSpot／Dynamics／Zoho）は通常ゼロから構築する理由、ライブのマーケットプレースでの確認、選択肢の段階	commercetools-integrations: crm/connector-selection.md
要件 → connect.yaml：方向 → アプリの構成、信頼できる情報源、externalId／カスタムフィールドによるリンク、最小権限のスコープ、セキュリティ保護された設定、具体例	commercetools-integrations: crm/config-from-requirements.md
同期の契約：外向きイベント同期、内向きの Webhook／ポーリング、移行ジョブ、externalId による冪等なアップサート、ID による再取得、確認応答のセマンティクス、自身による変更／ループのフィルタリング、削除／PII、落とし穴の完全な一覧	commercetools-integrations: crm/crm-contract.md
ラウンドトリップを検証する：externalId でリンクされたレコード、差分の伝播は 1 回のみ、削除の伝播、ループ／レート制限／サンドボックスの落とし穴	commercetools-integrations: crm/verification.md

PIM を commercetools に同期する（サブエリア）

概要から始めてください。そこからほかの項目に進めます（公開コネクターを使用する、設定する、フォークする、または構築する）。上記のコネクタータイプ別の統合サブエリアセクションも参照してください。

検討事項	リファレンス
ここから開始 — 同期に特化したワークフロー：要件 → 公開コネクターで十分か？ → 設定／フォーク／構築 → データマッピング → 検証	commercetools-integrations: pim/overview.md
公開 PIM コネクターで十分か？ マーケットプレイスの最新状況の確認、コネクターの名称、適合性の評価項目、設定／フォーク／構築の段階	commercetools-integrations: pim/connector-selection.md
データマッピング（中核となる内容）：Product Type の戦略（PIM のファミリーと 1 対 1 にしない）、属性マッピング、ローカライズ、カテゴリ、メディア、価格と在庫の分離、キーと冪等性	commercetools-integrations: pim/data-mapping.md
コネクターの構築またはフォーク：Import API と HTTP API の比較、service webhook と job、全件同期と差分同期、冪等な upsert、依存関係の解決、削除の処理	commercetools-integrations: pim/build-connector.md
同期のテストと安全な実行：マッピングの単体テストの後、事前の項目数確認、大規模カタログのゲート、冪等性を確認する再実行を伴う、範囲を限定したサンドボックス専用のライブ実行（本番の認証情報は使用しない）	commercetools-integrations: pim/testing.md

注文管理（OMS）コネクター（サブエリア）

概要から始めてください。そこからほかの項目に進めます（公開コネクターを使用する、カスタマイズ／フォークする、または専用 OMS 向けに新しいコネクターを構築する）。すべての経路に同期設計を適用します。上記のコネクタータイプ別の統合サブエリアセクションも参照してください。

検討事項	リファレンス
ここから開始 — データの方向と信頼できる情報源、要件 → 使用／設定／フォーク／構築の段階、エクスポート／受信／照合のワークフロー	commercetools-integrations: order-management/overview.md
公開 OMS コネクターで十分か？ マーケットプレイスのコネクターと照らした最新の適合性チェック、インストール可能な Connect コネクターとベンダーホスト型統合の違い	commercetools-integrations: order-management/connector-selection.md
同期設計：エクスポート（OrderCreated の event）、受信（service webhook）、照合（job）；サブスクライブする Messages；OMS のステータスから CT の状態へのマッピング；フローごとの冪等性	commercetools-integrations: order-management/sync-architecture.md
ユーザー定義 OMS 向けの新しいコネクターを構築する（第 4 段階）：スキャフォールド、宣言するアプリケーション、OMS API への接続方法、テンプレートから再利用するもの	commercetools-integrations: order-management/build-oms-connector.md

OMS コネクターには固定のランタイム契約がないため、構築側では上記のタイプに依存しない event／service／job のリファレンスを組み合わせます（fulfilment-integration CLI テンプレートからスキャフォールディングします）。デプロイにはサブエリア固有のフローではなく、deployment-installation.mdを使用します。

ERP コネクターの統合または構築（サブエリア）

まずは概要から確認してください。ほかの資料への案内があります。コードを書く前に、設計全体を左右する次の2点を押さえてください。「ERP 連携」が1つの連携であることはありません（文書化されたベストプラクティスに従い、商品、価格、在庫、顧客／B2B、注文、請求書はそれぞれ別のフローです）。また、コネクターの接続先は、通常 ERP 自体ではなくミドルウェア（SAP Cloud Integration、Boomi、MuleSoft、クラウド API ゲートウェイなど）です。社内ネットワーク内でしか応答しない ERP は、Connect アプリケーションからアドレス指定できません。ERP テンプレートはありませんが、erp はレジストリ検索に使える有効な IntegrationType です。また、ERP のマーケットプレイス掲載情報はミドルウェアのコンテンツやパートナーがホストする連携であることが特に多いため、マーケットプレイスの掲載情報がすべて Connect コネクターとは限りません — 推奨する前に確認を適用してください。対象範囲の境界：PIM からの商品コンテンツは pim、フルフィルメント、出荷、注文ステータスの書き戻しは order-managementです。

項目	リファレンス
まずはこちら — ワークフロー：ドメインの範囲を決める → rung-0（そもそも複製が必要か？）→ 要件 → ドメインごとに使用／設定／フォーク／構築 → 設定 → フロー → 検証。最初に明示する3つの事実と、PIM、OMS、CRM、税務との境界	commercetools-integrations: erp/overview.md
使用、設定、フォーク、構築のどれを選ぶか：ライブの integrationTypes=erp レジストリ確認、4種類の掲載形態（コネクター、ミドルウェアのコンテンツ、ベンダー／SI がホストするもの、アクセラレーター）、ドメインごとの適合性確認、フォーク候補の評価方法、各フローのスキャフォールドに使用するテンプレート	commercetools-integrations: erp/connector-selection.md
コントラクト（コーディング前に確認）：注文エクスポート（OrderCreated、SyncInfo／Custom Field の書き戻し）、マスターデータのインバウンド（Import API と HTTP API の使い分け、1リクエストあたり20件、参照解決の48時間）、在庫（絶対数量、Supply Channel、バッファー／しきい値、結果整合性）、顧客／B2B、請求書の書き戻しについて、フローごとのトリガー＋書き込み API＋冪等性キー。接続性、実行時間の予算、順序、ループに関する制約と、落とし穴の完全な一覧	commercetools-integrations: erp/erp-contract.md
フィールドマッピング：キーと識別情報（品目 → SKU、Order に externalId はない）、金額と丸め処理、価格条件 → Price のスコープ（Embedded と Standalone）、測定単位と梱包単位、分類と税区分、ERP のアカウント階層 → Business Units／Associates、注文ペイロード、請求書 — マッピングテーブルを設定または CustomObjects に置く理由	commercetools-integrations: erp/data-mapping.md
要件 → connect.yaml：フローごとに1つのアプリケーション、ERP／ミドルウェアのエンドポイントと認証情報、スケジュールとバッチサイズ、ロケーション→Channel のマッピング、バッファー／しきい値、ドメインごとの最小権限スコープ、実際の postDeploy 作業（Channels、Types、Subscription、状態コンテナー、認証情報の検証）。具体例	commercetools-integrations: erp/config-from-requirements.md
フローごとの検証：Order が1回だけ販売注文になり、元にリンクされること、マスターデータを再実行でき、インポートが完了までポーリングされること、在庫の収束としきい値の動作、B2B 階層と契約価格、請求書の書き戻し。強制的に発生させるべき障害パスと、非同期インポート／結果整合性／古い値による上書きの落とし穴	commercetools-integrations: erp/verification.md
ERP コネクターには固定のランタイム契約がないため、ビルド側では上記の型に依存しない event／service／job の参照を組み合わせます。デプロイには、サブエリア固有のフローではなく、deployment-installation.md を使用します。

ギフトカードコネクターの統合または構築（サブエリア）

概要から始めてください。概要から他のドキュメントに進めます（公開コネクターをそのまま使用する、カスタマイズまたはフォークする、あるいはギフトカードのテンプレートから新しいコネクターを構築する）。上記のコネクタータイプ別統合サブエリアのセクションも参照してください。

項目	参照先
まずはこちら — 2つのアプリを使うワークフロー：要件 → 使用／カスタマイズ／構築 → 設定 → 残高確認＋引き換え＋返金	commercetools-integrations: giftcard/overview.md
使用／カスタマイズ／構築の選択肢：段階的な選択肢（公開されているVoucherify、自社でテンプレートから構築）、PoC 用のサンプルコネクター、ライブのマーケットプレイスデータ経由	commercetools-integrations: giftcard/connector-selection.md
要件 → connect.yaml：CT 接続ブロック＋JWKS／issuer、通貨、ギフトカードシステムの認証情報、最小権限スコープ、具体例	commercetools-integrations: giftcard/config-from-requirements.md
2つのアプリの契約：エネーブラー（セッション駆動型 UI）＋プロセッサー（セッション認証による残高確認／引き換え、返金／取消のための Payment Intents modifyPayment）、複数カードの部分利用、冪等性、常にフォールバックと組み合わせること、落とし穴の全一覧	commercetools-integrations: giftcard/giftcard-contract.md
一連の処理を検証：残高確認 → 引き換え → Payment トランザクション → フォールバック残額 → 返金／取消、サンプルはシミュレーションのみという落とし穴、フォールバックがないという落とし穴	commercetools-integrations: giftcard/verification.md

メールコネクターの統合または構築（サブ領域）

概要から始めてください。概要から、既製コネクターの設定、フォークしてカスタマイズ、またはトランザクショナルメールのテンプレートから単一のイベントアプリを構築する方法に進めます。コネクタータイプ別の統合サブ領域のセクションも参照してください。これは純粋なeventアプリなので、event-applications.mdを基盤とします。

懸念事項	リファレンス
まずはこちら — 単一アプリのワークフロー：要件 → 既製コネクターで十分か → 設定 → 送信と確認	commercetools-integrations: email/overview.md
既製コネクターで十分か：設定するか、フォークしてカスタマイズするか、テンプレートから構築するか。メールをテンプレート優先にする理由。マーケットプレイスの最新状況の確認	commercetools-integrations: email/connector-selection.md
要件 → connect.yaml：使用するメッセージ、ESP キーとメールごとのテンプレート ID、送信者、使用するメールに限定した最小権限スコープ。記入例	commercetools-integrations: email/config-from-requirements.md
単一アプリの契約：Subscription の登録とメッセージからメールへのルーティング、べき等性のない送信における最大1回と最低1回の選択、トークンメール（≤60 min）の注意点、注文状態のフィルタリング、ローカライズ、PII。落とし穴の完全な一覧	commercetools-integrations: email/email-contract.md
ESP 固有の情報：SendGrid／Mailgun／AWS SES／Postmark の送信呼び出し形式、ESP ホストのテンプレート、べき等性キー。プロバイダーの比較	commercetools-integrations: email/providers.md
往復を確認する：イベントごとの確認項目。サブスクリプションがない場合とサンドボックスでは配信されない場合の落とし穴。重複や通知なしの破棄の兆候	commercetools-integrations: email/verification.md

マーケットプレイスコネクターの統合または構築（サブエリア）

概要から始めると、ほかの項目に進めます（公開コネクターをそのまま使う、カスタマイズ／フォークする、またはユーザーが定義するサービス向けに構築する）。上記のコネクタータイプ別統合のサブエリアセクションも参照してください。マーケットプレイスの掲載項目はConnectコネクターではないことが特に多いため、推奨する前にマーケットプレイスの掲載項目はすべてがConnectコネクターとは限りませんを確認してください。

懸念事項	リファレンス
まずはこちら — ワークフロー：「マーケットプレイス」の意味を明確化 → ドメインごとの役割＋方向 → パスの選択 → 出品者／オファーのモデリング → 同期アプリの構築	commercetools-integrations: marketplace/overview.md
パスの選択 — ユーザーに確認：公開コネクターをそのまま使うか、カスタマイズ／フォークするか、ユーザーのサービス向けに構築するか。掲載状況のライブ確認、および現在のリポジトリ（connect.yaml、ハンドラー、マッピング）を基に、フォーク候補が本番環境の基準を満たすか評価する方法	commercetools-integrations: marketplace/connector-selection.md
出品者＋オファーのモデリングとconnect.yaml：出品者ごとのChannel／Store／CustomObject、オファーのキー設定、出品者ごとの価格／在庫のスコープ設定、Order Import＋syncInfo、設計を制約するProjectの上限、スコープ。具体例	commercetools-integrations: marketplace/config-from-requirements.md
同期コントラクト：出品者の同期、オファー／在庫／価格の同期、注文のインポートと出品者ごとの振り分け、フルフィルメント状況、照合ジョブ。マーケットプレイスIDによる冪等なアップサート、複数出品者にまたがる注文の分割。落とし穴の完全な一覧	commercetools-integrations: marketplace/marketplace-contract.md
一連の処理を検証：出品者が利用可能であること、出品者ごとにオファーを販売できること、注文がちょうど1回インポート／振り分けされること、複数出品者にまたがる注文が分割されること。Channelのない価格、集約された在庫状況、スロットリング、削除できないChannelという落とし穴	commercetools-integrations: marketplace/verification.md

プロモーション／ロイヤルティコネクターの統合または構築（サブ領域）

概要から始めてください。ここからほかの項目に進めます（まずネイティブ割引を除外し、その後、公開コネクターを使用するか、カスタマイズ／フォークするか、独自のエンジン向けに構築します）。上記のコネクタータイプ別の統合サブ領域セクションも参照してください。

懸案事項	リファレンス
まずはこちら — ワークフロー：要件 → ネイティブかコネクターか → 使用／カスタマイズ／構築 → 設定 → 評価＋引き換え	commercetools-integrations: promotion/overview.md
ネイティブ、使用、カスタマイズ、それとも構築？ rung-0 のネイティブ確認（カート割引／割引コード／割引グループ）、ライブマーケットプレイスでの手順、エンジンごとの全体像、プロモーションテンプレートがない理由	commercetools-integrations: promotion/connector-selection.md
要件 → connect.yaml：割引をカートに反映する方法（setDirectDiscounts 対 負のカスタム明細項目 対 エンジン管理コード）、クーポンコードのカスタムフィールド、スコープ、具体例	commercetools-integrations: promotion/config-from-requirements.md
2 つのアプリの契約：評価器（効果からアクションへのマッピング、パーミリアド、カートを失敗させずにクーポンを拒否、202 ではなく 200、フェイルオープン、呼び出し削減、税との拡張チェーン）＋引き換え同期ツール（引き換え／ロールバック、冪等性、セッション ID）、落とし穴の完全な一覧	commercetools-integrations: promotion/promotion-contract.md
実際に使用する公開インテグレーション — Talon.One の Connect コネクターはサードパーティ製で、ベンダー自身のリポジトリは PoC アクセラレーターであること、Voucherify のものは移植版でありインストール用ではないこと、さらにフォーク時に適用する commercetools 側の修正	commercetools-integrations: promotion/public-connectors.md
往復を検証：カートの directDiscounts、エンジンでの引き換え、動作しない割引コード、割引額ゼロ、フェイルオープン時の自己修復、カート統合に関する落とし穴	commercetools-integrations: promotion/verification.md

分析コネクターの統合または構築（サブ領域）

概要から開始してください。ここから以降の手順に進みます（稼働中のレジストリチェックを実行し、Product export templateから方向性のあるエグレスパイプラインを構築します。CLI --template product-ingestion）。上記のコネクター種別ごとの統合サブ領域セクションも参照してください。すぐに使える分析コネクターもExport APIもないため、型に依存しないevent／jobのビルド側を組み合わせます（event-applications.md、job-applications.md）。

懸念事項	リファレンス
まずはこちら — エグレスのワークフロー：要件 → コネクターで十分か（いずれにしても稼働中のチェックを実施）→ パイプライン設計 → テストファーストで構築。コマース分析とPlatform Insights + Change Historyを区別し、クライアント側の境界を示します	commercetools-integrations: analytics/overview.md
コネクターで十分か？構築が想定されている場合でも必須となる稼働中のレジストリ／マーケットプレイスチェック、CDP／ELTローダーによって回答がどう変わるか、設定／フォーク／Product export templateからの構築という段階	commercetools-integrations: analytics/connector-selection.md
要件 → connect.yaml：どのMessages／ジョブスケジュールを使うか、最小権限の読み取りスコープ、securedConfiguration内の送信先認証情報、記述例	commercetools-integrations: analytics/config-from-requirements.md
パイプライン（中核）：イベントストリーマー（サブスクライブ→デコード→再取得→変換→配信）+ バッチ／バックフィルジョブ（lastModifiedAtウィンドウ + カーソルページネーション + チェックポイント）。イベントから行への変換、送信先側での重複排除（resource.id+sequenceNumber／version）、payloadNotIncludedの再取得、PII／GDPR、制限事項、落とし穴の完全なカタログ	commercetools-integrations: analytics/pipeline-architecture.md
送信先：データウェアハウスとCDP、プロダクト分析とBIの違い — ストリームかバッチか、どのようなデータが流れるか、PIIへの影響。サブスクリプションブローカー、GA4／Mixpanelに関するクライアント側優先という正直な但し書き	commercetools-integrations: analytics/destinations.md
往復を検証する：1つの変更が重複なしで1行になること、バッチウィンドウがべき等にロードされること。サブスクリプションなし／重複行／payloadNotIncluded／デフォルトで無効なクエリの落とし穴	commercetools-integrations: analytics/verification.md

検索コネクターの統合または構築（サブ領域）

概要から始めてください。概要から他の項目に進めます（まずネイティブの Product Search を除外し、その後、パブリックコネクターを利用するか、フォークするか、ご利用のエンジン向けに Product エクスポートテンプレートからスキャフォールディングします — CLI --template product-ingestion）。これはアウトバウンドで、バックエンドのみです — API Extension はありません。上記の コネクタータイプ別の統合サブ領域 セクションも参照してください。エンジン独自のダッシュボードで設定する統合（例：「Algolia for commercetools」）は、Connect コネクターではないことがよくあります。推奨する前に、マーケットプレイスの掲載項目がすべて Connect コネクターとは限りませんを確認してください。

懸案事項	リファレンス
まずはこちら — ワークフロー：段階 0 のネイティブ機能の判定 → 要件 → 利用／フォーク／構築 → データマッピング → 2 つのアプリ → 検証	commercetools-integrations: search/overview.md
ネイティブ機能、利用、フォーク、それとも構築？ 段階 0 のネイティブ検索（Product Search）の判定、ライブマーケットプレイスの確認、ベンダーホスト型統合の落とし穴、および Product エクスポートテンプレート（--template product-ingestion）からのスキャフォールディング	commercetools-integrations: search/connector-selection.md
要件 → 検索ドキュメント + connect.yaml：2 つのアプリ（全件取り込み + 差分更新）、インデックス／エンジンキー、読み取り専用の最小権限スコープ、セキュアな設定、実例	commercetools-integrations: search/config-from-requirements.md
データマッピング（要点）：Product Projection → フラットなドキュメント、objectID によるキー設定、レコードの粒度、価格コンテキストの爆発的増加、ローカライズ、カテゴリーの非正規化、Store の品揃え、可用性の境界	commercetools-integrations: search/data-mapping.md
2 つのアプリの契約：全件取り込み（カーソルページネーション、アトミック／ブルーグリーン再インデックス、件数チェック）+ 差分更新（冪等なアップサート、削除の反映、古いデータのガード）、落とし穴の完全なカタログ	commercetools-integrations: search/search-contract.md
同期を検証する：公開すると表示され、非公開化／削除すると消えること、全件ロードの件数が一致すること、再実行が冪等であること、Store ごとのスコープ。結果整合性、可用性のずれ、非アトミックな再構築の落とし穴	commercetools-integrations: search/verification.md

配送コネクターの統合または構築（サブ領域）

まず概要を確認してください。概要から、残りの資料に進めます（まずネイティブの配送方法に該当しないことを確認し、その後、公開コネクターを使用するか、カスタマイズ／フォークするか、ユーザーが指定する運送業者または料金サービス向けに構築します）。Checkout の配送コネクター契約も配送テンプレートもありません（ただし、shipping はレジストリの検索に使える有効な Connect IntegrationType です）。また、配送ベンダーはベンダーホスト型の統合を提供していることが特に多いため、推奨する前にMarketplace の掲載内容がすべて Connect コネクターとは限りませんを適用してください。対象範囲の境界：すでに運送業者の予約を行う OMS/WMS は、出荷と追跡を担います。これは注文管理の領域であり、ここでは扱いません。

関心事	参照先
まずここから — ワークフロー：段階 0 のネイティブ機能判定 → 要件 → ネイティブ機能の使用／利用／カスタマイズ／構築 → 設定 → アプリ → 検証；最初に明示すべき 3 つの事実と、commerce-patterns、OMS、税務との対象範囲の境界	commercetools-integrations: shipping/overview.md
ネイティブ機能を使うか、利用するか、カスタマイズするか、構築するか？ 段階 0 の表（ゾーン／段階／述語／確定料金と見積もりの違い、および実際のコネクター）、shippingRateInputType と 100 件の Shipping Method 制約、ライブチェック、ベンダーホスト型の落とし穴、スキャフォールド元のテンプレート	commercetools-integrations: shipping/connector-selection.md
契約（コーディング前に読むこと）：確定処理の選択（段階別の setShippingRateInput と setCustomShippingMethod／addCustomShippingMethod の比較）およびその matching-cart への影響；料金拡張機能のタイムアウト予算（デフォルト 2 秒、最大 10 秒）、キャッシュ、フェイルオープン；オプション一覧エンドポイント；ラベルと追跡情報の書き戻し（addDelivery／addParcelToDelivery／setParcelTrackingData。deliveryKey に対して冪等）；Single モードと Multiple モード；落とし穴の完全な一覧	commercetools-integrations: shipping/shipping-contract.md
要件 → connect.yaml：必要なアプリケーション、運送業者の認証情報、有効化する運送業者／サービスレベル／発送元／マークアップ、タイムアウトとフォールバックのキー、最小権限のスコープ、実際の postDeploy 作業（フォールバックの Shipping Method、Types、Extension、認証情報の検証）；記述例	commercetools-integrations: shipping/config-from-requirements.md
一連の処理を検証する：見積もり → 表示されるオプション → Cart の価格 → Order の価格 → ラベル → 追跡情報；ブロックされたカート、表示されないオプション、サンドボックスでの料金一覧取得、重複 Delivery の落とし穴	commercetools-integrations: shipping/verification.md

関連スキル： SDK クライアントのセットアップ、スコープ、クエリー述語、コアデータモデルはcommercetools-platformにあります。このページでクライアント／認証の基本を繰り返すのではなく、そちらを参照してください。税務のモード（Platform／External／ExternalAmount／Disabled）、割引の適用順序、sortOrder の意味、ドメイン概念としての Direct-Discounts による Discount-Codes のブロックは、commercetools-commerce-patternsにあります。これらのサブ領域では、それらを実現するコネクターを扱います。