Migrar de VTEX a Magento + Hyvä: cómo mapear catálogo, SKUs, clientes y pedidos

• El catálogo de VTEX tiene cuatro piezas: categorías, productos, SKUs y especificaciones. Cada una tiene su equivalente en Magento.
• Los atributos de Magento deben existir antes de importar: la importación nativa no los crea.
• Clientes y direcciones salen de Master Data con el endpoint de scroll, máximo 1,000 documentos por solicitud.
• La Orders API de VTEX solo da acceso a pedidos de los últimos dos años. Si quieres más historial, exporta antes.
• Las contraseñas no se migran: planea un restablecimiento para tus clientes.

¿Cómo exporto mis datos de VTEX para migrar a Magento?

Por API, una entidad a la vez: catálogo, clientes, direcciones y pedidos. Las exportaciones a hoja de cálculo del Admin sirven para revisar, pero para una migración completa y repetible conviene extraer todo por API.

Esto es lo que sale de cada lado de VTEX:

• Catálogo: la Catalog API entrega categorías, marcas, productos, SKUs, especificaciones e imágenes.
• Clientes y direcciones: viven en Master Data v1, en las entidades CL (perfiles) y AD (direcciones). Se extraen con el endpoint de scroll; VTEX también permite exportarlos a XLS desde el Admin.
• Pedidos: se consultan con la Orders API (OMS). El listado da los encabezados; el detalle de cada pedido se pide aparte.

Antes de extraer nada, haz un inventario: cuántos productos y SKUs activos e inactivos tienes, qué campos personalizados agregó tu equipo en Master Data y cuántos años de pedidos necesitas de verdad para atención y recompra.

¿Cómo se mapea el catálogo de VTEX en Magento?

Cada concepto de VTEX tiene un equivalente en Magento, pero no siempre uno a uno. La decisión más importante es cómo conviertes productos con variaciones.

En VTEX, el producto es la definición general (una playera) y el SKU es cada variación física (la playera azul talla M). Todo producto debe tener al menos un SKU. Las especificaciones se definen en grupos asociados a una categoría y se heredan a las subcategorías.

Un punto que suele sorprender: en Magento no puedes crear atributos durante la importación. Según la documentación de Adobe Commerce, el archivo CSV solo acepta atributos que ya existen. Por eso el orden es crear atributos y conjuntos de atributos primero, y después importar productos.

¿Qué pasa con las especificaciones y los SKUs de VTEX?

Se convierten en atributos de Magento, y aquí está la mayor oportunidad de limpiar el catálogo. Lo que en VTEX creció sin orden no tiene por qué llegar igual a tu tienda nueva.

En VTEX, las especificaciones de SKU solo pueden ser de tipo Combo o Radio, y son las que distinguen una variación de otra. Las de producto aceptan más tipos: texto, texto largo, número, combo, radio, casilla y texto indexado. Esa diferencia te ayuda a decidir:

• Las especificaciones de SKU (talla, color, voltaje) se vuelven los atributos que definen tu producto configurable.
• Las especificaciones de producto que usas como filtro se vuelven atributos filtrables en la navegación por capas de Magento.
• Las que solo se muestran en la ficha (composición, cuidados) pueden ser atributos de texto, sin filtro.
• Las que nadie usa o están vacías se quedan fuera. No migres basura.

Con Hyvä, esos atributos se muestran en un frontend ligero hecho con Tailwind y Alpine.js, así que una estructura limpia también se nota en la velocidad. Más detalle en Hyvä Commerce.

¿Cómo migro clientes y direcciones de VTEX?

Extraes CL y AD de Master Data y los importas en Magento como clientes y direcciones. La relación entre ambos se conserva con el identificador del cliente.

Para la extracción, VTEX recomienda el endpoint de scroll cuando hay más de 10,000 documentos. Tiene reglas que conviene conocer:

• Máximo 1,000 documentos por solicitud.
• El token de scroll expira si pasan 20 minutos sin usarlo.
• Puedes correr hasta 10 scrolls simultáneos por cuenta.
• VTEX sugiere dividir por filtros, por ejemplo por fecha de creación, para evitar tiempos de espera.

Del lado de Magento, la importación nativa tiene tres tipos de entidad para esto: Customers Main File (solo cuentas), Customer Addresses (solo direcciones) y Customers and Addresses (ambos en un archivo). Si tu tienda vende B2B, aquí también decides los grupos de clientes, porque de ellos dependen precios y reglas.

Dos cosas que no se negocian. Primero, las contraseñas: los perfiles de Master Data no las incluyen en sus campos exportables, así que tus clientes tendrán que crear una nueva. Planea un correo de restablecimiento antes del lanzamiento. Segundo, la privacidad: migra solo lo que tu aviso de privacidad permite y respeta quién aceptó recibir newsletter (el campo isNewsletterOptIn).

¿Se pueden migrar los pedidos históricos de VTEX?

Sí, pero con límites de los dos lados. VTEX solo da acceso por API a pedidos de los últimos dos años, y Magento no trae un importador nativo de pedidos.

Lo que dice la documentación de VTEX sobre el listado de pedidos:

• Solo devuelve pedidos creados en los últimos dos años.
• Llega a 30 páginas por consulta, con un máximo de 100 pedidos por página. Para volúmenes grandes, divides por rangos de fecha.
• No incluye los productos de cada pedido; para eso consultas el detalle de cada uno.

En Magento, la importación nativa cubre productos, precios avanzados, clientes, direcciones e inventario por fuente, pero no pedidos. Los pedidos históricos se cargan con un script o módulo a la medida. Mi recomendación: decide para qué los quieres. Si es para que el cliente vea su historial y para atención, basta con los encabezados, los productos y los estados finales. No intentes recrear cada movimiento de pago.

Si tu operación necesita más de dos años de historial, exporta y guarda esos pedidos hoy, aunque la migración sea el año que entra.

¿En qué orden se hace la migración de datos?

Primero la estructura, luego el catálogo y al final las personas y su historial. Y siempre con migraciones de prueba antes del corte.

1. Inventario y limpieza: decide qué productos, especificaciones y clientes sí viajan.
2. Estructura en Magento: categorías, atributos y conjuntos de atributos.
3. Catálogo: productos simples, configurables, imágenes, precios e inventario.
4. Clientes y direcciones, con sus grupos.
5. Pedidos históricos, si los necesitas.
6. URLs: mapa de cada URL de VTEX a su nueva URL con redirección 301.
7. Al menos dos migraciones de prueba con validación de tu equipo, y un corte final con los datos del último momento.

Las integraciones con tu ERP van en paralelo y casi siempre son el reto mayor. Ver integraciones de Magento.

Lo que hemos visto en migraciones reales

Desde 2011 hemos hecho unos 300 proyectos de ecommerce y entre 65 y 75 migraciones, unas 10 de ellas desde VTEX. Una migración desde VTEX nos toma de 2 a 4 meses, según qué tan rápido valida el equipo del cliente. Los datos casi nunca son el problema técnico; el problema es decidir qué se queda y qué se va. En catálogos grandes, como los unos 50,000 SKUs de Águila Azteca (que venía de un desarrollo a la medida, no de VTEX), la limpieza y el mapeo de atributos tomaron tanto cuidado como la integración con su ERP.

¿Qué se rompe si el mapeo sale mal?

Casi siempre lo mismo: filtros, variaciones, URLs y accesos de clientes. Todo es prevenible con pruebas.

• Filtros vacíos o duplicados: por valores sin normalizar (Azul y azul como dos opciones).
• Variaciones huérfanas: SKUs que no quedaron ligados a su configurable y aparecen sueltos o no aparecen.
• SEO: URLs de producto y categoría sin redirección 301 que pierden el tráfico que ya tenías.
• Clientes sin acceso: si no avisaste del restablecimiento de contraseña, el primer día llegan quejas a soporte.
• Precios equivocados: cuando había precios por lista o por tipo de cliente y no se mapearon a grupos de clientes.

¿Cuándo NO conviene migrar de VTEX a Magento?

No conviene si VTEX te funciona, tu contrato es favorable y no tienes integraciones complejas. Migrar por moda sale caro.

Tampoco conviene si tu catálogo tiene menos de unos 10 productos, si esperas que la plataforma haga todo sin configuración o si no tienes a alguien interno que valide datos. Y nunca en temporada alta. Si el argumento es el costo, revisa primero cómo migrar de VTEX a Magento y ahorrar en comisiones.

Construimos este tipo de migraciones como parte de nuestro desarrollo en Magento Open Source. Si quieres saber qué tan limpio está tu catálogo de VTEX y cuánto ahorrarías frente a tu plataforma actual, agenda un diagnóstico gratis de 30 minutos.

Preguntas frecuentes

¿Puedo exportar todo mi catálogo de VTEX a un Excel y subirlo a Magento?

Sirve para revisar, pero no como método principal. El formato de VTEX no coincide con el CSV de Magento, y los atributos tienen que existir antes de importar. Lo confiable es extraer por API, transformar con un script y probar la importación varias veces.

¿Los SKUs de VTEX conservan su código en Magento?

Pueden conservarlo. Decides qué identificador de VTEX será el sku en Magento (muchas tiendas usan el RefId) y lo mantienes para que tu ERP y tu equipo sigan reconociendo cada producto.

¿Mis clientes tendrán que registrarse otra vez?

No. Sus cuentas, datos y direcciones se migran. Lo único que cambia es la contraseña: reciben un correo para crear una nueva.

¿Cuántos años de pedidos puedo llevarme?

Por API, VTEX solo da acceso a los pedidos de los últimos dos años. Si necesitas más, exporta y guarda tu historial antes de que esos pedidos salgan de ese periodo.

¿Cuánto tarda una migración de VTEX a Magento?

En nuestra experiencia, de 2 a 4 meses en total, incluyendo integraciones y pruebas. La migración de datos es una parte; lo que más influye es la rapidez con la que tu equipo valida.

Fuentes

• VTEX Help Center: arquitectura del catálogo
• VTEX Help Center: especificaciones de SKU
• VTEX Help Center: especificaciones de producto
• VTEX Developers: extraer datos de Master Data con search y scroll
• VTEX Help Center: exportar datos de Master Data v1
• VTEX Developers: Orders API
• Adobe Commerce: importar datos
• Adobe Commerce: estructura de archivos CSV

Transparencia: Panamerik es partner de Cloudways (hosting) y de Hyvä. No obligamos a nadie a usarlos: trabajamos con el hosting y las herramientas que tú prefieras. Los datos de experiencia de este artículo son aproximados y vienen de nuestros proyectos desde 2011.