Salesforce Commerce Cloud向けZonos Checkout

metadata.zip の準備ができたら、SFCCサンドボックスにインポートします：

1. Business Manager > Administration > Site Development > Site Import & Export に移動します。
2. Local アップロードオプションを使用して metadata.zip をアップロードします。
3. アップロード後、リスト内のアーカイブを見つけて Import をクリックします。

この手順により、Zonos統合で使用される必要なサイト設定、サービス、認証情報、カスタムオブジェクトが作成されます。

サイトのカートリッジパスに int_zonos カートリッジを追加して、コントローラー、スクリプト、テンプレートを有効化します：

1. Administration > Sites > Manage Sites > [Your Target Site] > Settings に移動します。
2. ベースSFRAストアフロントカートリッジ（app_storefront_base）の前にカートリッジパスに int_zonos を挿入します。

カートリッジに含まれる2つのカスタムPipelineがあり、Business Manager内でパイプラインエイリアスを追加する必要があります：

Zonos-OrderConfirmation

Zonos Checkout内で注文が完了した後、SFCC内のカスタム注文確認に使用されます。ユーザーはここにリダイレクトされます。例えば、エイリアスは zonos-order-confirmation になる場合があります。ネイティブのSFCC/SFRAチェックアウト注文確認ページ（COSummary-Submit）で使用するエイリアスとは異なる、ビジネスに適したエイリアスを選択して追加してください。

Zonos-PlaceSFCCOrder

SFCC/SFRA内でZonos注文を作成するために使用されるカスタムエンドポイントで、エイリアスは zonos-placesfccorder であると想定されています。ここで異なるエイリアスを使用する場合、サービス設定の段階でこれを記録する必要があります。これは公開向けURLではないため、初期設定では zonos-placesfccorder の使用を推奨します。これにより、このカートリッジを簡単に使用できます。

これら2つのエイリアスを設定するには、Business Managerで Merchant Tools > URL Rules > Pipeline URLs に移動します。

手順2のサイトインポートにより、2つのSFCCサービス（付随するプロファイルと認証情報付き）が作成されました：zonos.api.graphql と create.order.api.sfra。

単一サイトの設定

組織内に単一のストアフロントサイトのみがある場合、ここで追加の作業は不要で、次の手順に進めます。

複数サイトの設定

組織内に複数のストアフロントサイトがある場合、または複数のストアフロントサイトを計画している場合、SFCCサービスの更新/追加が必要です。Zonos統合を利用する複数のSFCCサイトがある場合、各サイトに注文作成APIサービスが必要です。各サイトについて、以下を実行します：

1. create.order.api.[siteID] という名前で新しい認証情報を作成します。
2. 認証情報URLを https://[Sandbox Host]/s/[Site ID]/Zonos-PlaceSFCCOrder に設定します（例：https://wxyz-001.dx.commercecloud.salesforce.com/s/RefArch/zonos-placesfccorder）。
3. create.order.api.[siteID] という名前で新しいサービスを作成し、create.order.api プロファイルと手順1で作成した create.order.api.[siteID] 認証情報を割り当てます。

完了すると、各サイトに注文作成APIサービスが1つずつあるはずです。

注： 元の create.order.api.sfra サービスをいずれかのサイトの注文作成サービスにリネームせず、まだ存在する場合は削除できます。zonos.api.graphql サービス名はそのままにしてください。複数サイトがあっても、Zonos APIサービスは1つだけ必要です。

Business Managerで Merchant Tools > Site Preferences > Custom Preferences に移動し、zonos 設定グループをクリックしてZonosカスタムサイト設定にアクセスします。

サイトの以下のサイト設定を行います：

Zonos Modal Checkout中、買い物客はZonos Dashboardで定義された配送方法を選択します。これらの注文がSFCCにインポートされる際、配送方法は有効なSFCC配送方法に対応している必要があります。これをサポートするには：

1. Zonosの配送方法をマッピングするSFCC配送方法を1つ以上設定します。
2. 上記の Zonos Ship Method Mapping カスタムサイト設定で、Zonos配送方法とSFCC配送方法の間に1つ以上の配送方法マッピングを確立します。

配送方法マッピング

JSONオブジェクトの形式で、配送方法マッピングはZonos配送方法をSFCC配送方法にマッピングします。このマッピングには、Zonos Checkoutで選択される可能性のあるすべてのZonos配送方法（サービスレベル）のマッピングレコードが必要です。Zonos注文がSFCC配送方法へのマッピングが存在しない配送方法で配置された場合に使用される default マッピングレコードも含めることを強く推奨します。これにより、SFCC注文に配送方法がないことによる下流の障害を防げます。

JSONオブジェクトの形式は次のとおりです：

{
  "[Zonos Shipping Service Level Code]": "[SFCC Shipping Method ID]",
  ...
  "default": "[Default SFCC Shipping Method ID]"
}

例

Zonos Dashboardで以下のサービスレベルを有効にしていると仮定します：

理由（バックオフィス要件、追加のサードパーティ配送サービス統合など）により、サイトのSFCC配送方法は以下に限定されている場合があります：

新しいZonos注文を受信してSFCCに配置する際、配送方法はこのリストから選択する必要があります。

マッピングを構築するには、Zonos Dashboardにログインし、Shipping > Manage Rates に移動して、表示される各 Enabled service levels をクリックすると、以下のような表示が見られます：

各項目で Edit details をクリックして、Zonos配送サービスレベルコードを取得（または設定）します（下記参照）。

配送サービスレベルコードを使用して、Zonos Checkoutでその配送サービスレベル（Zonos配送方法）が選択されたときにSFCC注文に表示したいSFCC配送方法にマッピングするレコードを作成します。

有効な各配送サービスレベルコードのレコードと default 配送方法マッピングを追加すると、Zonos Ship Method Mapping JSONオブジェクトは次のようになります：

{
  "ups.worldwide_saver": "004",
  "ups.standard": "002",
  "ups.worldwide_expedited": "012",
  "ups.worldwide_express": "012",
  "default": "001"
}

注： これはZonos配送方法からSFCC配送方法へのマッピングのみであるため、マッピングに含める必要があるのはすべてのZonos配送方法のみです。各SFCC配送方法をマッピングに含める必要はありません。

インストールには、Zonos統合をサポートする2つのSFCCジョブが含まれています：

CreateOrdersFromZonos

このジョブは zonosOrders カスタムオブジェクトストア内の新しく作成されたZonos注文参照を検索し、Zonosから完全な注文詳細を取得して、SFCC内に対応する注文を作成します。

スケジュール： ビジネスニーズに合わせてこのジョブをスケジュールできますが、通常、このジョブは比較的頻繁に（例：5〜10分ごと）間隔ベースで実行するように設定し、週の各日に実行する必要があります。

カスタムパラメーター： CreateOrdersFromZonos ジョブにはカスタムパラメーターは含まれていません。

CreateMissingZonosOrders

稀であるべきですが、予期しない状況により、通常のプロセスを経由してSFCCインスタンスに到達しないZonos注文が存在する可能性があります。このため、CreateMissingZonosOrders ジョブを含めています。このジョブはZonos注文履歴とSFCC間のクロスチェックを実行し、不足している注文を特定してインポートします。

スケジュール： ビジネスニーズに合わせてこのジョブをスケジュールできますが、CreateOrdersFromZonos ジョブよりも低頻度で実行するようにスケジュールする必要があります。このジョブの実行頻度をスケジュールする際に考慮すべき事項：

1. すべてのジョブと同様に、処理負荷/帯域幅とビジネスニーズを含むすべてを考慮した後、このジョブは可能な限り低頻度で実行するようにスケジュールする必要があります。
2. このジョブは一定期間のすべての注文をクエリするため、高トラフィックサイトではより頻繁に実行する必要があります（ジョブ実行あたりの処理注文数が少なくなるため）。一方、低トラフィックサイトは低頻度でも問題ありません。
3. ほとんどのサイトで機能すると考えられる CreateMissingZonosOrders のベースライン推奨頻度は、90分に1回です。

カスタムパラメーター： CreateMissingZonosOrders ジョブステップに関連する2つのカスタムパラメーターを設定する必要があります：

1. LookBackHours: ジョブが実行される時点から遡って、ジョブがZonosで不足している注文を検索する時間（時間数）です。ジョブのスケジュール頻度に基づき、この値はジョブ実行間隔以上である必要があり、理想的には重複がある必要があります。例えば、ジョブが90分ごとに実行されるようにスケジュールされている場合、LookBackHours を 2（時間）に設定します。デフォルト値（値が設定されていない場合）：2
2. OrderSize: Zonosの内部クエリごとに取得する最大注文数。ジョブがZonosで注文をクエリする際に使用するページサイズと考えてください。デフォルト値（値が設定されていない場合）：20

Zonos Helloは、動的言語選択、関税/税金メッセージ、インライン通貨変換などのクライアント側ローカライゼーション機能を提供します。サイト設定でZonosが有効になると、HelloはZonosクライアントスクリプト経由でストアフロントに自動的に読み込まれます。

Zonosクライアントスクリプトは、以下のオーバーレイテンプレートの下部にある Zonos-ClientScriptInclude エンドポイントのSFCCリモートインクルードを使用して追加されます：

• /cartridge/templates/default/common/layout/page.isml
• /cartridge/templates/default/common/layout/checkout.isml

プロジェクトがこれらのテンプレートを優先度の高いカートリッジでオーバーライドしている場合、カスタマイズしたバージョンにリモートインクルードが追加されていることを確認してください：

<isinclude url="${URLUtils.url('Zonos-ClientScriptInclude', 'pageType', pdict.action)}"/>

Zonos Helloの詳細はこちらをご覧ください。

Zonos Helloは、ストアフロントに表示される価格値を買い物客の現地通貨に自動的に変換します。これを正しく機能させるには：

1. 価格値はjQueryで選択できるクラス名またはIDを使用したHTML要素でラップする必要があります。例：<p class="text-right sub-total zonos-price">${pdict.totals.subTotal}</p>
2. これらのセレクター値は Currency Element Selector サイト設定（またはZonos Dashboard）に含める必要があります。

価格表示コードの変更

Zonosカートリッジには、参照アーキテクチャサイト全体で価格がレンダリングされる場所の以下のオーバーレイテンプレートが含まれており、それぞれの価格を含むHTML要素に zonos-list-price、zonos-sales-price、zonos-price クラス名が割り当てられています：

• /cartridge/templates/default/cart/productCard/cartCouponDisplay.isml
• /cartridge/templates/default/cart/cartTotals.isml
• /cartridge/templates/default/checkout/billing/billingSummary.isml
• /cartridge/templates/default/checkout/cart/miniCart.isml
• /cartridge/templates/default/chackout/productCard/productCardProductTotalPrice.isml
• /cartridge/templates/default/product/components/pricing.isml
• /cartridge/templates/default/product/components/setPrice.isml

カートリッジパスで int_zonos より高い優先度で設定された、これらのテンプレートを含むカートリッジがない場合、Zonos Helloがサイト上のこれらの価格レンダリングの通貨を変換するためにコード変更は不要です。カートリッジパスで int_zonos より高い1つ以上のカートリッジにこれらのテンプレートのカスタマイズ版がある場合、カスタマイズしたテンプレート内の価格を囲むHTMLラッパーに一意のクラス名を含める必要があります（上記の例を参照）。

価格要素セレクター文字列の設定

通貨セレクター文字列は、Zonosスクリプトが通貨変換更新を受けるべき価格値を含むHTML要素を識別するために使用するjQuery形式のセレクター文字列値です。この値は、前の手順で説明したサイトの価格表示を囲むHTML要素に割り当てられたCSSクラス名および/またはIDのスペース区切りリストである必要があり、クラス名には . プレフィックス、IDには # プレフィックスを付けます（引用符なし）。例えば、サイトがZonosカートリッジに含まれる価格表示テンプレートを使用する場合、セレクター文字列は .zonos-list-price .zonos-sales-price .zonos-price になります（引用符なし）。

通貨セレクター文字列は、Zonos DashboardまたはBusiness ManagerのZonosカスタムサイト設定の Currency Element Selector サイト設定で構成できます。

注： 両方の場所で設定されている場合、Business Managerの値が優先されます。

Zonos Hello通貨変換の詳細はこちらをご覧ください。

チェックアウトボタンセレクター文字列は、Zonosスクリプトがサイト上でクリックすると顧客をサイトのチェックアウトフローに進めるボタンコントロールとして機能するHTML要素を識別するために使用するjQueryセレクター文字列値です。

買い物客が設定したセレクター文字列に一致したCheckoutボタンをクリックすると、Zonosは自動的にアクションをインターセプトしてモーダルCheckoutを開きます。

チェックアウトボタンセレクター文字列は、Zonos DashboardまたはBusiness ManagerのZonosカスタムサイト設定の Place Order (Checkout) Button Selector サイト設定で構成できます。

ユーザーがZonosホスト型Checkout内で注文を完了すると、SFCC内で注文確認を表示するカスタムPipeline（Zonos-OrderConfirmation）にリダイレクトされます。この注文確認の主要レンダリングテンプレートは /int_zonos/cartridge/templates/default/checkout/confirmation/zonosConfirmation.isml です。

この注文確認ページは、ネイティブのSFCC/SFRA注文確認ページと同じスタイリングを使用し、ネイティブのSFCC/SFRA注文確認ページと一部の.ismlファイルを共有しています。サイトに既に行われたカスタムスタイル更新に合わせるために、スタイル更新が必要な場合があります。Zonos注文確認テンプレートで使用されるベースレンダリングテンプレートには以下が含まれます：

• app_storefront_base\cartridge\templates\default\checkout\confirmation\confirmationDetails.isml
• app_storefront_base\cartridge\templates\default\checkout\shipping\shippingSummary.isml
• int_zonos\cartridge\templates\default\checkout\billing\billingSummary.isml
• app_storefront_base\cartridge\templates\default\checkout\orderProductSummary.isml
• app_storefront_base\cartridge\templates\default\checkout\orderTotalSummary.isml

ユーザーへの注文確認表示以外の、このカスタムパイプラインに関連する基盤機能は、データインポートに含まれる新しいカスタムオブジェクトタイプ zonosOrders に関連しています。ユーザーに注文確認が表示されると、SFCCは注文確認URLに表示されるZonos注文IDを使用し、Zonos注文IDをカスタムオブジェクトのKey Attributeとして対応するカスタムオブジェクトを作成します。これはジョブ CreateOrdersFromZonos 経由でSFCC内に注文を配置するために使用されます。このジョブは createdStatus = - None - の zonosOrders タイプのすべてのカスタムオブジェクトを反復処理します。ジョブは以下のタスクを実行します：

1. Zonosで注文詳細をクエリします。
2. このレスポンスを使用して、レスポンス内の商品、配送、請求、顧客の詳細と、サイト設定で設定された配送方法および決済方法に基づいてSFCC内に注文を作成します。
3. ミューテーション経由でZonosをSFCC注文番号で更新し、Zonos Dashboard内のZonos注文番号と関連付けます。

上記の手順が成功した場合、カスタムオブジェクト属性 createdStatus は created に設定され、今後の処理対象から除外されます。上記の手順が成功しない場合、カスタムオブジェクト属性 createdStatus は failed に設定され、プロセス中にエラーを返したシステムに応じて、オブジェクトの属性 errorResponse（Zonos）または sfccErrorResponse（SFCC）にエラーメッセージが記録されます。

注文の配置を再試行する必要がある場合は、createdStatus を - None - に再設定するだけで、次のジョブ実行で処理対象になります。

オプション—以下の設定は詳細設定です。デフォルトが設定されているため、対応は不要です。調整したい場合は、以下のガイドラインに従ってください：

インポート時に請求書を作成

デフォルトで Yes に設定されています。Zonosは注文インポート時に請求書を作成します。この機能を無効にする場合、独自の請求書を作成する必要があり、Zonosは不正レビューホールドを zonos_hold ステータスに設定します。不正が解除されると、以前のステータスに戻ります。

顧客ログイン

デフォルトで No に設定されています。チェックアウトにアカウントを必須にしたい場合、Yes に切り替えます。Customer configuration > Login options に移動し、Redirect Customer to Account Dashboard after Logging In を No に更新する必要もあります。

SFCC注文エクスポート

SFCC Order Exportを使用している場合、または使用を計画している場合、OrderオブジェクトとProductオブジェクトに割り当てられたZonosカスタム属性がSFCC注文エクスポートファイルに含まれていることを確認してください。Merchant Tools > Site Preferences > Orders から、注文エクスポートスキーマバージョンを最新バージョンに設定します。

アカウントとアプリの設定が完了したら、統合のテストの準備ができています。テスト中はSFCCでCheckoutとHelloを有効にする必要があります。手順：

1. Merchant Tools > Site Preferences > Custom Preferences > zonos に移動します。
2. Zonos Enabled を Yes に切り替えます。

サイトのカスタムサイト設定にZonosアカウント情報が設定され、Zonos Enabled 機能スイッチがYESに設定されると、サイトURLに以下のパラメーターを追加してストアフロントでZonos機能をテストできます：zCountry=[Zonos Dashboardで有効にした国の国コード]

例えば、カナダを有効にしている場合：https://abcd-001.dx.commercecloud.salesforce.com/on/demandware.store/Sites-RefArch-Site?zCountry=CA

注： これはZonos Public API Tokenがテスト認証情報トークンで設定されている非本番環境でのテストにのみ必要です。本番/ライブAPIトークンで設定されている場合、zCountry URLパラメーターは不要であり、想定もされていません。

まだ本番公開の準備ができていない場合は、テスト完了後に Zonos Enabled を No に戻すことを忘れないでください。テスト完了後、上記と同じ手順でZonosを有効にします。

商品情報は関税・税金の金額と配送コストに影響します。Zonosに提供する商品情報が多いほど、返される見積もりはより正確になります。Zonosはこの情報が利用できない場合でも見積もりを生成できますが、精度向上のために以下の主要な商品詳細の提供を推奨します：

• 重量： 重量は配送コストに影響し、関税や税金に影響する場合があります。SFCC商品リストの重量は、存在する場合Zonosによって自動的に使用されます。
• 寸法： 寸法は配送コストに影響し、関税や税金に影響する場合があります。ZonosはSFCCの各商品に設定された商品寸法（長さ、幅、高さ）を利用できますが、適切な統合のためにZonosカスタムサイト設定でマッピングする必要があります。
• HS code： HS codeは関税率に影響し、場合によっては税金にも影響します。ZonosはSFCCの商品リストに設定されたHS codeを使用できますが、Zonosカスタムサイト設定でHS codeフィールドをマッピングする必要があります。
• 原産国： 商品の原産国は関税率に影響し、税金に影響する場合があります。SFCC商品リストに設定された原産国は、存在する場合Zonosによって自動的に使用されます。

注： または、Catalogに情報を入力して、SFCCから保存・送信される情報を上書きすることもできます。

プラットフォーム別の商品情報の詳細はこちらをご覧ください。