目录 API

目录 API 是构建 Verified Account 目录的三种方式之一，适用于拥有开发资源、且已有系统保存其商品数据的发货方——例如 ERP、WMS、PIM 或发货平台。该系统始终作为唯一数据来源，直接将商品写入 Zonos，而不是通过渠道集成同步或上传 CSV 文件。如果您通过受支持的渠道销售，或者不想编写代码，这两种方式能以更少的工作量构建同样的目录。

通过 API 创建的商品与其他任何来源的商品享有完全相同的处理方式——商品一旦进入您的目录，Zonos 并不关心它是如何进入的。如果您没有提供 HS 编码，每件商品都会进行海关归类，接受美国合作政府机构（PGA）要求审查，并用于计算其所在货件的关税和税费。

其中有一个环节不在 API 范围内。当 PGA 审查将某件商品标记为 Needs attention 时，该标记背后的合规问卷必须在 Dashboard 中回答并确认——没有相应的 API。Zonos 会尽可能预填答案，因此大部分工作只是审核和确认。构建此集成的人通常并不是处理这些标记的人，因此请安排您组织中的相关人员在目录导入完成后，在 Dashboard 中逐一处理这些标记。被标记的商品不会被阻止发货，但在发货前清除这些标记，才能避免货件在美国边境被扣留。

工作原理 

1. 为您发运的每件商品创建一个目录商品。

2. 确保每个商品都带有您的邮政承运商会传递的标识符。

3. 当您的货件数据到达 Zonos 时，每个行项目都会与您的目录商品进行匹配，并将该商品的产品数据应用于计算。

创建目录商品 

catalogItemCreate 接受一个列表，因此您可以在单个请求中发送多件商品。

重复发送同一商品

如果您发送的商品的 SKU 或 product ID 已存在，Zonos 会更新该商品，而不会新增一个。因此重试和重复运行都是安全的。

反过来，共用同一 SKU 或 product ID 的两件不同商品将被合并为一件。批量导入前，请检查您的数据中是否存在重复项。

字段

让您的商品可被匹配 

Zonos 使用您的标识符将每个货件行项目关联到目录商品，顺序依次为：product ID、SKU、name。无论您使用哪种标识符，都请确保其在目录与您发送给承运商的数据之间保持准确一致。

邮政货件还存在另一项限制。Zonos 从邮政承运商处接收的字段有限，在许多线路上，海关描述是唯一带有商品特定信息的字段。如果整个目录中的描述都相同，则其本身无法识别任何商品。

请在发送给承运商的海关描述末尾附加您的 product 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 或 product ID。请先使用 catalogItem 查询获取该 ID。

相关内容 

• 渠道集成 — 从受支持的销售渠道自动同步您的目录。
• CSV 导入 — 使用电子表格上传目录商品，无需编写代码。
• PGA 审查 — 审查您的目录商品是否符合美国政府机构 (PGA) 要求。
• Catalog 的工作原理 — 了解 Zonos 如何处理您的产品数据。