Koru Catálogo Boost

ABM masivo del catálogo VTEX desde planilla Excel/CSV — categorías, marcas, logos de marca e imágenes de producto, con historial auditable.

//

Koru Catálogo Boost es una VTEX Admin App para hacer altas, bajas y actualizaciones masivas del catálogo desde una planilla Excel o CSV: categorías (con vista previa de la jerarquía), marcas, logos de marca e imágenes de producto — incluyendo visibilidad programada por fecha.

La app está pensada para dos momentos distintos:

• El equipo técnico o la agencia VTEX instala la app, conecta la licencia y define los defaults de categorías nuevas.
• El equipo de catálogo o ecommerce prepara las planillas, sube los archivos, revisa la vista previa antes de aplicar y hace seguimiento en el historial.

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.
• Un rol de License Manager con acceso Catalog - Full access. Sin este acceso, la Catalog API responde 401/403 al crear, actualizar, mover o desactivar cualquier entidad del catálogo.
• La VTEX CLI oficial instalada y actualizada.
• Permisos para instalar apps en el workspace elegido y para modificar los settings de la app.
• El Website ID del ecommerce en Koru Suite y la app Koru Catálogo Boost activa para ese sitio.
• Las planillas de categorías, marcas e imágenes preparadas (podés descargar la plantilla de cada módulo desde la propia app).

Koru Catálogo Boost no crea un rol VTEX propio. El acceso a la Catalog API 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. Es una Admin App nativa: no requiere modificar el Store Theme ni declarar bloques de storefront.

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 {account}.catalogo-boost@1.x

vtex list

Abrir la app en VTEX Admin

Podés abrir Catálogo Boost desde la sección de configuración de la tienda en VTEX Admin (menú lateral) o navegar directamente:

https://{workspace}--{store-account}.myvtex.com/admin/catalogo-boost

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

https://{store-account}.myvtex.com/admin/catalogo-boost

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 {account}.catalogo-boost@1.x
vtex list

Los settings son por instalación/workspace. Verificá el Website ID y los defaults de categorías en el ambiente definitivo aunque ya los 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 {account}.catalogo-boost@1.x
vtex list

Después de actualizar, abrí la app y verificá licencia, defaults de categorías y que el árbol de categorías cargue correctamente. No asumas que una actualización de código reemplaza la validación operativa.

Desinstalar

La desinstalación se aplica al workspace actual:

vtex whoami
vtex uninstall {account}.catalogo-boost
vtex list

Activación y primer acceso

Obtener el Website ID

Antes del primer uso, Red Clover debe activar Koru Catálogo Boost 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. Existe además un campo opcional de App ID de Koru pensado como escape hatch avanzado; en la gran mayoría de los casos no hace falta tocarlo.

Conectar la tienda

En el primer acceso, la app muestra Conectá 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 Catálogo Boost tenga una licencia activa.

Puesta a punto recomendada

Seguí este orden antes de operar con datos reales:

Configuración completa

Toda la configuración vive en los app settings de VTEX (Admin → Apps → Catálogo Boost). No existe otro canal de configuración.

Cómo funciona cada módulo

Categorías

El módulo tiene tres modos, seleccionables con los botones superiores:

Cargar / Actualizar. Subís una planilla (columnas: Categoria ID · Nombre · ID Padre · Title · Description · Keywords · Activa) y la app valida cada fila antes de mostrarte la vista previa:

• El Nombre es obligatorio.
• Si la fila trae ID Padre, ese id debe existir ya en el árbol de VTEX o corresponder a otra fila de la misma planilla que también se vaya a crear.
• Una fila no puede declararse a sí misma como su propio padre (jerarquía circular).
• No puede haber dos filas con el mismo nombre bajo el mismo padre (duplicado en la misma rama).

Las filas con errores se muestran con el motivo exacto y se excluyen; podés aplicar igual las filas válidas. La vista previa arma el árbol resultante combinando el árbol real con las categorías nuevas de la planilla, para que veas la jerarquía final antes de tocar nada en VTEX.

Los campos que VTEX exige y la planilla no trae se completan con categoryDefaults más algunos defaults de código (Title/Keywords toman el Nombre si vienen vacíos, Description queda en blanco). El campo GlobalCategoryId nunca se envía en 0: si no hay un valor válido (mayor a 0) configurado, se omite del todo, porque VTEX rechaza un 0 con el error "Global category not found".

Reubicar. VTEX no permite reparentar una categoría existente: cualquier cambio de FatherCategoryId — al mismo nivel o a otro departamento — es rechazado por la Catalog API con 400 "Cannot move category level". Por eso "reubicar" no mueve la categoría original: arrastrás una categoría hoja (sin subcategorías) sobre su nuevo padre en el árbol y, al confirmar, la app:

1. Crea una copia de la categoría bajo el nuevo padre.
2. (Opcional, tildado por defecto) Migra los productos de la categoría origen a la nueva, reasociando CategoryId y DepartmentId de cada producto.
3. Desactiva la categoría original — pero solo si todos los productos se migraron correctamente. Si algún producto no pudo migrarse, la original queda activa (para no dejar productos huérfanos colgando de una categoría desactivada) y la app te avisa cuántos quedaron pendientes.

Las subcategorías nunca se migran junto con sus productos; por eso el árbol solo permite arrastrar categorías hoja en este modo. Los movimientos quedan "en amarillo" (pendientes) hasta que confirmás, y podés deshacer cada uno antes de aplicar.

Desactivar. VTEX no expone un DELETE de categoría (desaconseja borrar categorías con productos asociados). Seleccioná una o varias categorías en el árbol con checkbox y confirmá: la app desactiva cada una (IsActive=false) preservando el resto de sus campos.

Todas las mutaciones de categorías se procesan en lotes de 10 solicitudes con 600 ms de pausa entre lotes.

Marcas

Sub-tab Datos de marca: subís una planilla (columnas: Brand ID · Nombre · URL Friendly · Activa · Titulo SEO · Descripcion SEO). Se valida:

• El Nombre es obligatorio y debe ser único, tanto contra las marcas existentes como dentro de la misma planilla.
• Si la fila trae URL Friendly, debe ser un slug válido (minúsculas, números y guiones). Si la dejás vacía, la app la autogenera a partir del nombre (sin acentos, en minúsculas, con guiones).

Las marcas nuevas se activan por defecto (Active: true) y el Título SEO (SiteTitle) toma el nombre si viene vacío. El procesamiento va en lotes de 10 con 600 ms de pausa.

Sub-tab Logos: la entidad marca de la Catalog API no tiene campo de imagen y VTEX no ofrece una API REST para subir el logo. El único mecanismo nativo es la sección "Imágenes y archivos" del Admin viejo de VTEX (formulario MarcaForm.aspx, tipo de archivo LogoMarca), que la app replica server-side: descarga ese formulario, reenvía sus campos actuales junto con el archivo, y confirma que VTEX lo aceptó.

Puntos a tener en cuenta:

• El binario no va por planilla: se sube arrastrando o seleccionando imágenes en una zona de dropzone dedicada.
• El matching automático archivo → marca prueba, en orden: nombre de archivo numérico = Brand ID → slug/URL Friendly → nombre de marca normalizado (solo si es único). Los archivos que no matchean quedan marcados como "sin asignar" y podés asignarlos a mano con un selector; no se sube nada hasta que todos los archivos del lote están asignados.
• VTEX solo acepta JPG o GIF para el logo (lo valida por extensión/tipo de archivo, no por el contenido real). La app convierte automáticamente a JPG cualquier PNG/WebP que subas, aplanando la transparencia sobre fondo blanco antes de enviarlo.
• Cada logo implica dos llamadas al formulario legado (una de lectura, una de escritura), así que se procesan en lotes más chicos: 4 por lote, con 800 ms de pausa entre lotes, y el envío desde el navegador va en tandas de 6 para no exceder el límite de tiempo de la ruta.

Imágenes

Subís una planilla (columnas: SKU ID · Nombre Imagen · URL Imagen · Orden · Principal · Reemplazar · Eliminar · Fecha Inicio · Fecha Fin) agrupada internamente por SKU. Cada fila representa una operación:

También podés consultar las imágenes actuales de un SKU (con miniatura) antes de subir cambios, útil para confirmar nombres exactos al reemplazar o eliminar.

Visibilidad programada. La Catalog API de imágenes no tiene fechas de inicio o fin, así que Koru Catálogo Boost la emula: si una fila trae Fecha Inicio y/o Fecha Fin (formato AAAA-MM-DD o DD/MM/AAAA, con hora opcional HH:MM, interpretada en la zona horaria del navegador de quien sube el archivo), esa operación no se aplica al instante: se encola como uno o dos trabajos programados (uno para que la imagen aparezca en la Fecha Inicio, otro para que desaparezca en la Fecha Fin). Las filas sin fechas se aplican de inmediato, como siempre.

Los trabajos programados viven en una cola persistida y un cron horario (corre en punto, cada hora) revisa cuáles ya vencieron y los aplica: associate para que la imagen aparezca, o la búsqueda + borrado por Nombre para que desaparezca. Cada trabajo queda en estado pendiente, aplicado, falló o cancelado; un trabajo ya procesado no se vuelve a tocar aunque el cron corra de nuevo. La pestaña Programadas lista la cola completa y permite cancelar cualquier trabajo todavía pendiente.

Las mutaciones inmediatas de imágenes se procesan en lotes de 8 (más livianos que categorías o marcas, porque cada SKU puede implicar varias llamadas), con 600 ms de pausa entre lotes.

Pantallas y operación diaria

La app se organiza en cuatro tabs dentro de un mismo panel.

Historial y auditoría

Cada operación relevante (carga/actualización de categorías, reubicación, desactivación, alta de marcas, subida de logos, operaciones de imágenes y aplicación de visibilidad programada por el cron) queda registrada en el módulo Historial.

• Guarda las últimas 500 operaciones, la más reciente primero.
• Cada entrada incluye módulo (Categorías/Marcas/Imágenes), tipo de operación, cantidad de éxitos y errores, un detalle legible del resultado, hasta 50 identificadores afectados, y hasta 50 errores reales ({id, error}, no solo el conteo).
• Las acciones manuales registran el email del usuario VTEX que las ejecutó (se obtiene del propio token de sesión del admin, ya validado por authorizeAdmin, sin llamadas adicionales). Las corridas automáticas del cron de visibilidad programada se registran con usuario cron.
• Cuando una reubicación deja productos sin migrar, el detalle indica explícitamente que la categoría original no se desactivó y cuántos productos quedaron pendientes.

Licencia y seguridad

Validación de licencia

Todas las rutas operativas de catálogo exigen, en este orden:

1. Sesión VTEX Admin válida (authorizeAdmin, contra License Manager).
2. Licencia Koru activa para el Website ID y el App ID de Koru Catálogo Boost (authorizeKoruLicense).

La ruta de app settings (bootstrap del gate de Koru) queda fuera del segundo chequeo para permitir que la pantalla de configuración inicial cargue, pero sigue exigiendo sesión de admin válida.

Política de tolerancia a fallas:

• Una licencia revocada explícitamente por Koru Suite bloquea el uso de inmediato (402).
• Sin koruWebsiteId configurado, el bloqueo también es inmediato, con un mensaje que indica dónde cargarlo.
• Ante una caída de red o error del servicio de licencias de Koru, la app no bloquea el uso (una caída de Koru no debe tumbar la operación del merchant); ese resultado no se cachea, así que el siguiente pedido vuelve a intentar la validación real.
• Una autorización positiva se revalida periódicamente en segundo plano; una revocación se reintenta con mayor frecuencia, para que una reactivación en Koru Suite impacte rápido.

Datos y credenciales

• El navegador nunca llama directamente a la Catalog API de VTEX: todas las solicitudes pasan por rutas propias de la app (/_v/private/catalogo-boost/*).
• La identidad usada para operar la Catalog API es la sesión del propio admin logueado (rol "Catalog - Full access" en License Manager); la app no solicita ni guarda AppKey/AppToken del merchant.
• El cron de visibilidad programada usa el token propio de la app, no el de un usuario humano.
• Website ID y App ID identifican recursos, pero no son contraseñas.
• El historial de operaciones y la cola de visibilidad programada se persisten en el almacenamiento interno de la app (VBase), no en Master Data ni en Órdenes.
• Subir el logo de una marca implica que la app llame a una sección del Admin legado de VTEX en nombre del admin logueado; no se envían credenciales adicionales para eso.

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á {account}.catalogo-boost.
4. Recargá VTEX Admin.
5. Probá la URL directa /admin/catalogo-boost en el mismo dominio/workspace.

La sesión fue rechazada o expiró

Volvé a iniciar sesión en VTEX Admin y recargá la app. Las rutas privadas responden 401 cuando falta una sesión admin válida.

No puedo crear, actualizar, mover o desactivar categorías/marcas/imágenes

Confirmá que tu usuario tenga el acceso Catalog - Full access en su rol de License Manager. Sin ese permiso, la Catalog API rechaza la operación aunque la sesión de VTEX Admin sea válida.

"No se pudo mover" / "Cannot move category level"

Es una restricción de VTEX, no un error de la app: la Catalog API rechaza cualquier cambio de padre de una categoría existente. Usá el modo Reubicar en lugar de intentar reparentar directamente: crea una copia en el destino, migra los productos si corresponde, y desactiva la original.

"Global category not found" al crear o actualizar una categoría

La categoría involucrada tiene una Global Category inválida. Asignale una válida desde el Admin de VTEX (Catálogo → Categorías → editar) y reintentá; la app nunca envía un 0 a propósito para evitar justamente este error, pero un valor inválido ya cargado en VTEX puede seguir disparándolo.

La reubicación no desactivó la categoría original

Revisá el resultado detallado: si quedaron productos sin migrar, la app deja la original activa a propósito para no esconder productos huérfanos. Reintentá la migración de esos productos puntuales o migralos manualmente en el Admin antes de desactivar la original a mano.

El logo de marca no se sube / aparece rechazado

• Confirmá que el archivo matcheó a la marca correcta antes de aplicar (revisá el indicador "auto"/"manual" en la vista previa).
• Recordá que VTEX solo acepta JPG o GIF; la app convierte automáticamente otros formatos, pero si el error persiste, probá con un JPG exportado manualmente.
• Si el error menciona un problema de conexión con el backend de VTEX, reintentá: puede tratarse de un problema transitorio del formulario legado que usa VTEX para este mecanismo.

No aparecen imágenes en la vista previa de un SKU

Verificá que el SKU ID sea numérico y exista en el catálogo. Un SKU sin imágenes asociadas muestra explícitamente "sin imágenes", no un error.

Una imagen programada no apareció/desapareció en la fecha esperada

1. Revisá la pestaña Programadas: confirmá el estado del trabajo (pendiente, aplicada, falló, cancelada).
2. Recordá que el cron corre una vez por hora, en punto — no es instantáneo al llegar la fecha configurada.
3. Si el estado es falló, revisá el historial para el detalle del error.
4. Verificá que la licencia Koru estuviera activa en el momento esperado: el cron se salta la corrida (sin marcar el trabajo como fallido) si la licencia no está autorizada en ese momento.

La licencia figura inactiva

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

Para soporte técnico en producción:

vtex logs {account}.catalogo-boost

No compartas tokens, cookies ni datos que no sean necesarios para diagnosticar.

Límites funcionales

La versión actual:

• No borra categorías: la baja es siempre desactivación (IsActive=false).
• No reparenta categorías directamente (restricción de la Catalog API de VTEX); el workaround "Reubicar" implica crear una copia y desactivar la original, no un movimiento in-place.
• El logo de marca se sube únicamente vía dropzone, no por planilla, y VTEX solo acepta JPG/GIF (otros formatos se convierten automáticamente a JPG).
• El "reemplazo" de una imagen no es atómico: primero borra la existente, luego crea la nueva.
• La visibilidad programada de imágenes depende de un cron que corre una vez por hora, no en tiempo real.
• Una reubicación con muchísimos productos a migrar podría exceder el tiempo límite de la ruta; en ese caso, la migración queda incompleta y debe reintentarse.
• El historial conserva las últimas 500 operaciones y la cola de visibilidad programada, hasta 1.000 trabajos.
• Tiene su interfaz en español, independientemente del idioma configurado en la cuenta VTEX (los labels del menú de VTEX Admin sí están traducidos a español/inglés/portugués).
• No integra con VTEX OMS ni Master Data: opera exclusivamente sobre la Catalog API (categorías, marcas, productos e imágenes de SKU).
• Opera siempre sobre la cuenta VTEX donde está instalada; no gestiona el catálogo de otra cuenta desde una misma instalación.

Checklist antes de operar

• Koru Catálogo Boost instalada en la cuenta y workspace correctos.
• Website ID de la tienda verificado.
• Licencia activa confirmada.
• Usuario con acceso Catalog - Full access en su rol de License Manager.
• Defaults de categorías nuevas (categoryDefaults) revisados.
• Plantillas descargadas y planillas de prueba validadas en cada módulo.
• Carga de prueba de categorías validada en la vista previa antes de aplicar en volumen.
• Reubicación de prueba ejecutada y contrastada con el resultado detallado.
• Matching automático de logos revisado antes de subir en lote.
• Visibilidad programada de al menos una imagen probada de punta a punta.
• Historial revisado después de cada operación de prueba.
• Responsable definido para revisar el historial de operaciones periódicamente.