Errores de arquitectura que encarecen un VTEX

Después de más de 15 años trabajando dentro de agencias en tiendas VTEX de retail grande, tengo una conclusión bastante firme: la plata no se va en la licencia ni en el desarrollo inicial. Se va en rehacer.

Las decisiones que se toman en las primeras semanas, casi siempre con apuro por salir a producción, son las que después cuestan meses de trabajo. No hablo de bugs, que se arreglan y listo. Hablo de decisiones estructurales que, una vez que la tienda vende, son carísimas de dar vuelta.

Vamos por las que más vi repetirse.

Modelar el catálogo como está en el ERP

El error clásico es copiar la estructura del ERP tal cual. Cada variante de color termina siendo un producto separado, o al revés, se agrupan como SKUs cosas que para el cliente son productos distintos. Las especificaciones van como texto libre en la descripción y las categorías se usan como filtros.

El resultado: filtros pobres, búsqueda que no encuentra, páginas de producto casi duplicadas que compiten entre sí en Google. Y corregirlo con la tienda andando implica migrar URLs, armar redirects, recargar imágenes y reentrenar al equipo que carga catálogo.

Cómo evitarlo:

• Hacer un workshop de catálogo antes de escribir una línea de código.
• Definir qué es producto y qué es SKU desde la mirada del cliente, no del depósito.
• Separar bien especificaciones de producto y de SKU, con campos tipados y no texto libre.
• Diseñar el árbol de categorías pensando en navegación y SEO.

El ERP no tiene por qué cambiar. Para eso está la capa de integración, que traduce un modelo al otro.

Parchar el checkout en vez de extenderlo

El checkout es donde se gana la plata, y también donde más hacks vi. Scripts que manipulan el DOM, listeners que esperan que aparezca un elemento para moverlo, campos ocultos con CSS, validaciones que solo existen en el navegador.

Todo eso funciona hasta que VTEX actualiza algo, se suma un medio de pago nuevo o cambia el flujo de envío. A partir de ahí, cada cambio de negocio en el checkout implica un testeo manual completo y cruzar los dedos.

Lo sano es trabajar sobre la API del orderForm, guardar datos extra en campos custom (customData y app fields) y validar del lado del servidor lo que importa de verdad. La capa visual se toca lo mínimo indispensable.

También conviene cuestionar el requerimiento. Muchos pedidos de customización del checkout son estéticos y no mueven la conversión. Cada línea de JavaScript custom ahí es deuda con una tasa de interés muy alta.

Usar Master Data para todo

Master Data es útil y está ahí, a mano, sin infraestructura adicional. Por eso termina siendo la base de datos de todo: logs de integración, carritos guardados, tablas enormes de configuración, historiales que nadie consulta.

Tiene límites de rate y de búsqueda, y v1 y v2 se comportan distinto. Vi entidades sin índices recorridas completas en cada sincronización, y peor: frontends consultando Master Data directo con credenciales expuestas en el navegador. Eso no es solo un problema de performance, es un problema de seguridad.

Mi criterio:

• Datos de cliente y extensiones livianas del modelo, sí.
• Volumen alto o lógica pesada, a un servicio propio o a una app de VTEX IO con cache.
• Si usás v2, esquemas e índices definidos desde el primer día.
• Nunca una appKey en el front. Si el navegador necesita un dato, pasa por un resolver GraphQL o un backend propio.

Integrar el ERP punto a punto

El ERP le pega directo a las APIs de VTEX y VTEX le pega directo al ERP. Sincronizaciones full de stock y precio cada pocos minutos, sin colas, sin reintentos, sin idempotencia. Anda bien en un martes cualquiera.

El problema aparece en Hot Sale o CyberMonday. El ERP se satura, los pedidos se pierden o entran duplicados, el stock queda desfasado y se vende lo que no hay. Después viene una semana de cancelaciones, reclamos y conciliación a mano.

Una integración que aguante tiene, como mínimo:

• Una capa intermedia con colas entre VTEX y el ERP.
• Cambios incrementales de stock y precio, no cargas completas.
• Órdenes consumidas por feed o hook, con confirmación explícita de procesamiento.
• Idempotencia por orderId, para que un reintento no genere un pedido duplicado en el ERP.
• Respeto de los rate limits con reintentos escalonados.
• Monitoreo, alertas y una reconciliación diaria que detecte diferencias antes que el cliente.

Esto cuesta más al principio. Mucho menos que un evento de ventas mal resuelto.

Resolver precios con promociones

Este lo vi en casi todas las cuentas grandes. El equipo comercial necesita precios distintos por canal, por región o para mayoristas, y la forma más rápida es cargar una promoción. Después otra. Después cientos.

Con muchas promociones activas, cada simulación del carrito tiene que evaluarlas todas y el checkout se vuelve lento. Aparecen conflictos de acumulación y nadie sabe explicar por qué un producto muestra ese precio. En Argentina se suma la capa de cuotas y promociones bancarias por BIN, que tiende a multiplicar reglas.

Lo ordenado es:

• Precios base y diferenciales en tablas de precio y políticas comerciales.
• Promociones solo para lo que es promocional, siempre con fecha de vencimiento.
• Cuotas e intereses configurados en las condiciones de pago, no simulados con descuentos.
• Una limpieza periódica de promociones vencidas o huérfanas.
• Un dueño claro del modelo comercial, que no sea el que tiene más apuro.

Decidir el multi tienda demasiado tarde

Se arranca con una sola política comercial y un solo almacén porque por ahora vendemos así. Al año aparece el canal B2B, el marketplace, el retiro en sucursal o las franquicias.

Ahí hay que rediseñar logística (almacenes, docks, puntos de retiro), canales de venta, a veces la estructura de cuentas, y todas las integraciones que dependían de que hubiera una sola de cada cosa.

No digo construir todo desde el día uno. Digo preguntarle al negocio qué piensa hacer en los próximos dos o tres años y diseñar dejando la puerta abierta. Esa conversación lleva una reunión y ahorra meses.

Forkear apps y deployar sin estrategia

Forkear una app nativa para cambiar un detalle parece rápido. En la práctica queda congelada, te perdés los fixes y mejoras que VTEX va sacando, y nadie se anima a actualizarla porque ya no se sabe qué se tocó.

Lo mismo con los deploys: directo a master, sin workspaces de producción para validar, con rangos de dependencias amplios. Vi un cambio chico en el tema romper el header de una tienda en plena campaña, porque una dependencia se actualizó sola.

Lo que funciona:

• Extender antes que forkear: blocks, slots, CSS handles, apps propias que componen las nativas.
• Workspaces de producción para validar con tráfico real antes de promover.
• Versionado semántico serio y dependencias acotadas.
• Releases chicos y frecuentes, con rollback probado.
• Congelamiento de deploys alrededor de las fechas críticas.

Dejar la performance para el final

La performance no es una etapa, es una restricción de diseño. Si se deja para el final, te encontrás con un Tag Manager cargado de scripts de terceros, apps que bloquean el render, banners sin dimensiones y una home que pesa lo que un video.

Arreglarlo después significa negociar con marketing qué tag se saca, rediseñar componentes y pelear con el CLS en cada plantilla. Definir un presupuesto de performance desde el diseño, y medirlo en cada release, sale muchísimo más barato.

El patrón detrás de todos

Si mirás la lista, el problema casi nunca es técnico. Es apuro combinado con que nadie tiene el rol, y la autoridad, de frenar una decisión que va a salir cara.

Un arquitecto metido desde el discovery no es un lujo. Es la persona que pregunta qué pasa en el próximo evento de ventas, cuando se sume otro canal o cuando VTEX actualice algo. Esas preguntas, hechas a tiempo, son las que hacen que la implementación cueste lo que se presupuestó.

Si sos de una agencia y necesitás un arquitecto o dev VTEX senior para un proyecto, o si estás del lado de la marca y querés una segunda opinión sobre tu implementación, escribime y lo charlamos.