Checkout for Miva

注册后的 24 小时内，专门的入职代表将与您联系，启动量身定制的集成流程。

重要提示： 以下列出的步骤供您参考，您的入职代表将指导您完成这些步骤。

1. 从 Miva App Store 下载该模块，或直接向 Zonos 索取 zonos.mvc 文件。
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 账户号码。
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 代码，我们建议映射 HS code。由于我们可以使用您在 Catalog 中输入的产品特定 HS 代码，或使用您的默认 HS 代码，因此这并非生成关税和税收报价所必需的。但是，仍建议进行此操作；通过正确分类的产品，登陆成本计算的准确性将大大提高。要在 Miva 中映射字段，请为 HS 代码创建一个自定义字段，然后在 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 代码会自动映射到 Zonos，并在填写后用于登陆成本/运费报价。无需额外配置映射。

如果您的商店销售所有变体共用同一 SKU 的可配置产品，Miva 标准的 Product Shipping Rules 会为每个产品存储一组尺寸，因此无论客户选择了哪种配置，都会被视为相同尺寸。

Miva 和 Zonos 支持在变体级别设置尺寸，但这需要单独设置每个变体。对于有成百上千种配置且无法映射到独立变体的商店来说，这可能并不现实。

此功能通过在结账时直接从购物篮中读取每种配置的尺寸来解决此问题，使用您商店已有的自定义逻辑来计算这些尺寸——例如从产品描述中解析出尺寸。

要求

• 您的商店必须已经在商品被添加到购物车时，在购物篮商品上填充自定义尺寸列（此部分在 Miva 端处理，不在 Zonos 模块的范围内）。
• 您需要知道您所使用的确切列名。

配置

在 Zonos 模块管理后台的三个对应字段中输入这些列名。留空则会回退到标准的 Product Shipping Rules -- 此功能完全是可选启用的，不会影响未使用该功能的商店。

当在 Zonos Dashboard 中创建运输标签或输入跟踪号时，跟踪号和物流状态会自动推送到 Miva 管理后台中对应的订单。此功能需要先注册 webhook（请参阅上文的 Register webhooks 步骤）。

跟踪号也可以直接在 Miva 中输入。在任意 Zonos 订单上使用 Enter Tracking Number 输入对话框——跟踪号和物流状态将自动同步回 Zonos Dashboard。

调试日志可在 Miva 管理后台的 Zonos 模块设置中访问。它记录了模块处理的每个订单事件的完整生命周期——导入、跟踪同步、取消操作以及发往 Zonos 的出站取消请求——并在其中直接包含成功和失败的信息。

每条记录都包含 Zonos 订单 ID、Miva 订单 ID，以及在相关情况下的客户级详细信息，例如来自 Miva 或 Zonos API 的错误响应。这使其成为诊断问题时最全面的信息来源。

该日志仅保留最近的 500 行。较早的记录不会被归档，因此请在问题发生后及时查看——较早的事件可能已被覆盖。

公共错误日志（无需登录）

还有第二个面向公众的日志，可通过直接 URL 访问——无需登录 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 响应元数据数组中返回。

所有付款退款都必须直接通过 Zonos Dashboard 处理。按照设计，Miva 中的 Refund、Capture 和 Void 按钮对通过 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 Basic Auth -- 如果开发环境站点设置了密码提示（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 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 也可以生成报价，但建议提供以下关键产品详细信息以提高准确性：

• 重量： 重量会影响您的运费，这可能会影响关税或税收。Miva 产品列表中的重量在存在时会由 Zonos 自动使用。
• 尺寸： 尺寸可能会影响您的运费，这可能会影响关税或税收。Zonos 可以使用在 Miva 中每个产品上设置的产品尺寸（长度、宽度和高度），但您必须在 Zonos 应用中进行映射以实现正确的集成。
• HS 代码： HS 代码会影响关税税率，有时也可能影响税收。Zonos 可以使用在 Miva 产品列表中设置的 HS 代码，但您必须在 Zonos 应用中映射 HS 代码字段。
• 原产国： 产品的原产国会影响关税税率，可能会影响税收。Miva 无法将您的产品原产国发送给 Zonos，因此必须使用 Zonos Catalog 添加它们。

Miva 传递给 Zonos 的产品详细信息 

注意： 或者，您可以在 Catalog 中输入上述任何信息，覆盖从 Miva 存储和传递的信息。

了解更多关于平台的产品信息。