Cupones Masivos

Genera y archiva cupones de VTEX en lote desde el Admin, con códigos únicos, reporte por cupón y exportación a CSV.

vtex install soluciones4fpartnerar.cupones-masivos@0.x

Cupones Masivos es una VTEX Admin App que resuelve una limitación del panel nativo de VTEX: no permite generar cupones en lote. La app crea N cupones a partir de un código base —con sufijo aleatorio o numeración secuencial—, los asocia a una utmSource / utmCampaign y permite archivarlos en lote cuando la campaña termina. Cada operación devuelve un reporte por cupón y, en la creación por lote, un CSV con los códigos generados.

A diferencia de las apps de storefront de Koru, acá no se configura nada desde el panel de Koru y no se toca código del sitio. Koru Suite se usa únicamente para habilitar la licencia de la app en la tienda; toda la operación vive dentro del Admin de VTEX.

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 en el workspace elegido.
• Permiso VTEX para operar cupones (módulo de Promociones y Cupones). Si el usuario logueado no lo tiene, cada cupón falla con "Sin permisos para operar cupones en VTEX."
• El Website ID del ecommerce en Koru Suite, con Cupones Masivos activa para ese sitio.

Cupones Masivos no crea un rol VTEX propio y no usa credenciales propias: opera con la identidad del administrador logueado. Los permisos humanos se administran con los controles de acceso de VTEX (License Manager).

Identificadores que vas a encontrar

Instalación con VTEX CLI

La instalación usa la VTEX CLI oficial. No requiere modificar el Store Theme, declarar bloques, pegar un <script> ni cargar nada por Google Tag Manager: la app corre íntegramente en el Admin y en su propio servicio Node.

Instalar primero en un workspace de validación

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

vtex login {store-account}

vtex use {store-account}/{workspace}

vtex whoami

vtex install soluciones4fpartnerar.cupones-masivos@0.x

vtex list

Abrir la app en VTEX Admin

La app se registra en el menú de Configuración de la tienda con el ítem Cupones Masivos. También podés navegar directamente:

https://{workspace}--{store-account}.myvtex.com/admin/app/cupones-masivos

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

https://{store-account}.myvtex.com/admin/app/cupones-masivos

Si esa URL no resuelve en tu cuenta, probá /admin/cupones-masivos: según la versión instalada, la app puede exponer la pantalla en cualquiera de las dos rutas. La vía estable es siempre el ítem del menú del Admin.

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 soluciones4fpartnerar.cupones-masivos@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.

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 soluciones4fpartnerar.cupones-masivos@0.x
vtex list

Después de actualizar, abrí la app y verificá que la licencia siga activa y que el Website ID esté cargado.

Desinstalar

La desinstalación se aplica al workspace actual:

vtex whoami
vtex uninstall soluciones4fpartnerar.cupones-masivos
vtex list

Desinstalar la app no archiva ni elimina los cupones ya creados: siguen existiendo en VTEX y se administran desde el módulo nativo de Promociones y Cupones.

Activación y primer acceso

Obtener el Website ID

Antes del primer uso, Red Clover debe activar Cupones Masivos 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 + Cupones Masivos tenga una licencia activa.

App settings disponibles

koruAppId solo puede cargarse desde los settings nativos de VTEX; la pantalla de conexión de la app escribe únicamente el Website ID.

Verificar la licencia desde el navegador

Con la sesión de Admin abierta, en la misma pestaña y dominio:

GET https://{store-account}.myvtex.com/_v/private/cupones-masivos/health

{
  "ok": true,
  "appId": "soluciones4fpartnerar.cupones-masivos",
  "account": "{store-account}",
  "workspace": "master",
  "checkedAt": "2026-07-30T12:00:00.000Z",
  "license": {
    "configured": true,
    "authorized": true,
    "reason": "koru"
  }
}

Antes de crear el primer lote

En VTEX el descuento vive en la promoción, no en el cupón. El orden correcto es:

Crear cupones

Todo se maneja desde el Admin de VTEX → Configuración de la tienda → Cupones Masivos. La pantalla es única y tiene un selector Operación arriba a la derecha:

Estrategia de código

El campo codeStrategy define cómo se arma cada código: {prefijo}{separador}{sufijo}.

El sufijo aleatorio usa un alfabeto legible sin caracteres ambiguos:

ABCDEFGHJKMNPQRSTUVWXYZ23456789

Se excluyen 0/O y 1/I/L para que el código pueda dictarse por teléfono o transcribirse a mano sin errores.

Debajo de los campos, la app muestra una vista previa en vivo (Ejemplo: RedClo-00001) que se actualiza al cambiar prefijo, separador y longitud.

Parámetros del código

Parámetros del cupón

Se aplican por igual a todos los cupones del lote.

El formulario muestra un aviso permanente: "El cupón solo aplica descuento si existe una promoción en VTEX asociada a esta Fuente y Campaña UTM."

Protección contra sobrescritura

Antes de crear cada cupón, el backend consulta si el código ya existe en VTEX. Si existe, no lo sobrescribe: ese ítem se reporta como error "El cupón ya existe." y el resto del lote continúa.

Es deliberado. El POST de cupones de VTEX es un upsert: sin esta verificación, una campaña nueva podría pisar la configuración de un cupón vigente.

Archivar cupones

El archivado usa el endpoint dedicado de VTEX, un cupón por request. Un código inexistente devuelve "El cupón no existe." para ese ítem, sin abortar el resto.

Resultados y exportación

Después de cada operación aparece un bloque de resultados:

Columnas del CSV: couponCode, utmSource, utmCampaign, maxItemsPerClient, expirationIntervalPerUse.

Una operación de lote nunca falla completa por un cupón individual: cada uno se resuelve por separado y la respuesta agrega los contadores.

Límites de la operación

El límite de 500 está validado en la creación. En el archivado, el backend solo exige al menos un código, pero conviene no pasar de unos cientos por operación: con 60 s de timeout y 8 en paralelo, un lote muy grande se corta por tiempo.

Para más de 500 cupones, ejecutá varias operaciones. Con sequential es directo: subí sequenceStart al siguiente número de la tanda anterior —tanda 1 desde 1, tanda 2 desde 501—. Con random repetí la operación: los códigos se verifican contra la tienda antes de crearse, así que no hay riesgo de colisión silenciosa.

Licencia y seguridad

Validación de licencia

Todas las rutas operativas exigen:

1. Sesión VTEX Admin válida. Sin ella, el backend responde 401.
2. Licencia Koru activa para el Website ID y el App ID de Cupones Masivos.

El backend expone sus rutas bajo /_v/private/cupones-masivos/*. Son privadas: no son consumibles desde el storefront ni desde un cliente externo sin sesión de admin.

Para tolerar fallas transitorias:

• Una autorización positiva se cachea 5 minutos; una revocación explícita, 60 segundos.
• Si Koru Suite no responde por red o error de servidor, una validación positiva previa puede mantener el acceso hasta 72 horas.

Estos tiempos son internos, no se configuran por tienda y no hay purga manual del caché: después de activar la licencia o corregir el Website ID, esperá el TTL y recargá la pantalla.

Datos y credenciales

• La app no solicita ni guarda AppKey/AppToken del merchant: opera con la identidad del administrador logueado.
• No hay secretos Koru en el browser; la validación de licencia se resuelve del lado del servidor.
• Los únicos datos que persiste son los settings koruWebsiteId y koruAppId —ninguno es secreto— y un registro interno de la última validación positiva.
• No guarda datos de clientes ni historial de lotes.
• No inyecta JavaScript, CSS ni bloques en el storefront, y no participa del render de las páginas públicas ni del checkout: no afecta la performance de la tienda.

Resolución de problemas

La app no aparece después de instalar

1. Ejecutá vtex list y buscá soluciones4fpartnerar.cupones-masivos.
2. Ejecutá vtex whoami y confirmá cuenta y workspace. Si la app se linkeó en un workspace de desarrollo, no aparece en master.
3. Recargá VTEX Admin: el menú se cachea del lado del navegador.
4. Entrá por URL directa a /admin/app/cupones-masivos o /admin/cupones-masivos.

La app dice "Licencia Koru no activa"

Koru respondió que esa combinación de website_id + app_id no tiene la app habilitada. Verificá:

1. Que el koruWebsiteId corresponda a este ecommerce. Es el error más frecuente: pegar el Website ID de otra tienda del mismo cliente.
2. Que la app figure activa para ese website en Koru Suite.
3. Que no hayas copiado espacios.
4. Que koruAppId esté vacío, salvo indicación explícita de Koru.

La app dice "No pudimos verificar la licencia"

Es un estado transitorio de disponibilidad, no una prueba de revocación. El backend tolera cortes de red: si hubo una validación positiva en las últimas 72 horas, sigue habilitando la operación. Reintentá en unos instantes.

Activé la licencia y la app sigue bloqueada

La validación se cachea. Esperá el TTL correspondiente —5 minutos para una licencia activa, 60 segundos para una revocada— y recargá la pantalla del Admin. No existe endpoint de purga manual.

Los cupones se crearon pero no descuentan nada

No es un problema de la app. En VTEX el cupón solo activa promociones cuyo scope escucha su utmSource / utmCampaign. Creá en Admin → Promociones una promoción con la condición de Parámetro UTM apuntando a la misma fuente y campaña, en minúsculas.

Un cupón salió con error "El cupón ya existe."

El código ya está en la tienda y la app no sobrescribe cupones existentes por diseño. Cambiá el prefijo, subí el sequenceStart o aumentá la longitud del sufijo aleatorio.

Pedí 100 cupones y se crearon menos, sin errores

Pasa con random y sufijos muy cortos: el espacio de combinaciones se agota. El alfabeto tiene 30 símbolos, así que un sufijo de 1 carácter da como máximo 30 códigos distintos. La app deduplica y crea solo los códigos únicos que logró generar.

Solución: aumentá suffixLength o reducí quantity. Compará siempre la cantidad pedida con el contador Solicitados del resultado.

Varios cupones fallaron con "Límite de velocidad de VTEX alcanzado."

La API de cupones aplicó rate limit y se agotaron los 3 reintentos. Reintentá más tarde con esos códigos o dividí en lotes más chicos.

Todos los cupones fallan con "Sin permisos para operar cupones en VTEX."

El usuario admin logueado no tiene permiso sobre el módulo de Promociones y Cupones. La app opera con su identidad, no con credenciales propias: pedí el rol correspondiente en License Manager y volvé a entrar.

Aparecen identificadores crudos en pantalla

Si ves textos como create.title en lugar de una etiqueta, el catálogo de mensajes del workspace quedó desactualizado. Re-linkeá o reinstalá la app.

Para soporte técnico en producción:

vtex logs soluciones4fpartnerar.cupones-masivos

No compartas tokens, cookies ni información personal innecesaria.

Límites funcionales

La versión actual:

• Crea y archiva cupones; no crea ni edita promociones.
• No lista, busca ni exporta los cupones existentes de la tienda: se opera por código.
• No sobrescribe cupones existentes.
• No guarda historial de lotes generados.
• No deshace un archivado.
• Admite hasta 500 cupones por operación de creación.
• Solo admite letras, números y guion en el código.
• Solo acepta hh:mm:ss en el intervalo de caducidad.
• Es una única pantalla de Admin por cuenta: no admite múltiples instancias.
• Está disponible en español, inglés y portugués, siguiendo el idioma del Admin de VTEX; no tiene setting de idioma propio.

Checklist antes de operar

• Cupones Masivos instalada en la cuenta y workspace correctos.
• Website ID de la tienda verificado y koruAppId vacío.
• Licencia activa visible en el encabezado.
• Usuario admin con permiso sobre Promociones y Cupones.
• Promoción creada en VTEX con la condición de Parámetro UTM.
• utmSource y utmCampaign acordados, sin espacios y en minúsculas.
• Estrategia de código elegida y vista previa revisada.
• quantity dentro del límite de 500 por operación.
• suffixLength suficiente para la cantidad pedida, si usás random.
• Contador Solicitados comparado con la cantidad pedida.
• CSV exportado y resguardado antes de cerrar la pantalla.
• Un cupón del lote probado en el checkout.
• Responsable definido para archivar los cupones al cerrar la campaña.