Crea el catálogo de tu cuenta verificada de forma programática, directamente desde tu propio sistema.
La API de catálogo es una de las tres formas de crear el catálogo de tu cuenta verificada, y es la opción para los remitentes que cuentan con recursos de desarrollo y un sistema que ya contiene sus datos de producto: un ERP, WMS, PIM o plataforma de envíos. Ese sistema sigue siendo la fuente de verdad y escribe los productos directamente en Zonos, en lugar de sincronizarlos desde una integración de canal o de subir un archivo CSV. Si vendes a través de un canal compatible o prefieres no escribir código, esas dos opciones crean el mismo catálogo con menos trabajo.
Los artículos creados mediante la API reciben exactamente el mismo tratamiento que los artículos de cualquier otra fuente: una vez que un artículo está en tu catálogo, a Zonos no le importa cómo llegó ahí. Cada uno se clasifica para aduanas si no proporcionaste un código HS, se examina según los requisitos de las agencias gubernamentales asociadas de EE. UU. (PGA) y se usa para calcular los aranceles e impuestos de los envíos en los que aparece.
Hay una parte de ese proceso que queda fuera de la API. Cuando el examen de PGA marca un artículo como Necesita atención, el cuestionario de cumplimiento asociado a esa marca debe responderse y confirmarse en Dashboard: no existe una API para ello, y Zonos completa previamente lo que puede, de modo que la mayor parte del trabajo consiste en revisar y confirmar. La persona que crea esta integración no suele ser la misma que resuelve esas marcas, así que planifica que alguien de tu organización las revise en Dashboard después de que se cargue tu catálogo. Los artículos marcados no tienen bloqueado el envío, pero resolverlos antes de enviar es lo que evita que un envío quede retenido en la frontera de EE. UU.
Crea un artículo del catálogo para cada producto que envíes.
Asegúrate de que cada artículo tenga un identificador que tu transportista postal vaya a transmitir.
Cuando los datos de tu envío llegan a Zonos, cada línea se vincula con su artículo del catálogo y los datos de producto de ese artículo se aplican al cálculo.
Si envías un producto cuyo SKU o ID de producto ya existe, Zonos actualiza ese producto en lugar de agregar uno nuevo. Los reintentos y las ejecuciones repetidas son seguros.
La contrapartida es que dos productos distintos que compartan un SKU o ID de producto se fusionarán en uno solo. Revisa tus datos en busca de duplicados antes de una carga masiva.
Campos
Campo↕
Obligatorio↕
Descripción↕
sku
Sí*
Tu identificador único del producto. *Cada producto necesita un SKU, un ID de producto o ambos.
productId
Sí*
El identificador del producto en tu plataforma. *Cada producto necesita un SKU, un ID de producto o ambos.
name
Sí
El nombre del producto.
customsDescription
Recomendado
Qué es el producto, en términos sencillos, para la declaración de aduanas. Usa "Camiseta de algodón", no "Camiseta Summer Vibes".
countryOfOrigin
Recomendado
El código ISO de 2 letras del lugar donde se fabricó el producto. Es necesario para calcular los aranceles con precisión.
measurements
Recomendado
Peso y dimensiones, que se usan para la tarificación y la declaración aduanera.
hsCode
No
El código HS universal de 6 dígitos. Si lo omites, Zonos clasifica el producto a partir de su nombre y descripción.
amount
No
El precio del producto como número.
currencyCode
No
El código ISO de 3 letras de la moneda del precio. Es obligatorio cuando proporcionas amount.
itemType
No
PHYSICAL_GOOD, DIGITAL_GOOD, SERVICE, SUBSCRIPTION, BUNDLE o PARTIAL_ITEM. Evita que los artículos no físicos se declaren como mercancía.
provinceOfOrigin
No
El estado o la provincia de origen del producto. Algunos países de destino lo exigen.
productComposition
No
Una lista de {material, percentage}. Sin ella, los textiles no pueden clasificarse más allá de 6 dígitos.
catalogItemUrl
No
Un enlace a la página del producto en tu sitio. Mejora la precisión de la clasificación.
imageUrl
No
Una URL de acceso público para la imagen del producto. Mejora la precisión de la clasificación.
Zonos vincula cada línea de envío con un artículo del catálogo usando tus identificadores, en este orden: ID de producto, luego SKU y, por último, nombre. Mantén precisos y consistentes los identificadores que uses, tanto en tu catálogo como en los datos que envías a tu transportista.
Los envíos postales tienen una restricción adicional. Zonos recibe un conjunto limitado de campos de los transportistas postales y, en muchas rutas, la descripción aduanera es el único campo que llega con información específica del producto. Una descripción idéntica en todo tu catálogo no puede identificar nada por sí sola.
Añade tu ID de producto o SKU al final de la descripción aduanera que envías a tu transportista.
Men's bifold wallet, cowhide leather - 123456
El identificador añadido debe coincidir exactamente con el productId o el sku del artículo del catálogo correspondiente.
Los campos de descripción son cortos. Los envíos de Canada Post, por ejemplo, admiten aproximadamente 49 caracteres, así que acorta la parte descriptiva si tus identificadores son largos. El identificador importa más que el texto descriptivo.
No es obligatorio que el customsDescription del artículo sea la misma cadena que envías a tu transportista, pero así ambos lados se pueden comparar directamente cuando una línea no coincide y necesitas averiguar por qué.
La vinculación suele fallar cuando:
Falta el identificador en la descripción.
El identificador no corresponde a ningún productId o sku de tu catálogo.
El límite de caracteres del transportista trunca el identificador.
El formato cambia entre envíos.
Este comportamiento aún se está finalizando y puede cambiar antes del lanzamiento.
Nota: Los campos omitidos no se modifican, por lo que las actualizaciones parciales son seguras. Enviar null no borra un valor; simplemente se ignora. Puedes sobrescribir un valor con otro distinto, pero no puedes vaciarlo mediante la API. Si necesitas borrar un campo, comunícate con tu representante de Zonos.
API de catálogo
API de catálogo
Crea el catálogo de tu cuenta verificada de forma programática, directamente desde tu propio sistema.
La API de catálogo es una de las tres formas de crear el catálogo de tu cuenta verificada, y es la opción para los remitentes que cuentan con recursos de desarrollo y un sistema que ya contiene sus datos de producto: un ERP, WMS, PIM o plataforma de envíos. Ese sistema sigue siendo la fuente de verdad y escribe los productos directamente en Zonos, en lugar de sincronizarlos desde una integración de canal o de subir un archivo CSV. Si vendes a través de un canal compatible o prefieres no escribir código, esas dos opciones crean el mismo catálogo con menos trabajo.
Los artículos creados mediante la API reciben exactamente el mismo tratamiento que los artículos de cualquier otra fuente: una vez que un artículo está en tu catálogo, a Zonos no le importa cómo llegó ahí. Cada uno se clasifica para aduanas si no proporcionaste un código HS, se examina según los requisitos de las agencias gubernamentales asociadas de EE. UU. (PGA) y se usa para calcular los aranceles e impuestos de los envíos en los que aparece.
Hay una parte de ese proceso que queda fuera de la API. Cuando el examen de PGA marca un artículo como Necesita atención, el cuestionario de cumplimiento asociado a esa marca debe responderse y confirmarse en Dashboard: no existe una API para ello, y Zonos completa previamente lo que puede, de modo que la mayor parte del trabajo consiste en revisar y confirmar. La persona que crea esta integración no suele ser la misma que resuelve esas marcas, así que planifica que alguien de tu organización las revise en Dashboard después de que se cargue tu catálogo. Los artículos marcados no tienen bloqueado el envío, pero resolverlos antes de enviar es lo que evita que un envío quede retenido en la frontera de EE. UU.
Cómo funciona
Crea un artículo del catálogo para cada producto que envíes.
Asegúrate de que cada artículo tenga un identificador que tu transportista postal vaya a transmitir.
Cuando los datos de tu envío llegan a Zonos, cada línea se vincula con su artículo del catálogo y los datos de producto de ese artículo se aplican al cálculo.
Crear artículos del catálogo
catalogItemCreateacepta una lista, por lo que puedes enviar muchos productos en una sola solicitud.mutation CatalogItemCreate($input: [CatalogItemInput!]!) {catalogItemCreate(input: $input) {iditemKeynameproductIdskuhsCodecustomsDescriptioncountryOfOrigin}}Enviar el mismo producto dos veces
Si envías un producto cuyo SKU o ID de producto ya existe, Zonos actualiza ese producto en lugar de agregar uno nuevo. Los reintentos y las ejecuciones repetidas son seguros.
La contrapartida es que dos productos distintos que compartan un SKU o ID de producto se fusionarán en uno solo. Revisa tus datos en busca de duplicados antes de una carga masiva.
Campos
skuproductIdnamecustomsDescriptioncountryOfOriginmeasurementshsCodeamountcurrencyCodeamount.itemTypePHYSICAL_GOOD,DIGITAL_GOOD,SERVICE,SUBSCRIPTION,BUNDLEoPARTIAL_ITEM. Evita que los artículos no físicos se declaren como mercancía.provinceOfOriginproductComposition{material, percentage}. Sin ella, los textiles no pueden clasificarse más allá de 6 dígitos.catalogItemUrlimageUrlHaz que tus artículos se puedan vincular
Zonos vincula cada línea de envío con un artículo del catálogo usando tus identificadores, en este orden: ID de producto, luego SKU y, por último, nombre. Mantén precisos y consistentes los identificadores que uses, tanto en tu catálogo como en los datos que envías a tu transportista.
Los envíos postales tienen una restricción adicional. Zonos recibe un conjunto limitado de campos de los transportistas postales y, en muchas rutas, la descripción aduanera es el único campo que llega con información específica del producto. Una descripción idéntica en todo tu catálogo no puede identificar nada por sí sola.
Añade tu ID de producto o SKU al final de la descripción aduanera que envías a tu transportista.
El identificador añadido debe coincidir exactamente con el
productIdo elskudel artículo del catálogo correspondiente.Los campos de descripción son cortos. Los envíos de Canada Post, por ejemplo, admiten aproximadamente 49 caracteres, así que acorta la parte descriptiva si tus identificadores son largos. El identificador importa más que el texto descriptivo.
No es obligatorio que el
customsDescriptiondel artículo sea la misma cadena que envías a tu transportista, pero así ambos lados se pueden comparar directamente cuando una línea no coincide y necesitas averiguar por qué.La vinculación suele fallar cuando:
productIdoskude tu catálogo.Actualizar artículos del catálogo
catalogItemUpdateusa el mismo tipo de entrada que la creación. Envía solo los campos que quieras cambiar.mutation CatalogItemUpdate($input: [CatalogItemInput!]!) {catalogItemUpdate(input: $input) {iditemKeyhsCodecustomsDescription}}Consultar tus artículos
La consulta
catalogItemaceptaid,productIdosku. Úsala para confirmar qué datos tiene Zonos de un producto.query CatalogItem($sku: String!) {catalogItem(sku: $sku) {iditemKeynamecustomsDescriptionhsCodeproductIdskucountryOfOrigin}}Eliminar artículos del catálogo
catalogItemDeleterecibe los ID de artículo del catálogo de Zonos, no tus SKU ni tus ID de producto. Primero obtén el ID con la consultacatalogItem.mutation CatalogItemDelete($input: [ID!]!) {catalogItemDelete(input: $input)}Relacionado
CatalogItemInput
catalogItemCreate catalogItemDelete catalogItemUpdate
¿Fue útil esta página?