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.
Crear artículos del catálogo
catalogItemCreate acepta una lista, por lo que puedes enviar muchos productos en una sola solicitud.
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.
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.
manufacturerProductId
Solo para la UE
El identificador de producto no estandarizado del fabricante (NS-PID). Es obligatorio en los envíos B2C a la UE con un valor de 150 EUR o menos.
gtin
Solo para la UE
El identificador de producto estandarizado del fabricante (S-PID), solo dígitos. Es obligatorio en los envíos B2C a la UE con un valor de 150 EUR o menos, si el producto tiene código de barras.
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.
Agregar identificadores de producto de la UE (PID)
Si envías a la UE con tu cuenta verificada, a partir del 1 de noviembre de 2026 la UE exige identificadores de producto (PID) en los envíos de empresa a consumidor (B2C) con un valor de 150 EUR o menos. Guárdalos en tus artículos del catálogo. En la mayoría de las cuentas verificadas, tu servicio postal envía a Zonos los datos del envío, y Zonos vincula cada artículo del envío con tu catálogo y aplica los identificadores que guardaste, por lo que no tienes que enviar nada adicional al momento del envío.
Identificador↕
Qué es↕
Campo de la API↕
¿Obligatorio?↕
Identificador de producto del comerciante (M-PID)
Tu SKU o código de artículo
sku
Siempre
Identificador de producto no estandarizado del fabricante (NS-PID)
El número de modelo o de pieza del fabricante. Si tú mismo fabricas el producto, usa tu propio número de modelo o de pieza.
manufacturerProductId
Siempre
Identificador de producto estandarizado del fabricante (S-PID)
El código de barras (UPC, EAN o ISBN)
gtin
Solo si el producto tiene uno
Envía los identificadores con catalogItemCreate para los productos nuevos. Para los productos que ya están en tu catálogo, envíalos con catalogItemUpdate, que acepta los mismos campos. Haz que el sku de cada artículo coincida con el SKU que usas en todos los demás lugares, para que Zonos pueda vincular ambos.
Envía el gtin solo con dígitos, sin guiones ni espacios. Los valores UPC, EAN, JAN e ISBN de 13 dígitos van todos en este mismo campo. Si tienes un ISBN de 10 dígitos, envía en su lugar la versión de 13 dígitos.
Si un producto no tiene código de barras, omite gtin en lugar de enviar una cadena vacía, reutilizar tu SKU o completarlo con texto de relleno como N/A.
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.
La forma de dar formato al identificador en los datos de envío que envías a tu transportista depende de tu servicio postal, porque cada uno vincula los envíos con tu catálogo de manera diferente. Ve a todos los servicios postales y selecciona el tuyo. Su página muestra cómo funciona la vinculación para ese servicio postal y exactamente qué debes enviar.
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 en los datos del envío el identificador con el que vincula tu servicio postal.
El identificador no coincide exactamente con nada 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.
Actualizar artículos del catálogo
catalogItemUpdate usa el mismo tipo de entrada que la creación. Envía solo los campos que quieras cambiar.
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.
Consultar tus artículos
La consulta catalogItem acepta id, productId o sku. Úsala para confirmar qué datos tiene Zonos de un producto.
1queryCatalogItem($sku: String!){
2 catalogItem(sku:$sku) {
3 id
4 itemKey
5 name
6 customsDescription
7 hsCode
8 productId
9 sku
10 countryOfOrigin
11}
12}
Eliminar artículos del catálogo
catalogItemDelete recibe 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 consulta catalogItem.
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
skuproductIdmanufacturerProductIdgtinnamecustomsDescriptioncountryOfOriginmeasurementshsCodeamountcurrencyCodeamount.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.catalogItemUrlimageUrlAgregar identificadores de producto de la UE (PID)
Si envías a la UE con tu cuenta verificada, a partir del 1 de noviembre de 2026 la UE exige identificadores de producto (PID) en los envíos de empresa a consumidor (B2C) con un valor de 150 EUR o menos. Guárdalos en tus artículos del catálogo. En la mayoría de las cuentas verificadas, tu servicio postal envía a Zonos los datos del envío, y Zonos vincula cada artículo del envío con tu catálogo y aplica los identificadores que guardaste, por lo que no tienes que enviar nada adicional al momento del envío.
skumanufacturerProductIdgtinEnvía los identificadores con
catalogItemCreatepara los productos nuevos. Para los productos que ya están en tu catálogo, envíalos concatalogItemUpdate, que acepta los mismos campos. Haz que elskude cada artículo coincida con el SKU que usas en todos los demás lugares, para que Zonos pueda vincular ambos.mutation CatalogItemCreate($input: [CatalogItemInput!]!) {catalogItemCreate(input: $input) {idskumanufacturerProductIdgtinEnvía el
gtinsolo con dígitos, sin guiones ni espacios. Los valores UPC, EAN, JAN e ISBN de 13 dígitos van todos en este mismo campo. Si tienes un ISBN de 10 dígitos, envía en su lugar la versión de 13 dígitos.Si un producto no tiene código de barras, omite
gtinen lugar de enviar una cadena vacía, reutilizar tu SKU o completarlo con texto de relleno comoN/A.Si llamas tú mismo a la Landed Cost API, también puedes incluir estos identificadores en tu solicitud de landed cost. La mayoría de las cuentas verificadas no lo hacen, porque es el servicio postal el que envía a Zonos los datos del envío.
Para saber qué exige la normativa, consulta la guía de identificadores de producto de la UE.
Haz 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.
La forma de dar formato al identificador en los datos de envío que envías a tu transportista depende de tu servicio postal, porque cada uno vincula los envíos con tu catálogo de manera diferente. Ve a todos los servicios postales y selecciona el tuyo. Su página muestra cómo funciona la vinculación para ese servicio postal y exactamente qué debes enviar.
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:
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?