直接从您自己的系统,以编程方式构建您的 Verified Account 目录。
目录 API 是构建 Verified Account 目录的三种方式之一,适用于拥有开发资源、且已有系统保存其商品数据的发货方——例如 ERP、WMS、PIM 或发货平台。该系统始终作为唯一数据来源,直接将商品写入 Zonos,而不是通过渠道集成同步或上传 CSV 文件。如果您通过受支持的渠道销售,或者不想编写代码,这两种方式能以更少的工作量构建同样的目录。
通过 API 创建的商品与其他任何来源的商品享有完全相同的处理方式——商品一旦进入您的目录,Zonos 并不关心它是如何进入的。每件商品都会在您未提供 HS 编码时进行海关归类,接受美国合作政府机构(PGA)要求审查,并用于计算其所在货件的关税和税费。
其中有一个环节不在 API 范围内。当 PGA 审查将某件商品标记为 Needs attention 时,该标记背后的合规问卷必须在 Dashboard 中回答并确认——没有相应的 API。Zonos 会尽可能预填答案,因此大部分工作只是审核和确认。构建此集成的人通常并不是处理这些标记的人,因此请安排您组织中的相关人员在目录导入完成后,在 Dashboard 中逐一处理这些标记。被标记的商品不会被阻止发货,但在发货前清除这些标记,才能避免货件在美国边境被扣留。
为您发运的每件商品创建一个目录商品。
确保每个商品都带有您的邮政承运商会传递的标识符。
当您的货件数据到达 Zonos 时,每个行项目都会与您的目录商品进行匹配,并将该商品的产品数据应用于计算。
catalogItemCreate 接受一个列表,因此您可以在单个请求中发送多件商品。
catalogItemCreate
mutation CatalogItemCreate($input: [CatalogItemInput!]!) {
catalogItemCreate(input: $input) {
id
itemKey
name
productId
sku
hsCode
customsDescription
countryOfOrigin
}
如果您发送的商品的 SKU 或 product ID 已存在,Zonos 会更新该商品,而不会新增一个。因此重试和重复运行都是安全的。
反过来,共用同一 SKU 或 product ID 的两件不同商品将被合并为一件。批量导入前,请检查您的数据中是否存在重复项。
manufacturerProductId
gtin
measurements
amount
currencyCode
itemType
PHYSICAL_GOOD
DIGITAL_GOOD
SERVICE
SUBSCRIPTION
BUNDLE
PARTIAL_ITEM
provinceOfOrigin
productComposition
{material, percentage}
catalogItemUrl
imageUrl
如果您使用 Verified Account 向欧盟发货,自 2026 年 11 月 1 日起,欧盟要求价值不超过 150 欧元的企业对消费者(B2C)货件提供产品标识符(PID)。请将这些标识符保存在您的目录商品上。对于大多数 Verified Account,由您的邮政机构将货件数据发送给 Zonos,Zonos 会将货件上的每件商品与您的目录进行匹配,并应用您保存的标识符,因此发货时无需额外发送任何内容。
新商品请通过 catalogItemCreate 发送这些标识符。对于目录中已有的商品,请通过 catalogItemUpdate 发送,它接受相同的字段。请确保每件商品的 sku 与您在其他所有地方使用的 SKU 一致,以便 Zonos 将两者关联起来。
catalogItemUpdate
gtin 请仅发送数字,不含短横线或空格。UPC、EAN、JAN 以及 13 位 ISBN 值都填入这一个字段。如果您持有的是 10 位 ISBN,请改为发送其 13 位版本。
如果商品没有条形码,请直接省略 gtin,不要发送空字符串、重复使用您的 SKU,或填入 N/A 之类的占位文本。
N/A
如果您自行调用 Landed Cost API,也可以在 landed cost 请求中包含这些标识符。大多数 Verified Account 不需要这样做,因为向 Zonos 发送货件数据的是邮政机构。
有关该法规的要求,请参阅欧盟产品标识符指南。
Zonos 使用您的标识符将每个货件行项目关联到目录商品,顺序依次为:product ID、SKU、name。无论您使用哪种标识符,都请确保其在目录与您发送给承运商的数据之间保持准确一致。
邮政货件还存在另一项限制。Zonos 从邮政承运商处接收的字段有限,在许多线路上,海关描述是唯一带有商品特定信息的字段。如果整个目录中的描述都相同,则其本身无法识别任何商品。
在发送给承运商的货件数据中如何填写标识符,取决于您的邮政机构,因为每家邮政机构将货件与您的目录进行匹配的方式各不相同。请前往所有邮政机构并选择您的邮政机构。其页面会说明该邮政机构的匹配方式以及需要发送的具体内容。
将商品的 customsDescription 设置为与您发送给承运商的相同字符串并非必需,但当某个行项目未能匹配、需要排查原因时,这样可以让双方数据直接对比。
匹配失败的常见原因包括:
此行为仍在最终确定中,在正式上线前可能会有所调整。
catalogItemUpdate 使用与创建相同的输入类型。只需发送您想要更改的字段。
mutation CatalogItemUpdate($input: [CatalogItemInput!]!) {
catalogItemUpdate(input: $input) {
注意: 未提供的字段将保持不变,因此部分更新是安全的。发送 null 不会清除值,而是会被忽略。您可以用其他值覆盖现有值,但无法通过 API 将其清空。如需清除某个字段,请联系您的 Zonos 代表。
null
catalogItem 查询接受 id、productId 或 sku。可使用它确认 Zonos 为某件商品存储的数据。
catalogItem
query CatalogItem($sku: String!) {
catalogItem(sku: $sku) {
catalogItemDelete 接受 Zonos 目录商品 ID,而不是您的 SKU 或 product ID。请先使用 catalogItem 查询获取该 ID。
catalogItemDelete
mutation CatalogItemDelete($input: [ID!]!) {
catalogItemDelete(input: $input)
CatalogItemInput
catalogItemCreate catalogItemDelete catalogItemUpdate
目录 API
目录 API
直接从您自己的系统,以编程方式构建您的 Verified Account 目录。
目录 API 是构建 Verified Account 目录的三种方式之一,适用于拥有开发资源、且已有系统保存其商品数据的发货方——例如 ERP、WMS、PIM 或发货平台。该系统始终作为唯一数据来源,直接将商品写入 Zonos,而不是通过渠道集成同步或上传 CSV 文件。如果您通过受支持的渠道销售,或者不想编写代码,这两种方式能以更少的工作量构建同样的目录。
通过 API 创建的商品与其他任何来源的商品享有完全相同的处理方式——商品一旦进入您的目录,Zonos 并不关心它是如何进入的。每件商品都会在您未提供 HS 编码时进行海关归类,接受美国合作政府机构(PGA)要求审查,并用于计算其所在货件的关税和税费。
其中有一个环节不在 API 范围内。当 PGA 审查将某件商品标记为 Needs attention 时,该标记背后的合规问卷必须在 Dashboard 中回答并确认——没有相应的 API。Zonos 会尽可能预填答案,因此大部分工作只是审核和确认。构建此集成的人通常并不是处理这些标记的人,因此请安排您组织中的相关人员在目录导入完成后,在 Dashboard 中逐一处理这些标记。被标记的商品不会被阻止发货,但在发货前清除这些标记,才能避免货件在美国边境被扣留。
工作原理
为您发运的每件商品创建一个目录商品。
确保每个商品都带有您的邮政承运商会传递的标识符。
当您的货件数据到达 Zonos 时,每个行项目都会与您的目录商品进行匹配,并将该商品的产品数据应用于计算。
创建目录商品
catalogItemCreate接受一个列表,因此您可以在单个请求中发送多件商品。mutation CatalogItemCreate($input: [CatalogItemInput!]!) {catalogItemCreate(input: $input) {iditemKeynameproductIdskuhsCodecustomsDescriptioncountryOfOrigin}}重复发送同一商品
如果您发送的商品的 SKU 或 product ID 已存在,Zonos 会更新该商品,而不会新增一个。因此重试和重复运行都是安全的。
反过来,共用同一 SKU 或 product ID 的两件不同商品将被合并为一件。批量导入前,请检查您的数据中是否存在重复项。
字段
skuproductIdmanufacturerProductIdgtinnamecustomsDescriptioncountryOfOriginmeasurementshsCodeamountcurrencyCodeamount时为必填。itemTypePHYSICAL_GOOD、DIGITAL_GOOD、SERVICE、SUBSCRIPTION、BUNDLE或PARTIAL_ITEM。可避免非实物商品被申报为货物。provinceOfOriginproductComposition{material, percentage}列表。缺少此字段时,纺织品无法归类到 6 位以上。catalogItemUrlimageUrl添加欧盟产品标识符(PID)
如果您使用 Verified Account 向欧盟发货,自 2026 年 11 月 1 日起,欧盟要求价值不超过 150 欧元的企业对消费者(B2C)货件提供产品标识符(PID)。请将这些标识符保存在您的目录商品上。对于大多数 Verified Account,由您的邮政机构将货件数据发送给 Zonos,Zonos 会将货件上的每件商品与您的目录进行匹配,并应用您保存的标识符,因此发货时无需额外发送任何内容。
skumanufacturerProductIdgtin新商品请通过
catalogItemCreate发送这些标识符。对于目录中已有的商品,请通过catalogItemUpdate发送,它接受相同的字段。请确保每件商品的sku与您在其他所有地方使用的 SKU 一致,以便 Zonos 将两者关联起来。mutation CatalogItemCreate($input: [CatalogItemInput!]!) {catalogItemCreate(input: $input) {idskumanufacturerProductIdgtin}}gtin请仅发送数字,不含短横线或空格。UPC、EAN、JAN 以及 13 位 ISBN 值都填入这一个字段。如果您持有的是 10 位 ISBN,请改为发送其 13 位版本。如果商品没有条形码,请直接省略
gtin,不要发送空字符串、重复使用您的 SKU,或填入N/A之类的占位文本。如果您自行调用 Landed Cost API,也可以在 landed cost 请求中包含这些标识符。大多数 Verified Account 不需要这样做,因为向 Zonos 发送货件数据的是邮政机构。
有关该法规的要求,请参阅欧盟产品标识符指南。
让您的商品可被匹配
Zonos 使用您的标识符将每个货件行项目关联到目录商品,顺序依次为:product ID、SKU、name。无论您使用哪种标识符,都请确保其在目录与您发送给承运商的数据之间保持准确一致。
邮政货件还存在另一项限制。Zonos 从邮政承运商处接收的字段有限,在许多线路上,海关描述是唯一带有商品特定信息的字段。如果整个目录中的描述都相同,则其本身无法识别任何商品。
在发送给承运商的货件数据中如何填写标识符,取决于您的邮政机构,因为每家邮政机构将货件与您的目录进行匹配的方式各不相同。请前往所有邮政机构并选择您的邮政机构。其页面会说明该邮政机构的匹配方式以及需要发送的具体内容。
将商品的
customsDescription设置为与您发送给承运商的相同字符串并非必需,但当某个行项目未能匹配、需要排查原因时,这样可以让双方数据直接对比。匹配失败的常见原因包括:
更新目录商品
catalogItemUpdate使用与创建相同的输入类型。只需发送您想要更改的字段。mutation CatalogItemUpdate($input: [CatalogItemInput!]!) {catalogItemUpdate(input: $input) {iditemKeyhsCodecustomsDescription}}读取您的商品
catalogItem查询接受id、productId或sku。可使用它确认 Zonos 为某件商品存储的数据。query CatalogItem($sku: String!) {catalogItem(sku: $sku) {iditemKeynamecustomsDescriptionhsCodeproductIdskucountryOfOrigin}}删除目录商品
catalogItemDelete接受 Zonos 目录商品 ID,而不是您的 SKU 或 product ID。请先使用catalogItem查询获取该 ID。mutation CatalogItemDelete($input: [ID!]!) {catalogItemDelete(input: $input)}相关内容
CatalogItemInput
catalogItemCreate catalogItemDelete catalogItemUpdate
这个页面有帮助吗?