Miva 的 Checkout

於註冊後 24 小時內，專用的入職代表將與您聯絡，開始客製化的整合流程。

重要事項： 以下列出的步驟供您參考，您將由入職代表逐步引導完成。

1. 從 Miva App Store 下載模組，或直接向 Zonos 索取 zonos.mvc 檔案。
2. 在您的 Miva 管理後台中，前往網域設定 -> 模組 -> 新增模組，上傳 zonos.mvc 檔案，然後點擊新增。

3. 前往設定 -> 模組，找到 Zonos，然後點擊安裝。確認其顯示為已安裝。

在 Miva 中，前往使用者 -> API 權杖，然後點擊新增 API 權杖。設定如下：

• 名稱： Zonos Checkout
• 允許的 IP 位址： 0.0.0.0/0, ::/0
• 簽章： 需要使用金鑰簽章 -- 點擊產生以建立簽章金鑰
• 時間戳記： 需要在 30 秒內提供時間戳記

在下一個畫面中，啟用客戶服務與銷售，以允許此權杖建立及修改訂單。點擊儲存。

前往 Miva -> 公用程式設定 -> Zonos，導覽至 Miva 中的 Checkout 模組，然後填寫下列欄位：

1. 商店識別碼： 從 Dashboard -> 設定 -> 帳戶 -> 整合，複製您的 Zonos 帳戶號碼。
2. Zonos API 金鑰： 您的私密 API 金鑰（切勿與他人分享）。
3. Zonos 公開金鑰： 您的公開金鑰。
4. 商店貨幣： 您商店的基礎貨幣（例如 USD）。
5. 環境： 生產環境請選擇即時，測試請選擇測試。
6. 結帳按鈕選擇器： 用於您結帳按鈕的 CSS 選擇器（範例：a[href*="checkout.html"]）。
7. 隱藏選擇器： 用於隱藏可能與國際客戶無關的國內付款選項及其他詳細資訊。
8. 匯入訂單： 勾選以自動將已完成的 Zonos 訂單匯入 Miva 管理後台。這需要在下一步驟中註冊 Webhook。

繼續之前，請點擊右上方的更新進行儲存。

在 10.x 模組中，訂單是透過 Webhook 匯入的。先前的模組版本則是使用訂單成功 URL/端點。

儲存設定後，點擊註冊 Webhook。這會將您的商店連接到 Zonos，以便自動匯入已完成的訂單、同步取消狀態，並將出貨更新推送回 Miva。

必須先註冊 Webhook，訂單匯入、取消同步和出貨更新才能運作。「匯入訂單」核取方塊需要先註冊 Webhook。

向下捲動以完成剩餘欄位：

1. Miva API 權杖： 您在建立 API 權杖步驟中建立的 API 權杖的存取權杖（Access Token）。
2. Miva API 簽章： 同一個 API 權杖項目中的簽章金鑰。
3. 圖片類型： 選擇 Zonos Checkout 中顯示的產品圖片尺寸（大多數商店使用「主要」即可）。
4. 其他欄位對應： 可選擇將 Miva 自訂欄位對應到 Zonos 屬性/中繼資料（顏色、材質、尺寸等）。如果您已在 Miva 產品清單中設定特定產品的 HS 代碼，我們建議對應 HS 代碼。由於我們可以使用您在 Catalog 中輸入的特定產品 HS 代碼，或使用您的預設 HS 代碼，因此這並非產生關稅和稅務報價的必要條件。不過，我們建議進行此設定；正確分類的產品將大幅提高 landed cost 計算的準確性。若要在 Miva 中對應欄位，請為 HS 代碼建立自訂欄位，然後在公用程式設定 -> Zonos 下進行對應。

點擊更新以儲存所有設定。

現在您已設定好帳戶和模組，可以透過以下方式進行測試：

• 測試運送報價
• 在您的網站上下測試訂單
• 透過您的系統測試訂單流程
• 測試您的網站

了解如何執行這些測試。測試期間，您需要將模組的環境欄位設定為測試。

完成測試後，您就可以準備上線了！將環境設定為即時，確認您的 Zonos 憑證正確無誤，並確保您的即時商店已註冊 Webhook。

1. 前往 dashboard.zonos.com -> Hello -> Hello 設定。
2. 開啟貨幣行為切換開關。
3. 輸入指向您產品價格元素的 CSS 選擇器（例如 .price）。

啟用此功能後，Zonos Hello 將自動以購物者的當地貨幣轉換並顯示價格。

在 Miva 目錄中設定的運送尺寸、原產地和 HS 代碼會自動對應至 Zonos，並在有填寫的情況下用於 landed cost／運送報價。無需額外設定對應。

如果您的商店銷售所有變體共用單一 SKU 的可設定產品，Miva 標準的產品運送規則會為每個產品儲存一組尺寸，因此無論客戶選擇了哪種設定，都會被視為相同的尺寸。

Miva 和 Zonos 支援變體層級的尺寸設定，但這需要個別設定每個變體。對於擁有數百或數千種設定、且無法對應到個別變體的商店來說，這可能不切實際。

此功能透過在結帳時直接從購物籃讀取各設定的尺寸來解決此問題，並使用您商店現有的自訂邏輯來計算這些尺寸 -- 例如，從產品說明中解析出尺寸。

需求

• 您的商店必須已在項目加入購物車時，於購物籃項目上填入自訂尺寸欄位（此部分由 Miva 端處理，不在 Zonos 模組的範圍內）。
• 您需要知道您使用的確切欄位名稱。

設定

在 Zonos 模組管理介面的三個對應欄位中輸入這些欄位名稱。留空則會回退至標準的產品運送規則 -- 此功能完全為選用，不會影響未使用此功能的商店。

當在 Zonos Dashboard 中建立運送標籤或輸入追蹤號碼時，追蹤號碼和出貨狀態會自動推送至 Miva 管理後台中對應的訂單。這需要先註冊 Webhook（請參閱上方的註冊 Webhook步驟）。

您也可以直接在 Miva 中輸入追蹤資訊。在任何 Zonos 訂單上使用輸入追蹤號碼輸入對話方塊 -- 追蹤號碼和出貨狀態將自動同步回 Zonos Dashboard。

偵錯記錄可在 Miva 管理後台的 Zonos 模組設定中查看。它會記錄模組處理的每個訂單事件的完整生命週期 -- 匯入、追蹤同步、取消，以及向 Zonos 傳出的取消請求 -- 並就地包含成功與失敗的記錄。

每筆記錄都包含 Zonos 訂單 ID、Miva 訂單 ID，以及相關情況下的客戶層級詳細資訊，例如來自 Miva 或 Zonos API 的錯誤回應。這使其成為診斷問題最完整的資訊來源。

該記錄僅保留最近的 500 行。較舊的記錄不會被封存，因此請在問題發生後盡快查看 -- 較早的事件可能已被覆寫。

公開錯誤記錄（無需登入） 

還有第二種公開的記錄，可透過直接的 URL 取得 -- 無需登入 Miva 管理後台。它僅記錄錯誤（不記錄成功項目），且不包含任何客戶個人識別資訊或敏感資料。每筆記錄都會加上模組版本前綴（例如 [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

商店代碼： miva_store_code 會在所有 Dashboard 訂單的 API 回應的中繼資料陣列中回傳。

所有付款退款都必須直接透過 Zonos Dashboard 處理。依設計，Miva 中的退款、請款和作廢按鈕不適用於由 Zonos 匯入的訂單。任何在 Zonos 中處理的退款都不會自動更新對應 Miva 訂單上的付款金額 -- Miva 訂單會保留原始請款金額，且不會與 Zonos 中的退款活動保持同步。

至於訂單取消，其行為取決於訂單目前的狀態：

• 未結案（尚未出貨）：在 Miva 中取消訂單也會在 Zonos 中取消該訂單，並作廢付款授權。由於 Zonos 在訂單出貨前不會請款，因此客戶實際上從未被收費，也不需要另外辦理退款。
• 已出貨或已完成： 在 Miva 中取消會將 Miva 訂單標記為已取消，但 Zonos 會拒絕此取消請求，因為該訂單已完成履行，不再符合自動取消的資格。在此情況下，系統會在 Miva 訂單上新增一則僅限管理員檢視的備註 -- 僅商店員工可見，客戶永遠看不到 -- 說明該訂單需要在 Zonos 中處理。系統也會傳送電子郵件通知至商店帳戶的主要電子郵件地址，提醒商家需在 Zonos Dashboard 中採取行動，商家可在該處手動處理任何適用的退款。

症狀： 訂單在 Zonos Checkout 中完成，並顯示在 Zonos Dashboard 中，但 Miva 管理後台中卻沒有顯示任何內容。

原因： Zonos 會向您商店的 /mm5/json.mvc 端點傳送 ORDER_CREATED Webhook（HTTP POST）。在開發網站上，伺服器層級的安全性設定通常會在請求送達 Miva 之前將其攔截。常見原因包括：

• HTTP 基本驗證 -- 如果開發網站有密碼提示（Plesk、cPanel、.htaccess 等），Webhook 會被拒絕並回傳 401 Unauthorized。請在您的 .htaccess 或 Plesk 設定中將 Zonos 的 IP 加入白名單，使其略過驗證提示。
• Cloudflare WAF／IP 存取規則 -- 如果網站透過 Cloudflare 代理，其安全性規則可能會在 POST 請求送達您的伺服器之前將其攔截。請新增一條 WAF 規則，允許 URL 路徑包含 /mm5/json.mvc 的 POST 請求，或直接在 Cloudflare 的 IP 存取規則中將 Zonos 的 IP 加入白名單。
• 伺服器層級 IP 允許清單 -- 如果開發網站僅限制特定 IP 的流量（在鎖定為僅限辦公室或平台 IP 的測試環境中很常見），Zonos 的 Webhook 請求會被靜默捨棄，不會有任何回應。請將所有 Zonos Webhook 傳送 IP 加入您伺服器的允許清單（Plesk IP 存取限制管理員、cPanel IP 封鎖工具，或您的防火牆／主機控制台安全性規則）。

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 仍可產生報價。

• 重量、尺寸、原產地和 HS 代碼： 在 Miva 目錄的運送規則中設定的值會自動傳遞至 Zonos，無需進行對應。
• 自訂欄位中的 HS 代碼： 如果您改為將 HS 代碼儲存在 Miva 自訂欄位中，請在公用程式設定 -> Zonos 的其他欄位對應下對應該欄位。
• 缺少的值： Zonos 會改用 Catalog 中的產品詳細資訊或您的預設 HS 代碼。

注意： 您在 Catalog 中輸入的任何值都會覆蓋從 Miva 傳遞的值。

深入了解各個平台的產品資訊。

10.x 模組會透過 Webhook 將已完成的 Zonos 訂單匯入 Miva 管理後台。在 Zonos 設定中勾選匯入訂單，然後點擊註冊 Webhook。Webhook 也會同步取消狀態，並將出貨更新推送回 Miva。先前的模組版本則是使用訂單成功 URL。

通常是開發網站上的伺服器層級安全性設定攔截了 Zonos 傳送至 /mm5/json.mvc 的 ORDER_CREATED Webhook -- 例如 HTTP 基本驗證、Cloudflare WAF 或 IP 存取規則，或伺服器 IP 允許清單。請將上方疑難排解：開發／測試環境網站中的訂單未顯示在 Miva 中一節所列的 Zonos Webhook 傳送 IP 加入允許清單。正式環境網站通常是公開的，不會受到影響。

所有退款都請在 Zonos Dashboard 中處理。Miva 中的退款、請款和作廢按鈕不適用於由 Zonos 匯入的訂單，且在 Zonos 中處理的退款不會更新 Miva 訂單上的付款金額。

這取決於訂單的狀態：

• 未結案（尚未出貨）： 該訂單也會在 Zonos 中取消，並作廢付款授權。客戶從未被收費，因此不需要退款。
• 已出貨或已完成： Zonos 會拒絕此取消請求。系統會在 Miva 訂單上新增一則僅限管理員檢視的備註，並傳送電子郵件至商店帳戶的主要電子郵件地址，讓您可以在 Zonos Dashboard 中處理任何退款。

請使用 Miva 管理後台中 Zonos 模組設定裡的偵錯記錄。它會記錄每一次訂單匯入、追蹤同步和取消，包含成功與失敗的記錄，並保留最近的 500 行。若只需查看錯誤且不想登入 Miva 管理後台，請使用上方偵錯記錄一節所述的公開錯誤記錄 URL。