目錄 API

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

透過 API 建立的項目與來自其他來源的項目完全一視同仁——項目一旦進入您的目錄，Zonos 並不在意它是如何加入的。如果您沒有提供 HS 編碼，每個項目都會進行海關歸類，並接受美國合作政府機構（PGA）規定的審查，同時用於計算其所屬貨件的關稅及稅項。

當中有一部分無法透過 API 處理。當 PGA 審查 將某個項目標記為 需要注意 時，該標記背後的合規問卷必須在 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 完全相符。

描述欄位的長度有限。例如，加拿大郵政的提交資料大約只容許 49 個字元，因此如果您的識別碼較長，請縮短描述部分。識別碼比描述文字更重要。

將項目的 customsDescription 設為與您傳送給承運商相同的字串並非必要，但當某個行項目未能配對、需要找出原因時，這樣做能讓雙方資料直接比對。

配對常見的失敗情況包括：

• 描述中缺少識別碼。
• 識別碼與目錄中任何 productId 或 sku 都不對應。
• 識別碼因承運商的字元限制而被截斷。
• 不同貨件之間的格式有所變動。

此行為仍在最終確定中，正式推出前可能會有所變更。

更新目錄項目 

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

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

讀取您的項目 

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

刪除目錄項目 

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

相關內容 

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