Koru Calculator Widget

Calculadora de producto para la PDP de VTEX. El comprador ingresa una medida y el widget calcula cuántas unidades necesita, valida precio y stock reales, y las agrega al carrito.

El Koru Calculator Widget es una app de VTEX IO que se declara como bloque de theme en la página de producto. Resuelve el caso de los productos que se venden por unidad pero se consumen por medida: pintura que rinde 10 m² por lata, alimento de 20 kg por bolsa, cerco de 10 m por rollo.

El comprador ingresa la medida que necesita (m², metros, kg, m³ o unidades) y el widget calcula redondeo_arriba(medida / rendimiento), lee precio y stock reales del Catalog de VTEX, muestra el total y agrega el ítem al carrito nativo con la cantidad exacta.

Antes de empezar

Responsables recomendados

Una misma persona puede cubrir varios roles en una tienda pequeña.

Accesos necesarios

Antes de instalar, verificá que contás con:

• Una sesión válida de VTEX Admin en la cuenta de la tienda.
• La VTEX CLI oficial instalada y actualizada.
• Permisos para instalar apps y linkear el theme en el workspace elegido.
• Acceso a Catálogo → Especificaciones para crear y asignar los campos de rendimiento y unidad de medida.
• El Website ID del ecommerce en Koru Suite, con el Calculator Widget activo para ese sitio.

La app no pide ni almacena credenciales del merchant: el backend usa el authToken propio de la app para hablar con el Catalog. No hace falta generar AppKey/AppToken.

Credenciales e identificadores

Instalación

Esta app se instala solo como dependencia de un theme de VTEX IO (Store Framework). No existe versión por <script> ni por Google Tag Manager.

vtex login {store-account}
vtex use {workspace} --create
vtex whoami                                  # verificá cuenta y workspace antes de seguir
vtex install soluciones4fpartnerar.calculator-widget@0.x
vtex list                                    # confirmá que aparece en la lista

{
  "dependencies": {
    "soluciones4fpartnerar.calculator-widget": "0.x"
  }
}

{
  "flex-layout.col#details-column": {
    "children": [
      "vtex.store-components:product-name",
      "flex-layout.row#product-prices",
      "calculator-widget",
      "flex-basic#buy-button"
    ]
  },
 
  "calculator-widget": {
    "props": {
      "title": "Calculá cuánto necesitás",
      "ctaText": "Agregar al carrito",
      "websiteId": "TU-WEBSITE-ID"
    }
  }
}

Múltiples instancias en la misma tienda

El bloque admite el patrón estándar de VTEX de instancias con #id, por ejemplo para una variante en otro punto de la PDP:

{
  "calculator-widget#compacta": {
    "props": {
      "title": "Calculadora rápida",
      "websiteId": "TU-WEBSITE-ID",
      "blockClass": "compacta"
    }
  }
}

• Cada instancia necesita su propio websiteId: el prop no se hereda entre instancias.
• El bloque no fija una posición propia — se renderiza donde lo pongas en el árbol de bloques. Como necesita contexto de producto, todas las instancias tienen que vivir dentro de la PDP.

Personalización visual por CSS

Los estilos por defecto salen de Tachyons con los design tokens de VTEX (t-heading-5, c-on-base, bg-action-primary, b--muted-4), así que el widget hereda automáticamente colores, tipografía y estilo de botón del styles de la cuenta. Los .css de la app no hardcodean colores.

Cada elemento lleva además su CSS handle. El archivo de override en el theme es:

styles/css/soluciones4fpartnerar.calculator-widget.css

.cta {
  border-radius: 0;
  text-transform: uppercase;
}
 
.stockAlert {
  font-weight: 600;
}

Handles disponibles:

Actualizar y desinstalar

Seleccioná la cuenta/workspace correcto, confirmalo y volvé a instalar el rango:

vtex whoami
vtex install soluciones4fpartnerar.calculator-widget@0.x
vtex list

La desinstalación se aplica al workspace actual:

vtex uninstall soluciones4fpartnerar.calculator-widget

El websiteId vive en la configuración del bloque del theme, no en app settings: si desinstalás y reinstalás la app, el prop sigue en el theme.

Activación en Koru Suite

La app está gateada. Si el website + la app no están activos en Koru, en lugar de la calculadora se muestra el cartel "Widget no disponible — Esta aplicación no está habilitada para este sitio. Comuníquese con Korusuite."

El gate corre client-side desde el navegador del comprador. No hay login de Koru ni sesión de VTEX Admin involucrada: lo único que se valida es que el par Website ID + App ID esté autorizado.

Configuración

La configuración se reparte en tres lugares, y ninguno es el panel de Koru:

1. Props del bloque — títulos y licencia.
2. Especificaciones del catálogo de VTEX — qué fórmula usa cada producto y cuánto rinde. Es acá donde vive la lógica.
3. CSS del theme — apariencia (ver Instalación).

Props del bloque

Especificaciones del catálogo

Creá dos campos de especificación en VTEX Admin (Catálogo → Especificaciones, o desde el grupo de especificaciones de la categoría) y asignalos a las categorías donde va el widget. La app los busca por nombre exacto, probando los candidatos en orden:

Reglas a tener en cuenta:

• El nombre del campo es lo que importa, no el grupo de especificaciones.
• El rendimiento tiene que ser un número mayor que 0. Vacío, 0 o no numérico se ignora y sigue la cascada.
• La unidad se lee del producto, no del SKU, y se usa para dos cosas: elegir la fórmula y mostrar Rendimiento X <unidad> c/u en el resumen.

Unidad de medida → fórmula que se activa

El valor de UnidadMedida define qué fórmula usa el widget y qué campos le pide al comprador:

perimetro no está mapeada a ninguna unidad. Como el bloque no permite fijar una fórmula, la única forma de ofrecerla es dejar el producto con unidad vacía o no reconocida: ahí se listan las 7 y el comprador elige.

Alias aceptados (se normalizan mayúsculas, espacios, acentos y puntos):

Cualquier otro valor cuenta como "no reconocido" y se ofrecen las 7 fórmulas. Recomendación: cargar siempre la forma corta (kg, m2, m, m3, un).

Fórmulas disponibles

Las fórmulas no son editables desde ningún panel: viven en el código de la app. Agregar o modificar una requiere publicar una versión nueva. El cliente nunca envía la expresión: manda un formulaId que el backend valida contra el whitelist, y la evaluación corre en modo restringido (sin eval, sin new Function, sin definición de funciones ni asignaciones).

Cómo calcula

Cascada del rendimiento

El rendimiento se resuelve server-side, tomando el primer valor válido (mayor que 0) de esta secuencia:

Cálculo final

bruto          = expresión(inputs del comprador)
cantidad_final = max(0, ceil(bruto / rendimiento))
precio_total   = precio_unitario * cantidad_final
alerta_stock   = cantidad_final > stock_disponible

precio_unitario y stock_disponible salen del search público del Catalog (Price y AvailableQuantity del primer seller del SKU). Si el SKU no tiene oferta, ambos vuelven en 0.

Endpoint del backend

El bloque llama a este endpoint con debounce de 300 ms cada vez que cambian los inputs, el SKU seleccionado o la fórmula elegida, y cancela el request anterior. No recalcula nada en el cliente: solo pinta la respuesta.

Qué pasa al agregar al carrito

Puesta a punto recomendada

Datos y privacidad

• La app no tiene storage propio: ni Master Data, ni VBase.
• Lo único que persiste es el customData del OrderForm con los valores que ingresó el comprador, para trazabilidad del pedido.
• En el navegador se guarda el cache de licencia en localStorage, con la clave koru_widget_<WEBSITE_ID>_<APP_ID>, por 300 segundos.
• No se piden ni guardan credenciales del merchant. No hay secretos de Koru en el browser.
• El endpoint de cálculo responde con no-store y no registra datos personales: recibe medidas, no identidad del comprador.

Límites funcionales

La versión actual:

• Requiere contexto de producto: solo funciona dentro de la PDP.
• No permite fijar la fórmula ni el rendimiento desde el bloque o el Site Editor.
• No permite crear ni editar fórmulas sin publicar una versión nueva de la app.
• Agrega el ítem con un único seller: no está pensada para tiendas con múltiples sellers o marketplace.
• Lee precio y stock del sales channel que resuelve el search público. En tiendas con varios sales channels o precios por trade policy, el precio mostrado puede no ser el de la política del comprador.
• Muestra la alerta de stock como advertencia visual, sin bloquear la compra.
• Los textos internos del widget están en español y no son traducibles desde el theme.
• No existe versión por <script> ni por Google Tag Manager.

Resolución de problemas

Activaron la app en Koru y sigue el cartel "Comuníquese con Korusuite"

Las respuestas negativas no se cachean, así que una activación en Koru se refleja en el siguiente page load. Lo que sí se cachea es la respuesta positiva, por 300 segundos (5 min), en localStorage con la clave koru_widget_<WEBSITE_ID>_<APP_ID>. Para forzar: borrá esa clave del localStorage o esperá 5 minutos.

Si el cartel persiste, revisá que el websiteId del bloque sea exactamente el del panel de Koru (sin espacios) y que la app esté habilitada para ese website.

El widget no aparece en absoluto — ni la calculadora ni el cartel de error

En este orden:

1. Contexto de producto: el bloque tiene que estar dentro de store.product. Sin SKU en el product-context el componente no renderiza nada.
2. Dependencia del theme: la app en el manifest.json del theme, y vtex link reiniciado después de agregarla.
3. Nombre del bloque: calculator-widget, o soluciones4fpartnerar.calculator-widget:calculator-widget si el theme usa prefijos completos.
4. Logs del backend:

vtex logs soluciones4fpartnerar.calculator-widget

Cambié UnidadMedida o el rendimiento y el widget no se enteró

UnidadMedida y el rendimiento a nivel producto viajan al storefront por el índice de búsqueda: el cambio no es instantáneo, hay que esperar el reindex del Catalog y hacer hard refresh de la PDP. Podés verificar el valor vigente en:

https://{account}.vtexcommercestable.com.br/api/catalog_system/pub/products/search/?fq=productId:{id}

El rendimiento cargado a nivel SKU se lee por el Catalog privado y se toma al instante.

Me pide campos que no corresponden al producto

Por ejemplo, ancho y alto en un producto que se vende por kg: UnidadMedida está vacía, mal escrita o con un valor fuera de los alias aceptados. Cargá kg, m2, m, m3 o un.

Aparece un selector con 7 fórmulas

Es el comportamiento esperado cuando la unidad no se reconoce. Cargá una unidad válida si querés que el widget elija sola. Al revés: si necesitás ofrecer perimetro, esa es la única vía.

La cantidad calculada es igual a la medida ingresada

Como si el producto rindiera 1: falta la spec de rendimiento, o su valor es 0, no numérico, o tiene coma en lugar de punto. Cargá ValorRendimiento mayor que 0 en el producto o en el SKU.

El rendimiento no cambia al cambiar de variación

Está cargado a nivel producto. Para que varíe por variación, cargalo a nivel SKU: el widget reenvía el skuId seleccionado y recalcula solo.

Precio total en 0 y stock 0

El SKU no tiene oferta/precio en el sales channel que devuelve el search público. Revisá precio y disponibilidad del SKU. Como efecto colateral, con stock 0 la alerta de stock aparece siempre.

Dice "Stock insuficiente" pero igual deja agregar al carrito

Es intencional: la alerta de stock es una advertencia visual. El botón solo se deshabilita si la cantidad calculada es 0 o mientras está agregando el ítem.

El comprador deja un campo vacío o pone texto

Mientras falte algún campo de la fórmula, no se llama al backend y no hay resultado. Los valores no numéricos se descartan en el servidor; si eso deja una variable de la fórmula sin valor, el widget muestra "No se pudo calcular. Revisá los valores e intentá de nuevo.".

Los inputs son numéricos con min=0, pero el backend no rechaza negativos: acepta cualquier número finito y después acota la cantidad final con max(0, …).

¿Afecta la performance del sitio?

El widget es 100% client-side en su carga: no bloquea el render de la PDP, pero hace dos tipos de request desde el navegador.

1. El gate de licencia: un fetch a korusuite.com por page load, salvo que haya cache válido de 5 minutos. Mientras responde, en el lugar del widget se ve "Verificando disponibilidad…".
2. El cálculo: un POST same-origin al backend de la app por cada cambio de input, con debounce de 300 ms y cancelación del request anterior, respondido con no-store (no cacheable por diseño, porque devuelve precio y stock reales).

¿Depende de otras apps?

El bloque depende de vtex.product-context, vtex.order-items, vtex.order-manager, vtex.css-handles, vtex.render-runtime, vtex.format-currency y vtex.pixel-manager, más vtex.store@2.x como peer dependency. La moneda del resumen la resuelve vtex.format-currency con la configuración del store.

Checklist antes de publicar

• App instalada en la cuenta y workspace correctos.
• Dependencia declarada en el theme y vtex link reiniciado.
• Bloque declarado dentro de la PDP, con contexto de producto.
• Website ID cargado y licencia confirmada en la PDP.
• Especificaciones ValorRendimiento y UnidadMedida creadas y asignadas a las categorías del widget.
• Rendimiento mayor que 0 en el producto o en el SKU.
• Unidad de medida cargada en forma corta y reconocida.
• Rendimiento a nivel SKU cuando varía por variación.
• Cantidad, precio y stock validados contra el catálogo en un producto piloto.
• Alta al carrito y minicart probados end to end.
• Registro de customData en el checkout coordinado, si se necesita trazabilidad.
• CSS de override revisado en desktop y mobile.