Miva向けCheckout

サインアップから24時間以内に、専任のオンボーディング担当者が連絡し、カスタマイズされた統合プロセスを開始します。

Important: 以下に記載の手順は参考用であり、オンボーディング担当者がご案内します。

1. Miva App Storeからモジュールをダウンロードするか、zonos.mvc ファイルを直接Zonosにリクエストしてください。
2. Miva管理画面で Domain Settings -> Modules -> Add Module に進み、zonos.mvc ファイルをアップロードして Add をクリックします。

3. Settings -> Modules に進み、Zonosを見つけて Install をクリックします。Installed と表示されることを確認してください。

Mivaで Users -> API Tokens に移動し、Add API Token をクリックします。以下のように設定します：

• Name: Zonos Checkout
• Allowed IP Addresses: 0.0.0.0/0, ::/0
• Signature: Require Signature with Key -- Generate をクリックして署名キーを作成します
• Timestamp: Require Timestamp Within 30 seconds

次の画面で Customer Service & Sales を有効にして、トークンが注文の作成・変更を行えるようにします。Save をクリックします。

Miva -> Utility Settings -> Zonos に移動してCheckoutモジュールを開き、以下のフィールドを入力します：

1. Store ID: Dashboard -> Settings -> Account -> Integrations から Zonos account number をコピーします。
2. Zonos API Key: シークレットAPIキーです（これは絶対に共有しないでください）。
3. Zonos Public Key: パブリックキーです。
4. Store Currency: ストアの基本通貨です（例：USD）。
5. Environment: 本番環境では Live、テストでは Test を選択します。
6. Checkout Button Selector: チェックアウトボタンのCSSセレクタです（例：a[href*="checkout.html"]）。
7. Hidden Selectors: 国内向け決済オプションなど、海外のお客様に関係のない項目を非表示にするために使用します。
8. Import Orders: 完了したZonos注文を自動的にMiva管理画面にインポートするにはチェックを入れます。これには次のステップでWebhookを登録する必要があります。

続行する前に、右上の Update をクリックして保存してください。

10.xモジュールでは、注文はWebhook経由でインポートされます。以前のモジュールバージョンでは、代わりに注文完了URL/エンドポイントが使用されていました。

設定を保存したら、Register Webhooks をクリックします。これによりストアがZonosと接続され、完了した注文が自動的にインポートされ、キャンセルが同期され、配送状況の更新がMivaに反映されるようになります。

注文のインポート、キャンセルの同期、配送状況の更新を機能させるには、事前にWebhookを登録する必要があります。Import Ordersチェックボックスを使用するにはWebhookの登録が必要です。

下にスクロールして、残りのフィールドを入力します：

1. Miva API Token: APIトークンを作成 の手順で作成したAPIトークンのAccess Tokenです。
2. Miva API Signature: 同じAPIトークンのSigning Keyです。
3. Image Type: Zonosチェックアウトに表示する商品画像のサイズを選択します（多くのストアでは Main が適しています）。
4. Additional Field Mappings: 必要に応じてMivaのカスタムフィールドをZonosの属性/メタデータ（色、素材、サイズなど）にマッピングします。Miva商品リストに商品固有のHS codeを設定している場合は、HS code のマッピングを推奨します。Catalogに入力した商品固有のHS codeまたはデフォルトHS codeを使用できるため、関税・税金見積もりの生成には必須ではありませんが、推奨されます。正しく分類された商品でLanded Cost計算の精度が大幅に向上します。Mivaでフィールドをマッピングするには、HS code用のカスタムフィールドを作成し、Utility Settings -> Zonos でマッピングしてください。

Update をクリックしてすべての設定を保存します。

アカウントとモジュールの設定が完了したら、以下を実行してテストする準備が整いました：

• 配送見積もりをテスト
• サイトでテスト注文を行う
• システム全体の注文フローをテスト
• ウェブサイトをテスト

これらのテストの実行方法をご覧ください。テスト中はモジュールの Environment フィールドを Test に設定する必要があります。

テストが完了したら、本番公開の準備は完了です！Environment を Live に設定し、Zonosの認証情報が正しいことを確認し、本番ストアでWebhookが登録されていることを確認してください。

1. dashboard.zonos.com -> Hello -> Hello Settings に移動します。
2. Currency behavior をオンに切り替えます。
3. 商品価格要素を対象とするCSSセレクタを入力します（例：.price）。

これを有効にすると、Zonos Helloは購入者のローカル通貨で価格を自動的に換算して表示します。

Mivaカタログに設定された配送寸法、原産国、HS codeは自動的にZonosにマッピングされ、入力されていればLanded Cost/配送見積もりに使用されます。追加のマッピング設定は必要ありません。

すべてのバリエーションが単一のSKUを共有する構成可能な商品を販売している場合、Mivaの標準Product Shipping Rulesは商品ごとに1組の寸法しか保持しないため、顧客が選択した内容に関係なくすべての構成が同じサイズとして扱われます。

MivaとZonosはバリアントレベルでの寸法設定に対応していますが、各バリアントを個別に設定する必要があります。個別のバリアントに対応しない何百、何千もの構成があるストアでは、これは現実的ではない場合があります。

この機能は、ストアに既に用意されているカスタムロジック（例：商品説明から寸法を解析するなど）を利用して、チェックアウト時にバスケットから構成ごとの寸法を直接読み取ることでこの問題を解決します。

要件

• ストアでは、商品がカートに追加された時点でバスケット商品にカスタム寸法カラムが既に入力されている必要があります（Miva側で処理される内容であり、Zonosモジュールの対象外です）。
• 使用している正確なカラム名を把握しておく必要があります。

設定

Zonosモジュール管理画面の対応する3つのフィールドにそれらのカラム名を入力します。空欄のままにすると標準のProduct Shipping Rulesにフォールバックします。この機能は完全にオプトイン方式であり、使用しないストアには影響しません。

Zonos Dashboardで配送ラベルが作成されるか追跡番号が入力されると、追跡番号と配送ステータスは対応するMiva管理画面の注文へ自動的に反映されます。これにはWebhookの登録が必要です（上記の Webhookを登録 の手順を参照してください）。

追跡番号はMivaで直接入力することもできます。任意のZonos注文で Enter Tracking Number 入力ダイアログを使用してください。追跡番号と配送ステータスは自動的にZonos Dashboardに同期されます。

デバッグログはMiva管理画面内のZonosモジュール設定からアクセスできます。モジュールが処理するすべての注文イベント（インポート、追跡同期、キャンセル、Zonosへの送信キャンセルリクエストなど）の全ライフサイクルを、成功・失敗を問わず記録します。

各エントリにはZonos注文ID、Miva注文ID、および該当する場合はMivaまたはZonos APIからのエラー応答などの顧客レベルの詳細が含まれます。そのため、問題を診断する上で最も詳細な情報源となります。

ログには直近500行のみが保持されます。古いエントリはアーカイブされないため、問題が発生したら速やかに確認してください。以前のイベントはすでに上書きされている可能性があります。

公開エラーログ（ログイン不要）

直接URLでアクセスできる、もう1つの公開ログも用意されています。Miva管理画面へのログインは不要です。このログにはエラーのみが記録され（成功は記録されません）、顧客のPIIや機微情報は含まれません。各エントリには、迅速に識別できるようモジュールバージョン（例：[v10.09]）が先頭に付与されます。

URL形式：

https://[store-domain]/mm5/json.mvc?Store_Code=[miva_store_code]&Function=Module&Module_Code=igs&Session_Type=runtime&Module_Function=JSON_WebHook&publiclog=1

例：

https://dts4509.mivamerchantdev.com/mm5/json.mvc?Store_Code=Test&Function=Module&Module_Code=igs&Session_Type=runtime&Module_Function=JSON_WebHook&publiclog=1

Store Code: miva_store_code は、すべてのdashboard注文のAPIレスポンスのmetadata配列内で返されます。

すべての支払い返金は、Zonosダッシュボードから直接処理する必要があります。MivaのRefund、Capture、Voidの各ボタンは、Zonosからインポートされた注文では仕様上使用できません。Zonosで処理された返金は、対応するMiva注文の支払い金額に自動的に反映されません。Miva注文は元の確定金額を保持したままとなり、Zonos側の返金処理とは同期されません。

注文のキャンセルについては、注文の現在のステータスによって動作が異なります：

• Open（未発送）：Mivaでキャンセルすると、Zonos側でも同時にキャンセルされ、支払いのオーソリが取り消されます。Zonosは注文が発送されるまで支払いを確定しないため、顧客に実際に請求されることはなく、別途返金を行う必要もありません。
• Shipped または Completed: Mivaでキャンセルするとその注文はキャンセル済みとしてマークされますが、すでに出荷済みで自動キャンセルの対象外となるため、Zonos側ではキャンセルが拒否されます。この場合、Miva注文には管理者のみが閲覧できるメモ（ストアスタッフのみに表示され、顧客には表示されません）が追加され、Zonosで対応する必要がある旨が記載されます。また、ストアアカウントのプライマリメールアドレスにも通知メールが送信され、Zonosダッシュボードで対応するよう販売者に案内されます。そこで必要に応じて手動で返金を処理できます。

症状： Zonos Checkoutで注文が完了しZonosダッシュボードには表示されるが、Miva管理画面には何も表示されない。

原因： Zonosはストアの /mm5/json.mvc エンドポイントに ORDER_CREATED Webhook（HTTP POST）を送信します。開発サイトでは、サーバーレベルのセキュリティによってこのリクエストがMivaに到達する前にブロックされることがよくあります。よくある原因：

• HTTP Basic Auth -- 開発サイトにパスワード入力プロンプトがある場合（Plesk、cPanel、.htaccessなど）、Webhookは401 Unauthorizedで拒否されます。.htaccessやPlesk設定でZonosのIPをホワイトリスト登録し、認証プロンプトを回避できるようにしてください。
• Cloudflare WAF / IP Access Rules -- サイトがCloudflare経由でプロキシされている場合、そのセキュリティルールによってPOSTがサーバーに到達する前にブロックされる可能性があります。URLパスに /mm5/json.mvc を含むPOSTリクエストを許可するWAFルールを追加するか、CloudflareのIP Access RulesでZonosのIPを直接ホワイトリスト登録してください。
• Server-level IP allowlist -- 開発サイトが特定のIPのみにトラフィックを制限している場合（オフィスやプラットフォームのIPに限定されたステージング環境でよく見られます）、Zonos Webhookのリクエストは応答なしで暗黙的に破棄されます。Zonos Webhook配信用のすべてのIPをサーバーの許可リストに追加してください（Plesk IP Access Restriction Manager、cPanel IP Blocker、またはファイアウォール/ホスティングパネルのセキュリティルール）。

Zonos Webhook配信IP

195.85.106.100/32
67.207.37.24/29
18.118.243.230/32
18.191.115.116/32
18.216.243.49/32
18.218.198.53/32
18.221.118.18/32
18.223.39.35/32
3.128.123.176/32
3.132.179.92/32
3.138.165.252/32
3.19.11.176/32
3.22.153.63/32
52.15.215.38/32

これは通常、開発/ステージングサイトにのみ影響します。本番のMivaサイトは通常公開されているため、IPのホワイトリスト登録は不要です。設定方法が不明な場合は、ホスティングプロバイダーまたはMivaサポートにお問い合わせください。

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

• Weight: 重量は配送コストに影響し、関税や税金に影響を与える可能性があります。Miva商品リストの重量は、存在する場合Zonosが自動的に使用します。
• Dimensions: 寸法は配送コストに影響し、関税や税金に影響を与える可能性があります。ZonosはMivaの各商品に設定された商品寸法（長さ、幅、高さ）を利用できますが、適切な統合のためにZonosアプリでマッピングする必要があります。
• HS codes: HS codeは関税率に影響し、場合によっては税金にも影響します。ZonosはMiva商品リストに設定されたHS codeを使用できますが、ZonosアプリでHS codeフィールドをマッピングする必要があります。
• Country of origin: 商品の原産国は関税率に影響し、税金にも影響する場合があります。Mivaは商品の原産国をZonosに送信できないため、Zonos Catalogを使用して追加する必要があります。

MivaからZonosに渡される商品詳細 

Note: または、上記の情報をCatalogに入力して、Mivaから保存・渡される情報を上書きすることもできます。

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