カスタム統合

始めるには営業チームに連絡してアカウントを作成し、契約にサインしてください。契約がサインされると、確認が必要な2つのマイクロデポジットがアカウントに送信されます。

これらのマイクロデポジットの金額をaccounting@zonos.comに、ダッシュボードストアIDを添えてメールしてください（営業担当者をCCしてください）。

確認が完了すると、銀行情報がダッシュボード -> 設定 -> 請求に表示されます。

Zonosアカウントを作成した後、ダッシュボードの設定を構成してCheckoutがストアで正しく機能するようにする必要があります。このセクションでは、すべての重要なダッシュボード設定をカバーします。

支払いの設定

Checkoutからタイムリーな支払いを受け取るために、銀行口座を接続します。支払いは、キャプチャされた支払いから2日以内に毎日処理されます。これを行うには、次の手順に従ってください。

1. ダッシュボード -> 設定 -> Checkout設定に移動します。
2. 銀行口座を追加をクリックします。
3. セットアップを完了し、次の情報を提供するためにStripeポータルに移動します：
   • 銀行口座情報。
   • 会社のEIN。
   • 25%の会社所有者の社会保障番号。これが必要な理由の詳細については、Stripeドキュメントを参照してください。

注意: 支払いスケジュールを更新する必要がある場合は、support@zonos.comに連絡してください。

許可されたドメインの設定

Zonos JSスクリプトは、セキュリティ上の理由から許可されたドメインのリストを必要とします。これにより、未承認のサイトがスクリプトを読み込むことを防ぎ、承認されたドメインでのみ実行されることを保証します。この設定がないと、スクリプトは権限エラーを返します。

これを設定するには：

1. ダッシュボード -> 設定 -> Checkout設定に移動します。
2. URLの下に、Checkoutが使用されるフルドメインとサブドメインを追加します。たとえば、ドメインがexample.comの場合、example.comとtest.example.comを追加する必要があります。

ブランド設定のカスタマイズ

ダッシュボードでブランド設定を構成して、ストアの外観に合わせます。

これを行うには、次の手順に従ってください：

1. ダッシュボード -> 設定 -> Checkout設定 -> ブランドに移動します。
2. 次の設定を構成します：
   • ロゴ。
   • ブランドおよびアクセントカラー。
   • テーマ、スタイル、フォント。

ブランド設定の詳細についてはドキュメントを参照してください。

配送業者を接続する

checkoutで配送を見積もるには、Zonosアカウントに配送業者を接続する必要があります。これにより、checkoutで特定の配送サービスレベルを有効にできます。

配送業者を接続するには、次の手順に従ってください：

1. ダッシュボード -> 設定 -> 配送 -> 料金に移動します。
2. 配送業者を追加をクリックします。
3. 配送業者のセットアップ手順に従います。

配送業者アカウントの接続に関する詳細はドキュメントを参照してください。

配送ゾーンを設定する

配送ゾーンを使用すると、世界のさまざまな地域に対してどの配送業者とサービスレベルが利用可能かを構成できます。

配送ゾーンを設定するには、次の手順に従ってください：

1. ダッシュボード -> 設定 -> 配送 -> 場所に移動します。
2. 新しいゾーンをクリックします。
3. ゾーン名を入力し、配送先の国を選択します。
4. 提供したい配送業者とサービスレベルを選択します。

配送ゾーンに関する詳細はドキュメントを参照してください。

フォールバックの原産国とHSコードを設定する

原産国とHSコードは、正確な関税と税金を計算するために使用されます。

特定の原産国やHSコードを提供しない場合、ダッシュボードに設定されたフォールバックが使用されます。

フォールバックの原産国とHSコードを設定するには：

1. ダッシュボード -> 設定 -> 配送 -> カタログに移動します。
2. 原産国には、製品の大部分が製造されている国を選択します。
3. HSコードには、最も一般的な製品のHSコードを入力します。HSコードがない場合は、ダッシュボードClassifyに移動し、製品の名前と説明を入力して正確なHSコードを生成します。

Zonos JSスニペットは、サイトでのグローバルcheckout機能を有効にするクライアントサイドのJavaScript統合です。これは、eコマースプラットフォームとZonosサービスの間の橋渡しを行い、以下を処理します：

• Checkout体験：checkout UIをレンダリングし、支払いを処理します。
• 位置情報サービス：訪問者の位置を検出し、通貨変換を管理します。
• カート統合：既存のカートおよび注文システムと接続します。
• セキュリティ：ドメインを検証し、APIリクエストを認証します。

スニペットは非同期で読み込まれ、サイトのパフォーマンスに影響を与えないようにします。ストアのAPI資格情報で初期化され、すべてのクライアントサイドのインタラクションを安全に処理します。実装は非侵襲的に設計されており、既存のcheckoutフローに最小限の変更を必要とします。

以下は、Checkoutを統合する際に参照するための、スクリプトの読み込み、初期化、およびイベント処理を含む完全な例です。

<script>
  (async function () {
    const timestamp = new Date().getTime();
    const zonosScript = document.querySelector(
      `script[src*="https://cdn.jsdelivr.net/npm/@zonos/elements/dist/scripts/loadZonos.js"]`,
    );

    if (!zonosScript) {
      const script = document.createElement('script');
      script.src = `https://cdn.jsdelivr.net/npm/@zonos/elements/dist/scripts/loadZonos.js?timestamp=${timestamp}`;

      script.addEventListener('load', () => {
        window.Zonos.init({
          checkoutSettings: {
            createCartId: async () => {
              // Replace with your server-side cart creation logic
              return {
                cartId: 'cart_73e707c0-c161-4c37-9581-4da1b1115777',
              };
            },
            placeOrderButtonSelector: '#placeOrder, .place-order', // Replace with your actual selector(s)
          },
          helloSettings: {
            currencyElementSelector: '.price',
            onInitSuccess: () => {
              Zonos.openHelloDialog();
            },
          },
          storeId: 7744, // Replace with your actual store ID
          zonosApiKey: 'credential_live_7a128f4e-f192-4232-8992-94dd09eb4437', // Replace with your actual API key
        });
      });

      document.head.appendChild(script);
    }
  })();
</script>

注意: プレースホルダー値 (storeId, zonosApiKey, selectors など) をあなたの Zonos ダッシュボードからの実際の値に置き換えてください。

ブラウザキャッシュの処理

ブラウザによってスクリプトがキャッシュされないように、URLにタイムスタンプやその他のユニークな識別子を追加することをお勧めします。これにより、常に最新のバージョンのスクリプトが読み込まれることが保証されます。これは完全な例の10行目に示されています。

      script.src = `https://cdn.jsdelivr.net/npm/@zonos/elements/dist/scripts/loadZonos.js?timestamp=${timestamp}`;

Zonos JSスニペットの認証

Zonos JSスクリプトを読み込んだら、公開されたZonos APIキーとストアIDをZonos.init関数に渡すことで認証する必要があります。Checkoutを認証するために使用される公開APIキーは、公開可能であるように設計されており、機密情報を露出することなくフロントエンドコードで安全に使用できます。

ストアIDとAPIキーを見つけるには、ダッシュボード -> 設定 -> 統合に移動してください。フロントエンドコードで使用するために設計されていないシークレットAPIキーを使用しないようにしてください。これは、完全な例の29行目と30行目に示されています。

Zonos.init({
  // ... other fields
  zonosApiKey: 'Your API KEY', // Replace with your actual API key (found in Dashboard)
  storeId: 'Your STORE ID', // Replace with your actual store ID (found in Dashboard)
  // ... other fields
});

Helloは、Checkoutを使用する際に必要です。

Helloは、訪問者の位置情報、言語、通貨を検出し、適切な情報を表示する役割を担っています。すべてHello設定は、ダッシュボードまたはZonos JSスクリプトで構成できます。すでにダッシュボードでHelloを設定している場合、スクリプトはそれらの設定を読み込み、使用します。Zonos.init関数のhelloSettingsプロパティに値を指定した場合、スクリプトは以下に示すようにそれらの値を代わりに使用します。

JSスクリプトでのHelloの通貨変換の設定

Helloは、通貨情報を表示するサイト上の要素を特定するためにCSSセレクタを使用します。これらのセレクタをZonos.init関数のhelloSettings.currencyElementSelectorプロパティに渡すことで、Helloは国際的なショッパーの正しい通貨を検出し、表示することができます。

ここでは、#price, .priceのように、複数の異なる要素を選択するために任意有効なCSSセレクタを使用できます。これは、完全な例の23行目と24行目に示されています。

Zonos.init({
  // ... other fields
  helloSettings: {
    currencyElementSelector: '.price', // Replace with your actual selector
  },
  // ... other fields
});

ページ読み込み時にHelloを自動的に開く

デフォルトでは、Helloは訪問者がフラグボタンをクリックしたときのみ開きます。ページが読み込まれたときにHelloを自動的に開きたい場合は、Zonosスクリプトが読み込まれた後にZonos.openHelloDialog()関数を呼び出すことができます。これは、完全な例の25行目と26行目に示されています。

Zonos.init({
  // ... other fields
  helloSettings: {
    // ... other hello settings
    onInitSuccess: () => {
      Zonos.openHelloDialog();
    },
  },
});

Checkoutは、顧客が配送先および請求先情報を入力し、landed costを計算し、collect支払いを受け取り、注文を完了することを可能にします。

Checkoutは、訪問者の位置情報、言語、通貨などの文脈データをHelloと共有します。これにより、顧客の体験がショッピングプロセス全体で一貫性を保つことができます。

すべてのCheckout設定は、ダッシュボードとZonos JSスクリプトの両方で構成できます。すでにダッシュボードでCheckoutを設定している場合、スクリプトはそれらの設定を読み込み、使用します。Zonos.init関数のcheckoutSettingsプロパティに値を指定した場合、スクリプトはそれらの値を代わりに使用します。

JSスクリプトでの「注文を確定」ボタンの設定

Zonos JSスクリプトは、国際的なショッパーを自動的に認識し、Checkoutフローに誘導します。ただし、クリック時にCheckoutを開くように、プラットフォーム上の「注文を確定」ボタンを設定する必要があります。これは、Zonos.init関数のcheckoutSettings.placeOrderButtonSelectorプロパティにCSSセレクタを渡すことで行えます。

複数のボタンが注文を確定するために使用できる場合は、各ボタンのセレクタを渡すようにしてください。例えば、#placeOrder, .place-orderのようにします。

これは、完全な例の21行目に示されています。

Zonos.init({
  // ... other fields
  checkoutSettings: {
    // ... other fields
    placeOrderButtonSelector: '#placeOrder', // Replace with your actual selector(s)
  },
});

サーバーサイドでカート詳細を安全に作成する

顧客にカート詳細を表示するためには、Zonos APIを呼び出してカートを作成するサーバーサイド関数を作成し、そのカートIDをフロントエンドに返す必要があります。これにより、カート詳細が顧客に操作可能な形で公開されることを防ぎます。

バックエンドAPI呼び出しでは、Zonos JSスクリプトを認証するために使用する公開トークンとは異なる秘密のGraphQL認証トークンを使用します。このトークンは、Dashboard -> Settings -> Integrations で取得できます。秘密のトークンは、API呼び出しのヘッダーとして渡す必要があります。

cartCreate ミューテーションはカートアイテムスキーマ に従ってフォーマットされたアイテムのリストを受け入れます。

// Create new cart from serverside
async function createCart() {
  /**
   * Full cart mutation schema: https://zonos.com/developer/mutations/cartCreate
   * */
  const graphql = JSON.stringify({
    query: `
mutation cartCreate($input: CartCreateInput!){
  cartCreate(input: $input) {
    id
    adjustments {
      amount
      currencyCode
      description
      productId
      sku
      type
    }
    items {
      id
      name
      amount
      currencyCode
      quantity
      sku
      description
      metadata {
        key
        value
      }
    }
    metadata {
      key
      value
    }
  }
}`,
    variables: {
      /**
       * input for the cartCreate is this schema https://zonos.com/developer/types/CartCreateInput
       */
      input: {
        /**
         * Cart adjustment input: https://zonos.com/developer/types/CartAdjustmentInput
         */
        adjustments: [
          {
            amount: -10,
            currencyCode: 'USD',
            /**
             * Enum value: https://zonos.com/developer/types/CartAdjustmentType
             */
            type: 'CART_TOTAL',
          },
        ],
        /**
         * Cart item input: https://zonos.com/developer/types/ItemInput
         */
        items: [
          {
            name: 'Item 1',
            amount: 150.99,
            currencyCode: 'USD',
            description: 'Item 1 description',
            quantity: 2,
          },
        ],
        /**
         * Cart metadata input: https://zonos.com/developer/types/CartMetadataInput
         */
        metadata: [
          {
            key: 'key1',
            value: 'value1',
          },
        ],
      },
    },
  });

  const response = await fetch('https://api.zonos.com/graphql', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      credentialToken: 'credential_live_xxxxxxxxx', // Replace with your actual SECRET credential token (found in Dashboard)
    },
    body: graphql,
  });

  const { data } = await response.json();
  return data.cartCreate.id; // Return the cart ID to your frontend
}

私たちは、サーバーサイドにAPIエンドポイントを作成し、そのエンドポイントをフロントエンドのJS統合から呼び出すことをお勧めします。これは次のステップで詳しく説明します。

フロントエンド経由でCheckoutにカートIDを渡す

サーバーサイドでカートを作成したら、カートIDをZonosのJSスクリプトに渡す必要があります。これは、Zonos.init関数の一部であるcreateCartIdコールバックを使用することで実現できます。Checkoutは、その後、安全にZonosからカートの詳細を取得し、カートの改ざんを防ぎます。以下のコード例を参照してください。

createCartIdの値は静的な値ではなく、関数でなければなりません。

Zonos.init({
  // ... other fields
  checkoutSettings: {
    // Replace with your actual selector(s)
    createCartId: async () => {
      const response = await fetch('https://api.merchant.com/api/get-cart', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
        },
      });
      const json = await response.json();

      return json.id; // Only need to return the cart ID
    },
  },
});

あなたのシステムとZonosダッシュボード間で注文を同期するには、これらのAPI呼び出しとWebhookを実装してください。

必要なミューテーション

必要なWebhook

Checkout統合を本番環境に移行する前に、顧客体験をスムーズにするために統合のすべての側面を徹底的にテストすることが重要です。これには、checkoutフロー、支払い処理、注文作成、Webhook機能のテストが含まれます。

テストガイドに従って、統合が正しく機能していることを確認し、本番環境に移行する前に問題を特定して修正してください。

以下は、統合プロセスに関する一般的な質問です。

Zonosは注文確認をどのように処理しますか？

Zonosは、注文確認に使用できる組み込みのサンキューページを提供します。このページは、注文があなたのシステムにインポートされない場合でも常に表示され、顧客が購入の確認を受け取ることを保証します。

注文が作成されたときに通知を受け取ることはできますか？

はい。注文が作成されたときに通知を受け取りたい場合は、ダッシュボードCheckout設定のEmailセクションに、注文が作成、出荷、またはキャンセルされたときに通知を受け取るべきチームメンバーのメールアドレスを入力できます。