Catalog API

Catalog API 是建立已驗證帳戶目錄的三種方式之一，適合擁有開發資源、且已有系統存放產品資料（例如 ERP、WMS、PIM 或出貨平台）的寄件人。該系統仍是唯一可信的資料來源，並直接將產品寫入 Zonos，而不是從頻道整合同步，或上傳 CSV 檔案。如果您透過支援的頻道銷售，或不想撰寫程式碼，這兩種方式能以更少的工作量建立相同的目錄。

透過 API 建立的商品與來自任何其他來源的商品享有完全相同的處理方式——商品一旦進入您的目錄，Zonos 並不在意它是如何加入的。每項商品都會在您未提供 HS 代碼時進行海關分類，並篩檢是否符合美國合作政府機構（PGA）的規定，並用於計算其所屬貨件的關稅與稅金。

其中有一部分無法透過 API 完成。當 PGA 篩檢將某項商品標記為 Needs attention 時，該標記背後的合規問卷必須在 Dashboard 中回答並確認——此功能沒有 API，而 Zonos 會預先填入能填的內容，因此大部分工作只需檢閱與確認。負責建置此整合的人通常不是處理這些標記的人，因此請規劃在目錄載入後，由貴組織中的相關人員在 Dashboard 中逐一處理。已標記的商品並不會被禁止出貨，但在出貨前處理完這些標記，才能避免貨件在美國邊境遭到扣留。

運作方式 

1. 為您出貨的每項產品建立一個目錄商品。

2. 確保每個商品都帶有您的郵政業者會一併傳遞的識別碼。

3. 當您的貨件資料送達 Zonos 時，每一行都會配對回您的目錄商品，並將該商品的產品資料套用於計算。

建立目錄商品 

catalogItemCreate 接受清單，因此您可以在單一請求中傳送多項產品。

重複傳送相同產品

如果您傳送的產品其 SKU 或產品 ID 已存在，Zonos 會更新該產品，而不會新增第二筆。重試與重複執行皆為安全操作。

反過來說，共用相同 SKU 或產品 ID 的兩項不同產品將會被合併為一項。在進行大量載入之前，請先檢查您的資料是否有重複項目。

欄位

讓您的商品可被配對 

Zonos 會使用您的識別碼，依照以下順序將每一行貨件資料連結回目錄商品：產品 ID，其次是 SKU，最後是名稱。無論您使用哪些識別碼，請確保其在目錄與您傳送給貨運業者的資料之間保持準確且一致。

郵政貨件還有另一項限制。Zonos 從郵政業者接收到的欄位有限，而在許多路線上，海關說明是唯一帶有產品專屬資訊的欄位。如果整個目錄的說明都完全相同，這些說明本身就無法識別任何產品。

請將您的產品 ID 或 SKU 附加在您傳送給貨運業者的海關說明後方。

Men's bifold wallet, cowhide leather - 123456

附加的識別碼必須與對應目錄商品上的 productId 或 sku 完全相符。

說明欄位的長度很短。例如，Canada Post 的提交資料大約只允許 49 個字元，因此如果您的識別碼較長，請縮短描述文字的部分。識別碼比描述文字更重要。

將商品的 customsDescription 設為與您傳送給貨運業者相同的字串並非必要，但當某一行無法配對、需要找出原因時，這樣做能讓兩邊資料直接比對。

配對常見的失敗原因包括：

• 說明中缺少識別碼。
• 識別碼與您目錄中的任何 productId 或 sku 都不相符。
• 識別碼因貨運業者的字元數限制而遭截斷。
• 不同貨件之間的格式有所變動。

此行為仍在最終確定中，上線前可能會有所變動。

更新目錄商品 

catalogItemUpdate 使用與建立時相同的輸入類型。只需傳送您想變更的欄位。

注意： 省略的欄位會保持不變，因此部分更新是安全的。傳送 null 並不會清除值，而是會被忽略。您可以用不同的值覆寫現有的值，但無法透過 API 將其清空。如果您需要清除某個欄位，請聯絡您的 Zonos 代表。

讀取您的商品 

catalogItem 查詢接受 id、productId 或 sku。您可以用它來確認 Zonos 為某項產品所保存的資料。

刪除目錄商品 

catalogItemDelete 接受的是 Zonos 目錄商品 ID，而不是您的 SKU 或產品 ID。請先使用 catalogItem 查詢取得 ID。

相關內容 

• 頻道整合 — 從支援的銷售頻道自動同步您的目錄。
• CSV 匯入 — 使用試算表上傳目錄商品，無需撰寫程式碼。
• PGA 檢查 — 篩選您的目錄商品是否符合美國政府機構（PGA）的要求。
• Catalog 運作方式 — 了解 Zonos 如何運用您的產品資料。