账户设置

创建您的验证账户，添加支付方式，并连接您的集成。

步骤 1 — 创建您的验证账户

使用 Česká pošta 注册链接注册 Zonos 验证账户。完成您的业务地址和账单设置。

向您的 Zonos 账户添加支付方式，为运往美国的货物资助关税汇款。

登录您的 Zonos Dashboard，然后导航至 Account → Integrations。该表显示两个密钥：

Dashboard 中的名称↕	用途↕	用于 API？↕
Account key	与邮政运营商链接的标识符	❌ 否
API key	调用 Zonos API 的身份验证密钥	✅ 是 — 使用此密钥

复制 API key 行中的令牌。它以 credential_live_ 开头。两种集成方式都需要此密钥。

保护您的 API 密钥。不要将其提交到源代码控制或公开共享。如果您认为它已泄露，从同一 Account → Integrations 页面重新生成它。

您的 Zonos Dashboard 中的 Item Quoter 工具让您在运送前查询产品的估算关税成本 — 这对于检查费率和提前规划，而无需生成声明 ID 很有用。

选择适合您技术设置的方法。两种方法都会生成声明 ID，然后您将其上传到 Česká pošta 的运输系统。

适用于直接从其自己的系统调用 Zonos 的技术客户和开发人员。

端点

身份验证

在 credentialToken 标头中传递您的 API 密钥： credentialToken: credential_live_xxxxxxxxxxxxxxxxxx

API 示例

登录您的 Česká pošta 账户以获取完整的 API 示例，包括完整的请求和响应。

生成声明 ID 后

将声明 ID 与您的货物详情一起提交给 Česká pošta。Česká pošta 将声明 ID 链接到货物并返回跟踪号。Zonos 不发出跟踪号。

错误处理

错误 / 症状↕	可能的原因和修复↕
Security requirement failed	您的 API 密钥无效或在错误的标头中传递。请确保您使用的是 API Key（而不是 Account Key），标头名称正确为 `credentialToken`。
HTTP 401 Unauthorized	API 密钥在请求标头中缺失。确认 `credentialToken` 已包含。
`errors` 数组在响应中	mutation 返回了 GraphQL 错误。检查 errors 数组中的 `message` 字段以获取详情。
意外的响应形状	响应不包含 `data.declarationCreate.id`。记录完整的响应体并验证 mutation 文本与示例完全一致。