Koru Financing Options

Muestra en la ficha de producto las cuotas y bancos de tus reglas de pago de VTEX, con logos, CFT/TEA y destacados, sin cargarlas a mano y siempre con los importes reales.

Koru Financing Options es una VTEX Admin App con un bloque de storefront que muestra, en la ficha de producto, las opciones de financiación reales de la tienda: cuántas cuotas, con qué banco y medio de pago, cuánto sale cada cuota, el total del plan y la diferencia contra el precio de contado.

La diferencia con una app de cuotas tradicional es de dónde salen los datos. En lugar de cargar a mano bancos, cuotas, vigencias y recurrencias, la app lee las reglas de pago que ya existen en VTEX y las agrupa en opciones. El operador solo agrega lo que VTEX no tiene: el logo del banco o de la tarjeta, colores, un nombre para mostrar, el orden, cuáles destacar, y los datos regulatorios (CFT, TEA y aclaraciones legales). Los importes que ve el comprador nunca los calcula la app: salen del propio producto en VTEX, así que no pueden contradecir al checkout.

La app tiene dos caras:

• En VTEX Admin, el equipo de ecommerce revisa las opciones que salen de sus reglas de pago, ve cuáles se muestran hoy y por qué, las enriquece, sube logos y suma opciones que VTEX no tiene como regla (por ejemplo Mercado Pago o MODO).
• En la ficha de producto, el bloque financing-block muestra la cuota protagonista, las opciones destacadas, un cuadro comparativo de planes y un popup con el detalle completo, filtrable por banco o tarjeta.

Antes de empezar

Responsables recomendados

Una misma persona puede cubrir varios roles en una tienda chica.

Accesos necesarios

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

• Una sesión válida de VTEX Admin en la cuenta de la tienda.
• Un rol de License Manager con el recurso Gerenciar condições de pagamento (GerenciarCondicoesPagamento) para las personas que van a usar la app. Sin ese recurso, VTEX rechaza la lectura de las reglas de pago y la app lo informa con el nombre del recurso faltante.
• La VTEX CLI oficial instalada y actualizada.
• Permisos para instalar apps en el workspace elegido y para modificar los settings de la app.
• Acceso al repositorio del Store Theme de la tienda, para declarar el bloque.
• El Website ID del ecommerce en Koru Suite y la app Koru Financing Options activa para ese sitio.

Koru Financing Options no crea un rol VTEX propio. El acceso se administra con los controles de acceso disponibles en VTEX License Manager.

Identificadores que vas a encontrar

Instalación con VTEX CLI

La instalación usa la VTEX CLI oficial y tiene dos partes: instalar la app en la cuenta (esta sección) y declarar el bloque en el theme (más abajo). Sin la segunda, el Admin funciona completo pero el comprador no ve nada.

Instalar primero en un workspace de validación

Si la tienda tiene un proceso de QA, instalá y configurá primero en un workspace de desarrollo. Reemplazá los valores entre llaves:

vtex login {store-account}

vtex use {store-account}/{workspace}

vtex whoami

vtex install {vendor}.koru-financing-options@0.x

vtex list

Abrir la app en VTEX Admin

La app aparece en el menú lateral de VTEX Admin, dentro de la sección de configuración de la tienda, como Opciones de Financiación. También podés navegar directamente:

https://{workspace}--{store-account}.myvtex.com/admin/koru-financing-options

Para master, usá el dominio principal de Admin de la cuenta:

https://{store-account}.myvtex.com/admin/koru-financing-options

Si la app no aparece en la navegación, confirmá vtex list, recargá VTEX Admin y verificá que estés mirando la misma cuenta y el mismo workspace donde la instalaste.

Instalar en master

Una vez validado el setup en el workspace correspondiente, seleccioná master, reconfirmá el contexto y repetí la instalación:

vtex use {store-account}/master
vtex whoami
vtex install {vendor}.koru-financing-options@0.x
vtex list

Los settings son por instalación/workspace. Verificá el Website ID en el ambiente definitivo aunque ya lo hayas probado en otro workspace. El enriquecimiento, los logos y las opciones manuales, en cambio, se guardan a nivel de cuenta.

Actualización y desinstalación

Actualizar dentro de la major actual

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

vtex whoami
vtex install {vendor}.koru-financing-options@0.x
vtex list

Después de actualizar, abrí la app, confirmá la licencia y abrí la pestaña Opciones para que se regenere la copia de las reglas que usa la ficha. Luego revisá una ficha de producto real.

Desinstalar

La desinstalación se aplica al workspace actual:

vtex whoami
vtex uninstall {vendor}.koru-financing-options
vtex list

Antes de desinstalar, quitá el bloque y la dependencia del Store Theme: si el theme sigue referenciando financing-block sin la app instalada, la ficha de producto falla con un error de bloque faltante.

Activación y primer acceso

Obtener el Website ID

Antes del primer uso, Red Clover debe activar Koru Financing Options para el website correspondiente en Koru Suite. El Website ID se obtiene desde Koru Suite o se entrega durante la activación.

El Website ID:

• Identifica al ecommerce dentro de Koru Suite.
• No es una contraseña ni un secreto.
• Debe pertenecer a la misma tienda VTEX donde instalaste la app.
• Es el único identificador Koru que el merchant ingresa manualmente.

Conectar la tienda

En el primer acceso, la app muestra Conecta esta tienda con Koru Suite:

La app no solicita un login adicional de Koru. La persona ya está autenticada en VTEX Admin; Koru Suite solamente valida que la combinación Website ID + Koru Financing Options tenga una licencia activa.

Cada pestaña incluye un tour guiado que se abre la primera vez que la visitás y que podés volver a ver con el botón Ver tour.

Puesta a punto recomendada

Seguí este orden para llegar a una ficha de producto correcta sin sorpresas:

Configuración completa

La configuración propia de la instalación es mínima: todo lo operativo (enriquecimiento, logos, opciones manuales) se administra desde las pestañas de la app.

El App ID de Koru viene incorporado en la app y no puede sobrescribirse desde los settings. Nada se aplica hasta guardar; si intentás salir de Configuración con cambios sin guardar, el navegador te avisa.

Cómo arma las opciones

De reglas de pago a opciones

VTEX suele tener muchas reglas de pago casi iguales: la misma promoción de cuotas repetida por nivel de tarjeta (classic, gold, platinum…), por condición comercial o por canal de venta. Para el comprador eso es una sola opción. La app agrupa en una opción todas las reglas que comparten:

• el banco emisor,
• el medio de pago,
• las cuotas con su tasa de interés,
• la vigencia (fecha desde y hasta), y
• la recurrencia (los días de la semana en que aplica).

El nivel de tarjeta, la condición comercial y el canal de venta no separan opciones. Una opción se considera activa si al menos una de sus reglas lo está. El listado se ordena por banco y, dentro de cada banco, de más cuotas a menos.

Visibilidad: ¿se ve hoy en la ficha?

Cada opción muestra un estado, evaluado en este orden:

La ficha de producto vuelve a calcular la visibilidad en cada consulta, así que una opción con recurrencia (por ejemplo, "solo los miércoles") aparece y desaparece sola. Además, una opción ocultada desde Enriquecer no sale en la ficha aunque figure como visible.

Qué opciones aparecen en cada producto

La ficha no muestra todas las opciones a todos los productos. Cruza cada opción con las cuotas que VTEX calcula para ese producto: una opción aparece solo si el producto tiene ese mismo medio de pago, la misma cantidad de cuotas y la misma tasa. Así, un producto que no admite 18 cuotas nunca muestra "18 cuotas sin interés", y los importes son siempre los de VTEX.

Las opciones manuales son la excepción: como no existen en VTEX, no hay cuotas del producto contra las cuales cruzarlas y se muestran siempre, mientras estén activas y vigentes.

Enriquecimiento

Desde la pestaña Opciones, el botón Enriquecer de cada fila abre un formulario con dos secciones.

Datos reutilizables (por banco o medio de pago)

Se comparten con todas las opciones del mismo banco o, si la opción no tiene banco, del mismo medio de pago. Se cargan una vez y valen para todas sus campañas.

Datos de esta opción

Aplican solo a la opción que estás editando.

Cuando una campaña cambia en VTEX: estado «Nueva»

La columna Enriquecimiento muestra si la opción está Enriquecida, Sin enriquecer o Nueva.

Una opción pasa a Nueva cuando la campaña que tenía enriquecida se rearma en VTEX: cambian sus cuotas o tasas, sus fechas, su recurrencia, el banco o el medio de pago. Desde el punto de vista de la app es otra opción, así que:

• Los datos de la opción (CFT, TEA, aclaración, destacado, orden, ocultar) dejan de mostrarse en la ficha. Sería riesgoso exhibir un CFT cargado para una tasa que ya no existe.
• Los datos reutilizables del banco o medio siguen visibles.
• Al abrir Enriquecer, el formulario trae los valores anteriores para que los revises y los confirmes con Guardar.

Cambiar solo el nivel de tarjeta, la condición comercial o el canal de venta no convierte la opción en nueva.

Opciones manuales

Con Crear opción sumás financiación que no existe como regla de pago en VTEX, por ejemplo cuotas de una billetera virtual que se procesa fuera del checkout estándar.

• No puede haber dos opciones manuales del mismo medio con la misma cantidad de cuotas (sin distinguir mayúsculas, tildes ni espacios).
• Una opción manual se enriquece igual que las demás, desde Enriquecer.
• Editar datos y Eliminar están en la columna Acciones. Eliminar no se puede deshacer y borra también su enriquecimiento.
• En la ficha se muestran siempre (no se cruzan con las cuotas del producto), con importe por cuota igual a precio ÷ cuotas cuando son sin interés.

Logos

La pestaña Logos lista cada banco y cada medio de pago que aparece en las reglas de pago de la cuenta, una sola vez cada uno. El logo que subas se usa en todas las opciones donde figure.

• El archivo se valida en el navegador antes de subirlo y de nuevo en el servidor.
• En la ficha, el logo reemplaza a la etiqueta de color. Si una opción tiene logo de banco y de medio de pago, se muestra el del banco.
• Una vez guardado, la ficha lo muestra en hasta 15 minutos (ver Tiempos de actualización).
• Reemplazar sube una versión nueva; los filtros Con logo / Sin logo ayudan a ver qué falta.

Mostrar el bloque en la ficha de producto

La app declara el bloque financing-block, pero quien lo pone en la ficha es el Store Theme de la tienda. Son dos cambios en el repositorio del theme.

"dependencies": {
  "{vendor}.koru-financing-options": "0.x"
}

// store/blocks/product.jsonc
{
  "flex-layout.col#right-col": {
    "children": [
      "product-name",
      "product-price",
      "financing-block",
      "product-quantity",
      "add-to-cart-button"
    ]
  },
 
  "financing-block": {
    "props": {
      "maxHighlights": 3
    }
  }
}

Props del bloque

Todas son opcionales y también se pueden editar desde el Site Editor.

Qué ve el comprador

• Cuota principal: la mejor opción sin interés del producto, en grande, con su importe por cuota y el banco o medio. A igual condición gana la de más cuotas.
• Destacadas: las opciones marcadas como destacadas (o, si no hay ninguna, las que aplican), hasta maxHighlights, cada una con su logo o etiqueta.
• Cuadro comparativo: filas de plan con valor de cuota, total y diferencia contra contado, agrupadas en Sin interés, Más barato que el contado y Con interés, más la fila de "1 pago".
• Popup ("Ver los N planes, con total y CFT"): pestañas Sin interés, Más cuotas y Contado, un filtro por banco o tarjeta, y columnas extra con TEA / CFT y los logos de los medios. Se cierra con Escape, con clic afuera o con el botón.
• Pie legal: CFT/TEA de las opciones con interés a la vista, las aclaraciones legales cargadas y siempre la aclaración de que el plan definitivo se confirma en el checkout.

El bloque está traducido a español, inglés y portugués, según el idioma de la tienda. Mientras carga, reserva su lugar con un esqueleto para no mover la página.

Estilos

La app trae su propio estilo base, así que el bloque se ve bien recién instalado sin escribir CSS. Para adaptarlo a la marca, el theme puede sobrescribir los CSS handles del bloque (container, title, hero, highlight, badge, logo, table, tableRow, modal, legal, entre otros) con el prefijo {vendor}-koru-financing-options-0-x-.

Si algo no se ve bien

Tiempos de actualización

La ficha de producto no consulta VTEX Admin en cada visita. Trabaja con una copia de las opciones y con una caché corta, para no sumar latencia a la página:

• Cambios en la app (enriquecimiento, logos, opciones manuales): se ven en la ficha en 5 a 15 minutos.
• Cambios en las reglas de pago de VTEX (una campaña nueva, un cambio de cuotas o de vigencia): la copia se actualiza cada vez que alguien abre la pestaña Opciones o Logos del Admin. Después de tocar reglas en VTEX, abrí Opciones y usá Actualizar; la ficha lo refleja dentro de los 15 minutos siguientes.
• Visibilidad por fecha y recurrencia: se recalcula en cada consulta, no hace falta abrir el Admin.

Pantallas y operación diaria

La app se organiza en cuatro pestañas dentro de un mismo panel.

Licencia y seguridad

Validación de licencia

Todas las rutas del Admin exigen:

1. Sesión VTEX Admin válida.
2. Licencia Koru activa para el Website ID y el App ID de Koru Financing Options.

La ficha de producto (y los logos que muestra) también dependen de la licencia: si no está activa, el bloque vuelve al modo básico y muestra solo la cuota que calcula VTEX, sin logos, destacados, cuadro, CFT ni opciones manuales. La ficha nunca se rompe por un problema de licencia.

Para tolerar fallas transitorias, una validación positiva se conserva hasta 72 horas si Koru Suite no responde, y 5 minutos ante una respuesta negativa aislada. Pasado ese margen, la app distingue una licencia inactiva (la pantalla lo indica y ofrece revisar la configuración) de una indisponibilidad temporal (pide reintentar, sin necesidad de cambiar nada).

Datos y credenciales

• El navegador nunca llama directamente a las APIs privadas de VTEX ni a Koru Suite: todo pasa por rutas propias de la app.
• La app no solicita ni guarda AppKey/AppToken del merchant. Las reglas de pago se leen con la sesión del admin logueado; por eso hace falta el recurso Gerenciar condições de pagamento en su rol.
• La app solo lee las reglas de pago: nunca las crea, modifica ni elimina.
• El enriquecimiento, las opciones manuales, los logos y la copia de reglas para la ficha se guardan en Master Data de la propia cuenta, en entidades de la app.
• La ruta pública de la ficha expone únicamente lo que se exhibe al comprador: nombres de medios, cuotas, tasas, CFT/TEA, aclaraciones y logos.
• Website ID y App ID identifican recursos, pero no son contraseñas.

Resolución de problemas

La app no aparece después de instalar

1. Ejecutá vtex whoami.
2. Confirmá cuenta y workspace.
3. Ejecutá vtex list y buscá {vendor}.koru-financing-options.
4. Recargá VTEX Admin.
5. Probá la URL directa /admin/koru-financing-options en el mismo dominio/workspace.

La sesión fue rechazada o expiró

Volvé a iniciar sesión en VTEX Admin y recargá la app.

«Tu usuario no tiene permiso para leer las condiciones de pago»

Tu rol de License Manager no incluye el recurso Gerenciar condições de pagamento (GerenciarCondicoesPagamento). Pedile a un administrador de la cuenta que lo agregue a tu rol y volvé a abrir la pestaña.

«Esta cuenta no tiene reglas de pago cargadas en VTEX»

La cuenta no tiene reglas de pago configuradas. Crealas en el módulo de Pagos de VTEX o, si la financiación no pasa por VTEX, usá Crear opción.

Una opción no se ve en la ficha

1. Mirá su columna Visibilidad en Opciones: tiene que decir Se ve.
2. Revisá que no esté marcada como Ocultar esta opción en Enriquecer.
3. Confirmá que ese producto tenga en VTEX ese medio, esa cantidad de cuotas y esa tasa: la opción solo aparece en productos donde VTEX la ofrece.
4. Si la campaña cambió en VTEX, abrí Opciones, usá Actualizar y esperá hasta 15 minutos.

La opción figura como «Nueva» y perdió su CFT

La campaña cambió en VTEX. Abrí Enriquecer, revisá los valores anteriores que trae el formulario y confirmalos con Guardar.

«La opción cambió en VTEX: actualizá el listado y volvé a intentar»

Alguien modificó la regla de pago mientras tenías el listado abierto. Usá Actualizar y volvé a enriquecer la opción.

El logo no se acepta

Revisá formato (PNG o WebP), alto (40 a 56 px, ideal 48 px), ancho (hasta 144 px) y peso (hasta 100 KB). El mensaje de error indica cuál de los requisitos no se cumple.

No puedo crear una opción manual

• Ya existe una opción manual del mismo medio con la misma cantidad de cuotas: editá esa.
• La fecha "hasta" es anterior a "desde".
• La cantidad de cuotas está fuera de 1 a 36.

La licencia figura inactiva

1. Compará el Website ID con el sitio correcto en Koru Suite.
2. Confirmá que Koru Financing Options esté activa para ese website.
3. Verificá que no hayas copiado espacios.
4. Reintentá la validación desde Resumen → Actualizar estado.
5. Si persiste, informá Website ID, cuenta y workspace al soporte, sin enviar credenciales.

Límites funcionales

La versión actual:

• Solo lee reglas de pago de VTEX; no muestra descuentos por medio de pago ni promociones.
• No distingue canal de venta ni condición comercial en la ficha: una opción se muestra si el producto tiene esas cuotas en VTEX.
• Actualiza la copia de reglas que usa la ficha solo cuando alguien abre Opciones o Logos en el Admin; no se sincroniza sola.
• Interpreta las fechas y los días de las opciones manuales en hora de Argentina (UTC−3).
• Admite hasta 5.000 registros por tipo de dato (enriquecimientos, opciones manuales).
• No muestra el importe por cuota de las opciones manuales con interés.
• Opera siempre sobre la cuenta VTEX donde está instalada.

Checklist antes de publicar

• Koru Financing Options instalada en la cuenta y workspace correctos.
• Website ID de la tienda verificado y licencia activa en Resumen.
• Usuarios con el recurso Gerenciar condições de pagamento en su rol.
• Pestaña Opciones abierta al menos una vez en la cuenta.
• Visibilidad de las opciones revisada contra las campañas vigentes.
• Logos cargados para los bancos y medios que se muestran.
• CFT y TEA cargados en todas las opciones con interés.
• Destacadas y opciones ocultas definidas.
• Opciones manuales revisadas (vigencia y cuotas reales).
• Dependencia y bloque financing-block declarados en el theme.
• Fichas reales revisadas en desktop y mobile en un workspace.
• Responsable definido para revisar la app cuando cambien las campañas en VTEX.