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. Store ID： 從 Dashboard -> Settings -> Account -> Integrations 複製您的Zonos 帳戶編號。
2. Zonos API Key： 您的私密 API 金鑰（請勿分享）。
3. Zonos Public Key： 您的公開金鑰。
4. 商店貨幣： 您商店的基礎貨幣（例如：USD）。
5. 環境： 正式環境請選擇Live，測試請選擇Test。
6. Checkout 按鈕選擇器： 您 Checkout 按鈕的 CSS 選擇器（例如：a[href*="checkout.html"]）。
7. 隱藏選擇器： 用於隱藏本地付款選項及其他可能與國際客戶無關的詳細資訊。
8. 匯入訂單： 勾選以自動將已完成的 Zonos 訂單匯入 Miva 管理後台。此功能需要在下一步註冊 Webhook。

點擊右上角的更新以儲存並繼續。

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

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

必須先註冊 Webhook，才能使用訂單匯入、取消同步及運送更新功能。匯入訂單核取方塊需要先註冊 Webhook。

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

1. Miva API 權杖： 您在建立 API 權杖步驟中所建立的 API 權杖的存取權杖（Access Token）。
2. Miva API 簽名： 同一個 API 權杖項目中的簽名金鑰（Signing Key）。
3. 圖像類型： 選擇 Zonos checkout 中顯示的商品圖片尺寸（大部分商店使用「Main」即可）。
4. 其他欄位對映： 可選擇將 Miva 自訂欄位對映至 Zonos 屬性／metadata（顏色、材質、尺寸等）。若您已在 Miva 商品清單中設定產品特定的 HS 代碼，我們建議對映HS 代碼。由於我們可以使用您已輸入 Catalog 的產品特定 HS 代碼，或使用您的預設 HS 代碼，因此這不是產生關稅和稅費報價的必要條件。不過，仍建議進行此設定；正確分類的產品將大幅提高 Landed Cost 計算的準確性。若要在 Miva 中對映欄位，請先為 HS 代碼建立自訂欄位，然後在工具設定 -> Zonos 下對映該欄位。

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

既然您已設定好帳戶和模組，您現在可以透過執行以下操作來測試：

• 測試運費報價
• 在您的網站上下達測試訂單
• 測試訂單在您系統中的流程
• 測試您的網站

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

完成測試後，您現在已準備好上線！請將環境設為Live，確認您的 Zonos 認證正確無誤，並確保您的線上商店已註冊 Webhook。

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

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

在 Miva 產品目錄中設定的運送尺寸、原產地國家及 HS 代碼，會自動對映至 Zonos，並在填入資料時用於 Landed Cost／運送報價計算。無需額外設定對映。

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

Miva 和 Zonos 支援在款式（variant）層級設定尺寸，但這需要為每個款式個別設定。對於擁有數百或數千種組合、且無法對映至個別款式的商店來說，這可能不切實際。

此功能透過在結帳時直接從購物車讀取每個組合的尺寸來解決此問題，並使用您商店現有的自訂邏輯來計算尺寸 -- 例如，從商品描述中解析尺寸資料。

需求

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

設定

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

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

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

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

每個項目都包含 Zonos 訂單編號、Miva 訂單編號，以及（相關時）客戶層級的詳細資訊，例如來自 Miva 或 Zonos API 的錯誤回應。這使其成為診斷問題時最完整的資訊來源。

日誌只會保留最新的 500 行。較舊的項目不會被存檔，因此請在問題發生後立即查看 -- 較早的事件可能已被覆寫。

公開錯誤日誌（無需登入） 

另有一個公開的日誌，可透過直接網址存取 -- 無需登入 Miva 管理後台。它只會記錄錯誤（不含成功項目），且不包含任何客戶 PII 或敏感資料。每個項目都會以模組版本作為前綴（例如：[v10.09]），方便快速識別。

網址格式：

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 回應 metadata 陣列中回傳。

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

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

• Open（尚未出貨）：在 Miva 中取消訂單，也會同時在 Zonos 中取消該訂單，並撤銷付款授權。由於 Zonos 在訂單出貨前不會請款，因此客戶實際上從未被扣款，也不需要另外退款。
• Shipped 或 Completed： 在 Miva 中取消訂單會將該 Miva 訂單標示為已取消，但 Zonos 會拒絕此取消請求，因為訂單已經完成履行，不再符合自動取消的條件。在此情況下，系統會在 Miva 訂單中新增一則僅限管理後台可見的備註 -- 僅商店員工可見，客戶永不可見 -- 說明該訂單需要在 Zonos 中處理。系統也會發送電郵通知至商店帳戶的主要電郵地址，提醒商家需在 Zonos Dashboard 中採取行動，並可在其中手動處理任何應退款項。

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

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

• HTTP 基本驗證（HTTP Basic Auth） -- 如果開發網站有密碼驗證提示（例如 Plesk、cPanel、.htaccess 等），Webhook 會因 401 Unauthorized 而被拒絕。請在您的 .htaccess 或 Plesk 設定中將 Zonos 的 IP 加入白名單，讓其繞過驗證提示。
• Cloudflare WAF／IP 存取規則 -- 如果網站透過 Cloudflare 代理，其安全性規則可能會在請求到達您的伺服器之前封鎖該 POST 請求。請新增一則 WAF 規則，允許網址路徑包含 /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。先前的模組版本則改用訂單成功網址。

開發網站上的伺服器層級安全性設定通常會封鎖 Zonos 傳送至 /mm5/json.mvc 的 ORDER_CREATED Webhook，原因包括 HTTP 基本驗證、Cloudflare WAF 或 IP 存取規則，或伺服器 IP 白名單。請將上方疑難排解：開發／預備網站上的訂單未顯示於 Miva中列出的 Zonos Webhook 傳送 IP 加入允許清單。正式環境網站通常是公開的，不受影響。

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

這取決於訂單的狀態：

• Open（尚未出貨）： 訂單也會在 Zonos 中被取消，並撤銷付款授權。客戶從未被扣款，因此無需退款。
• Shipped 或 Completed： Zonos 會拒絕此取消請求。系統會在 Miva 訂單中新增一則僅限管理員可見的備註，並發送電郵至商店帳戶的主要電郵地址，讓您可在 Zonos Dashboard 中處理任何退款。

請使用 Miva 管理後台 Zonos 模組設定中的偵錯日誌。它會記錄每次訂單匯入、追蹤同步和取消，包括成功與失敗的結果，並保留最新的 500 行。如只需查看錯誤而不想登入 Miva 管理後台，請使用上方偵錯日誌中所述的公開錯誤日誌網址。