步驟 1 — 建立您的認證帳戶
使用 Česká pošta 註冊連結 向 Zonos 認證帳戶註冊。 填完您的商業地址及帳單設定。
步驟 2 — 新增付款方式
向您的 Zonos 帳戶新增付款方式，以支付美國目的地貨件的關稅匯款。
步驟 3 — 取得您的 API 金鑰
登入您的 Zonos Dashboard，然後瀏覽至 帳戶 → 整合。該表格顯示兩個金鑰：
| Dashboard 中的名稱↕ | 用途↕ | 用於 API 嗎？↕ |
|---|---|---|
| 帳戶金鑰 | 與郵政營運商連結的識別碼 | ❌ 否 |
| API 金鑰 | 用於呼叫 Zonos API 的驗證金鑰 | ✅ 是 — 使用此金鑰 |
複製 API 金鑰 列中的權杖。它以 credential_live_ 開頭。您將需要此金鑰以進行兩種整合方法。
請保護您的 API 金鑰安全。請勿將其提交到原始碼控制或公開分享。如果您認為它已被洩露，請從相同的 帳戶 → 整合 頁面重新產生。
步驟 4（選用）— 使用商品報價工具估算關稅成本
您的 Zonos Dashboard 中的 商品報價工具 讓您在發貨前查詢產品的估計關稅成本 — 非常適合檢查費率並提前規劃，而無需產生宣告 ID。
整合方法
選擇適合您的技術設定的方法。兩種方法都會產生宣告 ID，然後您將其上傳到 Česká pošta 的運輸系統。
適用於直接從其自己系統呼叫 Zonos 的技術客戶和開發人員。
端點
- URL:
https://api.zonos.com/graphql - Method: POST
- Content-Type:
application/json
驗證
在 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 金鑰（而不是帳戶金鑰），且標頭名稱完全是 credentialToken。 |
| HTTP 401 Unauthorized | API 金鑰在請求標頭中遺失。確認 credentialToken 已包含。 |
errors array in response | mutation 傳回了 GraphQL 錯誤。檢查 errors 陣列中的 message 欄位以取得詳情。 |
| Unexpected response shape | 回應未包含 data.declarationCreate.id。記錄完整的回應正文並驗證 mutation 文字完全符合範例。 |
帳戶設定
建立您的認證帳戶、新增付款方式，並連接您的整合系統。