Los fallos en una migración hacia VTEX rara vez se deben a un único campo ausente. Aparecen cuando una arquitectura comercial conectada se trata como si fuera simplemente un destino para Products, Customers y Orders. Un registro puede existir mientras su relación con SKU, contexto de Trade Policy, responsabilidad de seller, ruta de preparación de pedidos, vínculo de Master Data o identificador de sistema externo ya no conserva el significado que necesita la operación.
Los siguientes problemas se centran en patrones de fallo recurrentes. Cada uno explica qué se rompe, qué señales permiten detectarlo pronto, cómo prevenirlo, una recomendación práctica y la condición que demuestra que el riesgo está controlado.
Mapa de prevención de problemas en VTEX
| Área operativa | Patrón de fallo oculto | Foco de prevención |
|---|---|---|
| Catalog | Los registros de Product existen, pero las relaciones de SKU y specifications están incompletas. | Conservar la cadena Product-SKU-Category-specification. |
| Contexto comercial | Un precio válido se aplica en el canal de ventas o contexto de seller equivocado. | Mapear por separado responsabilidad de precio, Trade Policies y offer del sellers. |
| Marketplace | Products y Orders pierden responsabilidad de seller, offer, comisión o preparación de pedidos. | Conservar relaciones de marketplace y sellers, no solo etiquetas. |
| Logistics | Los totales de inventario se transfieren sin warehouses, docks, carriers o significado de entrega. | Reconstruir la red de preparación de pedidos alrededor de responsables explícitos. |
| Orders | Los totales siguen siendo legibles, pero desaparecen composición de paquetes, invoice, cancelaciones o referencias externas. | Conservar contexto histórico de transacción y trazabilidad. |
| Datos personalizados | Master Data y registros propiedad de aplicaciones se aplanan dentro de campos ordinarios de Customer. | Clasificar cada objeto personalizado por schema, relación y responsable. |
| Integraciones | ERP, PIM, WMS o marketplaces se reconectan con IDs rotos o dirección de actualización incorrecta. | Conservar identificadores y establecer una autoridad por dominio de datos. |
| Storefront | La presencia en Catalog se confunde con comportamiento completo de Search, Checkout y contenido. | Asignar implementación de Storefront y Checkout por separado de los registros migrados. |
Problema 1: tratar VTEX como una única Store autocontenida
Qué sale mal
La migración se diseña como si VTEX fuera una única base de datos y un único Storefront. En la práctica, Catalog, Pricing, Promotions, Checkout, Orders, Inventory y shipping, relaciones de marketplace, Master Data, implementación de Storefront y sistemas externos pueden controlar partes diferentes del modelo operativo. Los registros pueden parecer correctos en un módulo mientras otro aplica una disponibilidad, precio, seller o comportamiento de preparación de pedidos distintos.
Esto crea una falsa sensación de completitud. El equipo aprueba conteos de Products y Orders aunque nadie pueda explicar qué sistema controla realmente los valores que utilizarán Customers y operaciones.
Señales de alerta temprana
| Señal de alerta | Consecuencia probable |
|---|---|
| El alcance enumera únicamente Products, Customers y Orders. | Dependencias de Trade Policies, sellers, Logistics o datos personalizados permanecen invisibles. |
| Una sola persona revisa todas las áreas de datos. | Se acepta contexto importante sin el responsable de negocio adecuado. |
| Los sistemas externos se describen solo como "integraciones". | La responsabilidad sobre campos y la dirección de actualización quedan indefinidas. |
| Se espera que Storefront siga automáticamente los registros de Catalog. | Aparecen brechas de Search, contenido, Checkout y navegación después de cargar los registros. |
Prevención
Modele el destino por dominios operativos. Para cada valor importante, identifique si su responsable futuro será VTEX Catalog, Pricing, Promotions, Checkout, Orders, Inventory y shipping, Master Data, un seller, la implementación de Storefront o un sistema externo. Utilice al menos un escenario representativo que atraviese varios dominios para que los traspasos entre responsables queden visibles.
Ejemplo de recomendación
Siga un SKU de alto valor desde Catalog, pasando por specification, contexto de precio, seller o responsabilidad de first-party, ubicación de inventario, promesa de entrega, selección en Checkout, creación del Order e identificador del sistema back-office. El mismo escenario debe tener revisores identificados de merchandising, operaciones comerciales, Logistics y responsabilidad de integraciones.
Condición de aprobación
Cada dominio crítico para lanzamiento tiene un responsable declarado y el equipo puede explicar cómo un Product representativo pasa de descubrimiento en Catalog a precio, disponibilidad, Checkout, Order, preparación de pedidos y reconciliación externa.
Problema 2: aplanar el significado de Product, SKU y specifications
Qué sale mal
Products y variantes del origen se aplanan en registros genéricos de Product de VTEX. Las opciones a nivel de SKU, imágenes, dimensiones, referencias de stock y valores de specifications pierden su relación con la unidad vendible. Product specifications pueden copiarse como texto aunque deberían sostener información o navegación, mientras SKU specifications necesarias para selección del comprador quedan asociadas al nivel equivocado.
El Product puede existir y, aun así, seguir no disponible, difícil de encontrar o imposible de seleccionar correctamente. El defecto es estructural, no cosmético.
Señales de alerta temprana
| Señal de Catalog | Patrón de fallo |
|---|---|
| Campos de Product y SKU se revisan en una sola hoja plana. | Las variaciones vendibles pierden sus propios identificadores y atributos. |
| Valores como talla, voltaje o color se almacenan como texto de Product. | La selección de SKU y los filtros dejan de representar la unidad comprable. |
| Las imágenes se conservan únicamente a nivel de Product. | El SKU seleccionado muestra media incorrecto. |
| Se cuentan specifications sin clasificarlas por finalidad. | Search, filtros, detalles de Product o integraciones reciben valores inutilizables. |
Prevención
Clasifique cada valor del origen como datos de Product, datos de SKU, Product specification, SKU specification, media, identificador externo o presentación exclusiva de Storefront. Conserve el orden de creación y dependencias entre Categories, grupos de specifications, campos, Products, SKUs, valores de specifications y archivos de SKU. No infiera éxito a partir del SKU predeterminado.
Ejemplo de recomendación
Para un electrodoméstico disponible en varios voltajes y acabados, conserve el modelo genérico como Product, cada combinación comprable como SKU, voltaje y acabado como valores de selección de SKU cuando corresponda, información técnica como Product specifications e imágenes y dimensiones específicas vinculadas con la unidad vendible real.
Condición de aprobación
Las familias representativas de Products conservan la relación Product-SKU correcta, diferencias seleccionables, specifications, imágenes, identificadores y unidades vendibles activas sin depender de texto descriptivo aplanado.
Problema 3: romper dependencias entre Categories y specifications
Qué sale mal
Las Categories se copian como etiquetas de navegación sin conservar cómo gobiernan la organización de Catalog y los requisitos de specifications. Los grupos o campos de specifications se crean después de Products y SKUs, se asocian con la Category incorrecta o se rellenan con valores inconsistentes. Un cambio tardío de Category o specification puede desactivar SKUs, fragmentar filtros o dejar Products importantes sin información obligatoria.
El Catalog resultante puede contener los registros esperados mientras Search y activación de Products se comportan de forma impredecible.
Señales de alerta temprana
| Señal de dependencia | Riesgo creado |
|---|---|
| La profundidad de Categories se copia sin un modelo de navegación en destino. | La jerarquía de Catalog se vuelve más difícil de mantener y explorar. |
| Los campos de specifications se crean independientemente de Categories. | Los valores obligatorios y filtros difieren entre Products relacionados. |
| Se añaden nuevas SKU specifications después de cargar Products en masa. | Los SKUs asociados pueden quedar inactivos hasta completar valores. |
| Valores equivalentes usan ortografía o unidades inconsistentes. | Los filtros se fragmentan en opciones duplicadas o engañosas. |
Prevención
Diseñe el modelo de Categories y specifications antes de cargar Products en masa. Defina qué Categories requieren qué Product o SKU specifications, normalice valores controlados y conserve la secuencia necesaria para crear y asociar esos registros. Trate cambios posteriores de schema como cambios controlados de Catalog, no como ediciones informales de contenido.
Ejemplo de recomendación
Para un Catalog de electrónica, establezca primero departamento, Category, grupos de specifications, campo de voltaje, campo de capacidad y valores permitidos. Complete una familia y verifique estado activo, filtros y selección en Storefront antes de extender el patrón.
Condición de aprobación
Categories, grupos de specifications, campos, valores, Products y SKUs forman una cadena de dependencias coherente y los SKUs representativos permanecen activos y encontrables después de aplicar el schema de destino.
Problema 4: trasladar precios sin contexto de Trade Policy y seller
Qué sale mal
La migración conserva un único precio por SKU mientras la operación real diferencia precios, Promotions, disponibilidad, Logistics o Payments por canal de ventas, Trade Policy, seller, segmento de Customer o sistema externo de precios. Un valor numéricamente correcto puede ser comercialmente incorrecto en el contexto donde lo ve el Customer.
Las Promotions históricas también pueden confundirse con configuración actual, provocando reconstrucción de descuentos obsoletos o pérdida de reglas comerciales activas.
Señales de alerta temprana
| Señal comercial | Problema oculto |
|---|---|
| Solo se compara un precio base. | Pricing específico por canal, seller o segmento queda sin contemplar. |
| Las Trade Policies se analizan después de cargar Catalog. | Price, Promotion, Logistics y Payments pueden requerir retrabajo. |
| Los nombres de Promotions se consideran evidencia suficiente. | Condiciones, elegibilidad y comportamiento de acumulación no se conservan. |
| No está claro quién controla ERP o precios engine. | Los valores migrados se sobrescriben o entran en conflicto con actualizaciones externas. |
Prevención
Mapee el contexto comercial por separado de los datos de Product. Para cada SKU prioritario, identifique responsable del precio, canal de ventas o Trade Policy aplicable, seller, dependencias de Promotion, contexto de Customer y dirección de actualización. Conserve evidencia histórica de precios solo cuando siga siendo útil; configure el comportamiento comercial actual bajo su responsable real en destino.
Ejemplo de recomendación
Use un SKU vendido directamente y mediante marketplace, con precio B2C, contexto B2B y una Promotion activa. Documente qué valores entran en VTEX, cuáles proceden de un servicio externo y qué condiciones determinan el resultado final que ve el Customer.
Condición de aprobación
Los SKUs prioritarios muestran resultados explicables de precio y Promotion en cada contexto comercial previsto, sin conflictos pendientes entre valores migrados, configuración de VTEX, sellers y sistemas externos.
Problema 5: perder responsabilidad de seller y offer
Qué sale mal
Los datos de marketplace se tratan como datos ordinarios de Product. Identidad de seller, responsabilidad de offer, correspondencia de SKU, responsabilidad sobre precio y stock, contexto de comisión, expectativas de nivel de servicio y responsabilidad de preparación de pedidos se aplanan en notas o se descartan. Los Products pueden aparecer en marketplace, pero la operación deja de saber quién controla la offer o quién debe preparar el Order resultante.
El problema es especialmente grave cuando varios sellers ofrecen el mismo SKU o cuando una empresa actúa como marketplace y como seller en otros contextos.
Señales de alerta temprana
| Señal de marketplace | Patrón de fallo |
|---|---|
| Los IDs de seller se guardan como atributos de Product. | La responsabilidad de marketplace no puede gobernar offers y Orders. |
| Se crean Products duplicados para offer del sellers. | Matching de Catalog y comportamiento de buy box se fragmentan. |
| Orders de marketplace y seller se revisan juntos. | Se confunden responsable de Checkout y responsable de preparación de pedidos. |
| Se eliminan referencias externas de sellers. | La reconciliación y actualizaciones del conector crean duplicados. |
Prevención
Separe identidad de Catalog de identidad de offer del seller. Conserve identificadores de seller, referencias de correspondencia de SKU, responsabilidad de precio y cantidad, referencias de Orders de marketplace, responsabilidad de preparación de pedidos y claves de conectores externos. Defina si la cuenta de destino actúa como marketplace, seller o ambos en cada relación.
Ejemplo de recomendación
Para un Product de marca suministrado por tres sellers, mantenga una única identidad de Catalog del marketplace y tres offers distintas con seller, precio, stock y responsabilidad de entrega. Revise un Order que seleccione un seller y confirme que la parte correcta lo recibe y prepara.
Condición de aprobación
Los Products representativos de marketplace conservan offers de seller correctas, responsabilidad, correspondencia, precio, stock, routing de Orders y preparación de pedidos sin crear identidades duplicadas de Catalog.
Problema 6: aplanar Inventory y Logistics en una única cantidad
Qué sale mal
La migración transfiere una cantidad disponible pero pierde warehouses, registros de inventario, loading docks, carriers, políticas de entrega, ubicaciones de recogida, relaciones de Trade Policy o responsabilidad externa de WMS. Storefront puede mostrar stock mientras Checkout no puede producir la promesa de entrega prevista, o la ubicación equivocada puede tratarse como origen de la preparación de pedidos.
Una cantidad inicial tampoco es fiable si ERP o WMS se convertirá inmediatamente en la autoridad continua.
Señales de alerta temprana
| Señal de Logistics | Consecuencia operativa |
|---|---|
| Una cantidad total sustituye stock por ubicación. | La disponibilidad no puede asignarse al punto correcto de preparación de pedidos. |
| Inventory se carga antes de que existan relaciones de Logistics. | Las simulaciones de Checkout producen opciones de entrega incompletas o engañosas. |
| Pickup y delivery se tratan como la misma ruta. | Se pierden compromisos de ubicación y nivel de servicio. |
| Las actualizaciones de ERP o WMS no se pausan ni secuencian. | Las quantities migradas se sobrescriben antes de reconciliarse. |
Prevención
Mapee la red de preparación de pedidos, no solo los valores de stock. Identifique ubicaciones de inventario, relaciones de Logistics, rutas de entrega y pickup, responsabilidad externa, identificadores de SKUs y secuencia para abrir inventario y continuar la sincronización. Conserve las etiquetas históricas de shipping por separado de la configuración de entrega actual.
Ejemplo de recomendación
Para un SKU almacenado en dos warehouses y disponible para pickup en regiones seleccionadas, siga qué inventario se ofrece en cada canal de ventas, qué promesa de entrega aparece en Checkout y qué sistema publica la cantidad futura.
Condición de aprobación
Los SKUs representativos tienen disponibilidad correcta por ubicación, resultados explicables de delivery o pickup y un único responsable continuo documentado para cada actualización de stock.
Problema 7: reducir Orders a totales y etiquetas de estado
Qué sale mal
Los Orders se migran con número de Order, Customer, total y status genérico, pero composición de paquetes, relación con seller, sustituciones de artículos, shipping, referencias de invoices, historial de cancelaciones, reembolsos, tracking, IDs externos o contexto de marketplace dejan de ser interpretables. El equipo de soporte puede localizar el Order pero no explicar qué ocurrió.
Los registros históricos también pueden confundirse con prueba de que Checkout, Payments, impuestos y configuración de preparación de pedidos actuales funcionan.
Señales de alerta temprana
| Evidencia de Order | Significado ausente |
|---|---|
| Se ve un total final. | Descuentos, impuestos, envío, reembolsos o ajustes no pueden explicarse. |
| Se conserva un único status. | El ciclo de vida del origen y su significado actual son ambiguos. |
| Los nombres de Products son legibles. | Faltan relaciones de SKU, seller, package y preparación de pedidos. |
| Se omiten referencias externas. | Se rompe reconciliación con ERP, WMS, marketplace o contabilidad. |
Prevención
Defina el uso histórico de Orders y conserve la evidencia necesaria para soporte, finanzas, operaciones de sellers y reconciliación. Incluya identificadores de items y SKUs, relación de Customer, contexto de seller y marketplace, componentes financieros, datos de packages y shipments, referencias de invoice o tracking, historial de status cuando aporte valor y claves externas. Mantenga la configuración activa de Checkout fuera de la interpretación de Orders históricos.
Ejemplo de recomendación
Revise un Order directo, uno de marketplace, uno con varios packages, uno cancelado y uno refunded. Un agente de servicio debe poder explicar items, seller, resultado financiero, estado de preparación de pedidos y trazabilidad externa sin abrir la plataforma de origen.
Condición de aprobación
Los Orders históricos representativos siguen siendo comprensibles en dimensiones de Customer, SKU, seller, finanzas, package, invoice, preparación de pedidos, cancelación o refund y sistemas externos sin volver a consultar la plataforma de origen.
Problema 8: tratar Master Data como campos ordinarios de Customer
Qué sale mal
Entidades de Master Data, schemas personalizados, registros relacionados, objetos propiedad de aplicaciones y referencias externas se comprimen en unos pocos campos de Customer u Order. Las relaciones entre empresas, contactos, aprobaciones, registros de loyalty, solicitudes de servicio o entidades operativas desaparecen porque los schemas de origen y destino no se tratan como objetos estructurados.
El perfil visible de Customer puede parecer completo mientras flujos de trabajo e integraciones pierden los registros de los que realmente dependen.
Señales de alerta temprana
| Señal de datos personalizados | Riesgo creado |
|---|---|
| Cada registro personalizado se describe como campo de Customer. | Se pierden entidades separadas y relaciones one-to-many. |
| Se enumeran schemas sin claves de relación. | Los registros no pueden conectarse después de cargarse. |
| Los objetos propiedad de aplicaciones no aparecen en las muestras. | Los flujos de trabajo operativos fallan fuera de los registros comerciales estándar. |
| Se copian datos personales sin una regla de responsabilidad. | Quedan poco claros requisitos de privacidad, retención y acceso. |
Prevención
Inventaríe objetos personalizados por schema, clave principal, relación, finalidad comercial, sensibilidad, responsable actual, responsable de destino y consumidor futuro. Conserve solo los datos que tengan un uso válido en destino y mantenga estructuradas las relaciones estructuradas. Los datos personalizados que continúen fuera de VTEX deben conservar los identificadores necesarios para enlazarlos con seguridad con los registros VTEX.
Ejemplo de recomendación
En una operación B2B, separe identidad de empresa, contactos compradores, registros de rol o aprobación, referencias comerciales y perfiles de Customer. Conserve las claves que los conectan en lugar de concatenar todos los valores dentro de notas.
Condición de aprobación
Cada objeto personalizado crítico para el negocio tiene schema, relación, responsable y uso de destino explícitos, sin entidades estructuradas escondidas dentro de campos genéricos de Customer u Order.
Problema 9: reconectar ERP, PIM y WMS con identidades rotas
Qué sale mal
Los sistemas externos se reconectan usando nuevos IDs de VTEX sin conservar IDs de referencia del origen, tablas de correspondencia, dirección de actualización o secuencia de eventos. PIM crea Products duplicados, ERP sobrescribe precios, WMS publica inventario en el SKU equivocado u actualizaciones de Orders fallan porque cada sistema identifica el mismo registro de forma distinta.
Una conexión de API técnicamente correcta puede dañar datos migrados inmediatamente.
Señales de alerta temprana
| Señal de integración | Fallo probable |
|---|---|
| Los nuevos IDs de VTEX se tratan como los únicos identificadores. | Los sistemas externos no pueden reconocer los registros migrados. |
| No se distingue comportamiento de create y update. | La primera sincronización duplica objetos existentes. |
| Dos sistemas pueden escribir el mismo campo. | Los valores oscilan o se sobrescriben mutuamente. |
| Orders históricos y Orders activos usan un feed indiferenciado. | Registros antiguos desencadenan procesamiento operativo no previsto. |
Prevención
Cree un contrato de identidad y responsabilidad para cada integración. Conserve IDs del origen cuando sean necesarios, registre IDs de VTEX, defina comportamiento create-versus-update, establezca un único escritor por campo o dominio y secuencie la sincronización inicial después de reconciliar registros migrados. Separe datos históricos de eventos operativos activos.
Ejemplo de recomendación
Para una integración con PIM y WMS, cree referencias cruzadas para identificadores de Product, SKU e inventario. PIM puede controlar contenido descriptivo de Catalog, mientras WMS controla stock por ubicación; ninguno debe sobrescribir campos controlados por el otro.
Condición de aprobación
Cada sistema externo actualiza exactamente una vez el registro VTEX previsto, usa referencias cruzadas estables y dispone de un límite documentado de lectura/escritura que evita duplicados y conflictos de sobrescritura.
Problema 10: asumir que los datos de Catalog crean Storefront y Checkout
Qué sale mal
Los registros de Catalog se tratan como una experiencia de Customer completa en VTEX. Indexación de Search, facetas, componentes de página de Product, contenido, navegación, visualización de sellers, simulación de carrito, campos de Checkout, Payments, envíos, impuestos e integraciones de Storefront siguen siendo responsabilidades separadas de implementación. Los Products pueden existir y, aun así, ser difíciles de encontrar o imposibles de comprar mediante la ruta prevista.
El fallo suele diagnosticarse erróneamente como una mala migración cuando el responsable ausente es Storefront, Search, Checkout o implementación de integración.
Señales de alerta temprana
| Señal del recorrido del Customer | Brecha oculta |
|---|---|
| Los Products solo se revisan en Admin. | Quedan ocultos defectos de Search, filtros, página de Product y visualización de sellers. |
| Las URLs de alto valor no tienen mapa de destino. | Content y entradas orgánicas pierden continuidad. |
| Se reutilizan etiquetas históricas de Payments y shipping como configuración. | Los métodos actuales de Checkout siguen sin implementar. |
| Los componentes headless o composable no tienen responsables. | Datos correctos nunca llegan a la experiencia orientada al Customer. |
Prevención
Separe registros migrados de implementación de Storefront y Checkout. Defina modelo de Search y facetas, requisitos de datos para páginas de Product, destinos de contenido y URLs, presentación de sellers, contratos de cart y Checkout y servicios externos. Utilice los mismos escenarios representativos de Product y Order a través de Catalog, Storefront y responsabilidad de Checkout para que las brechas no puedan esconderse entre equipos.
Ejemplo de recomendación
Para un Product prioritario, confirme que la URL prevista resuelve, Search lo encuentra, los filtros exponen specifications correctas, puede seleccionarse SKU y seller adecuados, la simulación de carrito devuelve precio y disponibilidad actuales y Checkout recibe el contexto necesario de delivery y Customer.
Condición de aprobación
Los recorridos prioritarios del Customer usan correctamente los registros migrados desde descubrimiento y selección de Product hasta contexto de seller, cart y Checkout, con cada comportamiento no relacionado con datos asignado a un responsable nombrado en destino.
Conclusión
Una migración hacia VTEX tiene éxito cuando sobreviven relaciones y responsabilidades, no simplemente registros. Estructura Product-SKU, specifications, Trade Policies, sellers, Logistics, Orders, Master Data, integraciones, Search y Checkout deben permanecer conectados mediante identidades y responsabilidades explícitas. El patrón de prevención más seguro consiste en seguir escenarios comerciales representativos a través de estos límites y exigir una condición clara de aprobación para cada patrón de fallo recurrente.
Preguntas frecuentes
¿Por qué pueden existir Products en VTEX y seguir sin estar disponibles para Customers?
Un Product puede seguir sin SKU activo, valores obligatorios de specifications, imágenes, precio, inventario, offer del seller, relación con Trade Policy o exposición en Storefront. La disponibilidad depende del contexto conectado de Catalog y comercio, no únicamente de la presencia del Product.
¿Cuál es la relación de Catalog más importante que debe conservarse en VTEX?
La relación Product-SKU es central, pero depende de Categories, grupos de specifications, Product y SKU specifications, media, identificadores y unidades vendibles activas. Aplanar estos registros elimina la estructura que utilizan compradores e integraciones.
¿Por qué deben revisarse las Trade Policies por separado de los precios?
Las Trade Policies pueden agrupar Catalog, precio, Promotion, Logistics, segmentación y configuración de Payments para estrategias de venta distintas. Un precio puede ser correcto numéricamente y seguir aplicándose en el contexto comercial equivocado.
¿Cómo deben tratarse los datos de sellers de marketplace?
Conserve identidad de seller, responsabilidad de offer, correspondencia de SKU, responsabilidad sobre precio y stock, referencias de Orders y responsabilidad de preparación de pedidos. La información del seller no debe reducirse a un atributo de Product o una nota de texto libre.
¿Conservar Orders históricos demuestra que VTEX Checkout está listo?
No. Los Orders históricos conservan evidencia transaccional. Checkout, Payments, envíos, impuestos, Promotions y preparación de pedidos actuales deben implementarse bajo sus responsables actuales.
¿Por qué los identificadores externos son críticos durante una migración hacia VTEX?
ERP, PIM, WMS, marketplace y sistemas de soporte suelen utilizar sus propios identificadores. Las referencias cruzadas estables evitan creación duplicada, actualizaciones sobre el registro equivocado y reconciliación rota cuando esos sistemas vuelven a conectarse.