集成检查清单
请遵循此全面的检查清单，以设置您的Zonos仪表板帐户并将Zonos Checkout集成到您的自定义网站或平台中。
创建Zonos帐户
要开始，联系销售团队以创建帐户并签署协议。签署协议后，您将收到两个微型存款，需要进行验证。
请将这些微型存款金额通过电子邮件发送至accounting@zonos.com，并附上您的仪表板商店ID（抄送您的销售代表）。
验证后，您的银行详细信息将在仪表板 -> 设置 -> 账单中显示。
配置仪表板和Checkout设置
创建Zonos帐户后，您需要在仪表板中配置设置，以确保Checkout与您的商店正常工作。本节涵盖所有基本的仪表板配置。
设置付款
连接一个银行帐户，以便及时从Checkout接收付款。付款将在捕获付款后延迟2天内每日处理。为此，请按照以下步骤操作：
- 导航到仪表板 -> 设置 -> Checkout设置。
- 点击添加银行帐户
- 您将被带到Stripe门户以完成设置并提供以下信息：
- 银行帐户信息。
- 公司EIN。
- 25%公司所有者的社会安全号码。有关此要求的更多详细信息，请参见Stripe文档。
注意： 如果您需要更新付款计划，请联系support@zonos.com
设置允许的域名
Zonos JS脚本需要一个允许的域名列表以确保安全。这可以防止未经授权的网站加载脚本，并确保它仅在您批准的域名上运行。如果没有此配置，脚本将返回权限错误。
要设置此项：
- 导航到仪表板 -> 设置 -> Checkout设置
- 在URLs下，添加您的完整域名和任何子域名，其中Checkout将被使用。例如，如果您的域名是
example.com，您应该添加example.com和test.example.com。
自定义品牌设置
在仪表板中配置您的品牌设置，以匹配您商店的外观和感觉。
为此，请按照以下步骤操作：
- 导航到仪表板 -> 设置 -> Checkout设置 -> 品牌
- 配置以下设置：
- 徽标。
- 品牌和强调色。
- 主题、样式和字体。
有关品牌设置的更多信息，请参见我们文档。
连接运输承运人
要在checkout中报价运输，您需要将运输承运人连接到您的Zonos帐户。这将允许您在checkout中启用特定的运输服务级别。
要连接运输承运人，请按照以下步骤操作：
- 导航到仪表板 -> 设置 -> 运输 -> 费率
- 点击添加承运人
- 按照承运人设置说明进行操作。
有关连接承运人帐户的更多详细信息，请参见我们文档。
设置运输区域
运输区域允许您配置不同地区可用的运输承运人和服务级别。
要设置运输区域，请按照以下步骤操作：
- 导航到仪表板 -> 设置 -> 运输 -> 位置
- 点击新区域
- 输入区域名称并选择您要运输的国家。
- 选择您要提供的承运人和服务级别。
有关运输区域的更多详细信息，请参见我们文档。
设置备用原产国和HS代码
原产国和HS代码用于计算准确的关税和税费。
如果您未提供特定的原产国或HS代码，我们将使用在仪表板中设置的备用值。
要设置您的备用原产国和HS代码：
安装Zonos JS代码片段
Zonos JS代码片段是一个客户端JavaScript集成，使您的网站能够实现全球checkout功能。它充当您的电子商务平台与Zonos服务之间的桥梁，处理：
- Checkout体验：呈现checkout用户界面并处理付款。
- 位置服务：检测访客位置并管理货币转换。
- 购物车集成：与您现有的购物车和订单系统连接。
- 安全性：验证域名并验证API请求。
该代码片段是异步加载的，以防止对您网站性能的任何影响。它使用您商店的API凭据进行初始化，并安全地处理所有客户端交互。该实现旨在不干扰现有checkout流程，所需更改最小。
以下是一个完整的示例，包括脚本加载、初始化和事件处理，以供在集成Checkout时参考。
完整Zonos JS集成示例
<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 密钥，请导航到 Dashboard -> Settings -> Integrations。确保您不要使用Secret API key，因为它不适合在前端代码中使用。这在完整示例的第 29 和 30 行中有所显示。
Zonos 商店 ID 和 API 密钥
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
Hello 在使用Checkout时是必需的。
Hello 负责检测访问者的位置、语言和货币，并向他们显示适当的信息。您可以在仪表板或Hello JS脚本中配置所Zonos 设置。如果您已经在仪表板中配置了Hello，脚本将加载这些设置并使用它们。如果您在Zonos.init函数的helloSettings属性中指定了任何值，脚本将使用这些值，如下所示。
在JS脚本中配置Hello的货币转换
Hello 使用CSS选择器来识别您网站上显示货币信息的元素。将这些选择器传递给Zonos.init函数的helloSettings.currencyElementSelector属性，以便Hello能够检测并显示国际购物者的正确货币。
您可以在此处使用任有效的CSS选择器，例如#price, .price来选择多个不同的元素。这在完整示例的第23和24行中显示。
Hello 设置
Zonos.init({
// ... other fields
helloSettings: {
currencyElementSelector: '.price', // Replace with your actual selector
},
// ... other fields
});
自动在页面加载时打开 Hello
默认情况下，Hello 仅在访客点击旗帜按钮时打开。如果您希望在页面加载时自动打开 Hello，可以在 Zonos 脚本加载后调用 Zonos.openHelloDialog() 函数。这在完整示例的第 25 和 26 行中显示。
Zonos JS 代码片段
Zonos.init({
// ... other fields
helloSettings: {
// ... other hello settings
onInitSuccess: () => {
Zonos.openHelloDialog();
},
},
});
设置Checkout
Checkout 负责让客户输入他们的运输和账单信息，计算landed cost，collect付款，并完成订单。
Checkout 将与Hello共享上下文数据，例如访客的位置、语言和货币。这确保了客户在整个购物过程中体验的一致性。
您可以在Dashboard和Checkout JS脚本中配置所有Zonos设置。如果您已经在Dashboard中配置了Checkout，脚本将加载这些设置并使用它们。如果您在Zonos.init函数的checkoutSettings属性中指定了任何值，脚本将使用这些值。
在JS脚本中配置“下订单”按钮
Zonos JS脚本将自动识别国际购物者并将他们引导到Checkout流程。然而，您需要在您的平台上配置“下订单”按钮，以便在点击时打开Checkout。这可以通过将CSS选择器传递给Zonos.init函数的checkoutSettings.placeOrderButtonSelector属性来完成。
如果您有多个按钮可以用于下订单，请确保为每个按钮传递一个选择器。例如，#placeOrder, .place-order。
这在完整示例的第21行中显示。
下订单按钮选择器
Zonos.init({
// ... other fields
checkoutSettings: {
// ... other fields
placeOrderButtonSelector: '#placeOrder', // Replace with your actual selector(s)
},
});
安全地在服务器端创建购物车详情
为了向客户显示购物车详情，您需要创建一个服务器端函数，该函数将调用Zonos API 来创建购物车，然后将该购物车 ID 传回前端。这将确保购物车详情不会以可被操控的方式暴露给客户。
您的后端 API 调用将使用一个秘密的 GraphQL 凭证令牌，该令牌与您用于验证Zonos JS 脚本的公共令牌不同。该令牌可以在 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 集成中调用该端点，详细信息请参见下一步。
通过前端将购物车 ID 传递给 Checkout
一旦您在服务器端创建了购物车，您需要将购物车 ID 传递给 Zonos JS 脚本。这可以通过使用 createCartId 回调来完成，该回调是 Zonos.init 函数的一部分。Checkout 将在打开时安全地从 Zonos 检索购物车详细信息，从而防止对购物车的任何篡改。请参见下面的代码示例。
createCartId 的值不能是静态值，它必须是一个函数。
将购物车 ID 传递给 Checkout
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
},
},
});
将订单跟踪和状态同步到仪表板
测试您的集成
在您的Checkout集成上线之前，彻底测试集成的所有方面以确保顺畅的客户体验是很重要的。这包括测试checkout流程、支付处理、订单创建和Webhook功能。
遵循我们的测试指南以验证您的集成是否正常工作，并在上线之前识别和修复任何问题。
常见问题
以下是一些关于集成过程的常见问题。
Zonos如何处理订单确认？
Zonos提供了一个内置的感谢页面，您可以用于订单确认。即使订单未成功导入到您的系统中，该页面也会始终显示，确保客户始终收到购买确认。
我可以在订单创建时收到通知吗？
可以。如果您希望在订单创建时收到通知，请在仪表板Checkout设置的电子邮件部分中，输入应在订单创建、发货或取消时收到通知的团队成员的电子邮件地址。
自定义集成
在您的自定义网站中构建端到端Checkout集成。