Koru Power Seller

App de Social Selling para vendedores de tiendas VTEX — catálogo con links rastreables y banners para compartir, CRM con carritos abandonados y ranking de ventas, con panel de administración propio.

Koru Power Seller (identificada en su propio código como "Power Seller") es una aplicación de Social Selling para vendedores de tiendas VTEX: cada vendedor recibe su propio catálogo con precios y stock reales, genera links rastreables y textos sugeridos para compartir productos por redes sociales o WhatsApp, hace seguimiento de sus ventas y su posición en un ranking, y gestiona una cartera de clientes con los datos protegidos. A diferencia del resto de las apps de Koru, no vive dentro del Admin de VTEX: es una aplicación web propia, mobile-first, alojada aparte (Cloudflare Pages) y multi-tienda — un solo despliegue sirve a todos los retailers que la contratan, cada uno con su propia marca, sus propios vendedores y sus propias credenciales VTEX.

La app está pensada para dos momentos distintos:

• El equipo técnico, la agencia o el dueño de la tienda contrata la app en Koru Suite, entra por primera vez, conecta las credenciales de su propia cuenta VTEX y hace la puesta a punto (marca, vendedores, colecciones, banners).
• El equipo de ventas (vendedores) usa la app día a día desde su celular: comparte productos, sigue sus métricas y atiende a sus clientes.

Antes de empezar

Responsables recomendados

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

Accesos necesarios

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

• Un usuario de Koru Suite con el website de la tienda activado con la app Power Seller.
• Acceso a VTEX Admin de la cuenta, con permisos para generar una App Key propia.
• La URL pública que te haya entregado Red Clover para acceder a la app (hoy, https://app.powerseller.com.ar).
• La URL pública de tu tienda VTEX (el dominio del storefront), para configurar la conexión.

Koru Power Seller no crea un rol de VTEX License Manager: los vendedores son cuentas propias de la app (guardadas en la base de la app, no en VTEX), y el único acceso VTEX que usa la app es el de la App Key que carga el admin.

Identificadores que vas a encontrar

Cómo se contrata y se accede

A diferencia del resto de las apps de Koru, Power Seller no se instala con la VTEX CLI ni vive dentro del Admin de VTEX: es una aplicación separada, con su propia URL, alojada en Cloudflare Pages. El alta de una tienda nueva pasa por tres lugares distintos.

Actualización y desinstalación

Como Power Seller no se instala en tu cuenta VTEX ni en tu workspace, no hay un comando vtex install/vtex uninstall que corra tu equipo: el código se despliega de forma centralizada por Red Clover y un mismo build sirve a todas las tiendas (no hay versión por tienda para actualizar).

• Actualización: no requiere ninguna acción de tu parte. Si un cambio afecta tu configuración de alguna manera, Red Clover te va a avisar por separado.
• Baja de la suscripción: desactivar la app para tu website en Koru Suite corta el acceso (ver "Licencia y seguridad" más abajo): tanto el login de vendedores como el de admin quedan bloqueados con la licencia inactiva, con hasta ~5 minutos de gracia por el cache de la validación.

Activación y primer acceso

Cómo entran los administradores (vía Koru Suite)

El admin no tiene una contraseña propia en Power Seller: inicia sesión con su usuario de Koru Suite, usando el login en dos pasos de la app (ver más abajo). La primera vez que Koru valida ese login, Power Seller le muestra los websites de Koru asociados a esa persona:

• Si tiene exactamente un website y ya está reclamado, entra directo al panel de administración.
• Si tiene cero, varios, o una mezcla de websites reclamados/sin reclamar, aterriza en un selector ("Elegí una tienda") con un botón Entrar (para los ya reclamados) o Configurar (para reclamar uno nuevo) por cada website.

Cómo entran los vendedores

Los vendedores no tienen usuario de Koru: el admin los da de alta (individualmente o por CSV) con un email y una contraseña temporal, que reciben por correo (si el envío de emails está configurado; ver más abajo). En su primer ingreso, la app los obliga a cambiarla antes de continuar.

Login en dos pasos

Todos los roles entran por el mismo formulario, en dos pasos:

Puesta a punto recomendada

Después de conectar VTEX (ver arriba), seguí este orden antes de invitar a tu equipo de ventas:

Configuración completa

Toda la configuración vive fuera de VTEX: en la base de datos propia de Power Seller (Cloudflare D1/KV), scopeada por tienda.

Conexión con VTEX (Admin → Conexión)

Roles que necesita la App Key: Catalog (read) · OMS (ver pedidos) · Master Data v2 (read). La app valida los tres antes de guardar; si alguno falla, te dice cuál (Catalog, OMS o Master Data).

Marca / White Label (Admin → Marca)

Hot Items / Novedades (Admin → Hot Items / Novedades)

Vendedores (Admin → Vendedores)

Alta individual o import CSV (columnas: nombre, nro_vendedor, email, telefono, empresa, sucursal, otros, otros1). Campos obligatorios: nombre, nº de vendedor, email, empresa, sucursal y contraseña (la alta por CSV genera una contraseña temporal automáticamente). Email y nº de vendedor deben ser únicos por tienda; los duplicados se omiten en la importación, no bloquean el resto del lote.

Banners de Social Selling (Admin → Banners)

Si un formato no está cargado, el botón de descarga correspondiente aparece deshabilitado en el modal del vendedor ("el admin todavía no configuró este banner").

Calendario de contenido (Admin → Calendario)

Cada publicación tiene fecha/hora, copy sugerido (máx. 500 caracteres), imágenes (story, post, miniatura) y, opcionalmente, un producto vinculado (buscado por nombre). El vendedor ve las publicaciones agrupadas por semana en su pestaña Novedades.

Cómo funciona cada módulo

Atribución de ventas al vendedor

Cada vendedor tiene un número de vendedor propio. Cuando comparte un producto, el link generado agrega utm_campaign=<nº de vendedor> al link de agregar al carrito de VTEX. Del lado del dashboard, la app consulta OMS filtrando por ese mismo valor, pero usando el parámetro real que exige OMS (f_UtmCampaign; OMS ignora utm_campaign como filtro de búsqueda, aunque sí lo acepta como parámetro de URL para el checkout). Todas las métricas de ventas (dashboard propio, ranking, dashboard consolidado del admin) están acotadas al mes calendario en curso; no hay selector de rango de fechas.

Links rastreables (shortlinks)

Al tocar Compartir en un producto, la app genera un código corto (guardado en Cloudflare KV, TTL de 90 días) que redirige (/r/{code}, 302) al link real de agregar al carrito de VTEX con las UTMs de atribución. Cada clic se cuenta de forma no bloqueante. Si la generación del shortlink falla por cualquier motivo, el modal cae a mostrar directamente el link del producto (sin tracking) en vez de bloquear el compartir.

CRM y datos de clientes

La búsqueda (por nombre, DNI o email, mínimo 2 caracteres) consulta la entidad CL de VTEX Master Data y siempre devuelve los datos enmascarados: el valor real nunca sale del edge hacia el navegador del vendedor. Ejemplos: marcos.garcia@gmail.com → ma***@gmail.com; Marcos García → Marcos G...; documento 33456789 → 33.***.**9. El detalle de un cliente (compras, carrito abandonado) se pide con el id del documento CL, nunca con el email. Si un cliente tiene un carrito abandonado detectado, la app arma un link de WhatsApp (wa.me) con un mensaje sugerido; no usa la API de WhatsApp Business. El historial de compras solo muestra las últimas 3 órdenes facturadas (invoiced) del cliente, no todo su historial.

Catálogo del vendedor

Se muestran únicamente productos con stock disponible mayor a cero, hasta un máximo de 20 productos por sección (Todos/Hot Items/Novedades), con cache de 5 minutos. Un producto con descuento (precio de lista mayor al precio final) muestra el porcentaje de descuento calculado por la propia app, no un campo nativo de VTEX.

Ranking y dashboard

El ranking se calcula por sucursal (campo branch del vendedor); si un vendedor no tiene sucursal cargada, se compara contra un pool global de hasta 60 vendedores activos. El dashboard del vendedor muestra el podio (top 3) y, si el vendedor no está en él, agrega su propia fila aparte con "···" en el medio. El dashboard consolidado del admin muestra el equipo completo ordenado por ventas, con conversión promedio (pedidos ÷ clics) y exporta a CSV.

Pantallas y operación diaria

Licencia y seguridad

Validación de licencia

Cada login y cada request autenticado valida la licencia Koru del website (GET /api/auth/widget?website_id&app_id), con estas reglas:

• Resultado cacheado 5 minutos (fresco) y hasta 1 hora como valor de respaldo.
• Fail-open ante errores transitorios: si Koru no responde o falla la red, la app deja pasar en vez de bloquear, para no tumbar la operación del merchant por un blip de Koru.
• Una licencia explícitamente inactiva (authorized: false) bloquea el login con 403 LICENSE_INACTIVE, con hasta ~5 minutos de gracia por el cache.
• Con una sesión ya abierta, el corte de licencia se ve hoy como "sesión expirada" (401), no como un mensaje explícito de licencia — recién al reintentar el login aparece el motivo real. Es una mejora pendiente conocida del equipo de desarrollo, no un bug a reportar.

Credenciales VTEX

• El admin carga su propia App Key/Token desde Admin → Conexión; nunca se piden por otro canal.
• Se validan contra 3 endpoints privados de VTEX (Catalog, OMS, Master Data) antes de guardarse: si el probe falla, no se persiste nada.
• Se cifran con envelope encryption AES-256-GCM (clave maestra = secreto del proyecto) antes de guardarse en la base de la app. Nunca se guardan ni se muestran en texto plano.
• Son write-only: el panel nunca vuelve a mostrar el valor guardado, ni siquiera parcialmente. Para rotarlas, se pisan con un valor nuevo.

Datos de clientes (CRM)

Toda la PII del CRM (nombre, email, teléfono, documento) se enmascara en el servidor antes de responder al navegador: el vendedor nunca recibe el dato real, solo su versión enmascarada. La pantalla de CRM además muestra una leyenda fija recordando que son datos confidenciales de uso exclusivo para gestión de ventas.

Contraseñas y sesión

• Las contraseñas de vendedor se guardan con PBKDF2-SHA256 (100.000 iteraciones), nunca en texto plano.
• La sesión es un JWT propio (HS256, válido 8 horas), enviado como Bearer y guardado en el navegador del vendedor/admin.
• El admin de Koru no tiene contraseña propia en la app: su identidad se valida contra Koru Suite en cada login, no contra una contraseña guardada acá.

Resolución de problemas

No puedo entrar / "Email o contraseña incorrectos"

1. Si sos vendedor, confirmá con tu admin que tu cuenta esté activa (un vendedor desactivado no puede loguearse, aunque la contraseña sea correcta).
2. Si sos admin, confirmá que estás usando tu usuario de Koru Suite, no una contraseña que hayas usado en otra tienda.
3. Un email que pertenece a un vendedor de varias tiendas puede requerir elegir la tienda en el paso 1 del login.

"La licencia de esta tienda no está activa"

1. Confirmá en Koru Suite que la app Power Seller siga activa para tu website.
2. Esperá unos minutos: el chequeo tiene cache de hasta 1 hora, así que una reactivación reciente puede tardar en reflejarse.
3. Si persiste, informá a soporte el email usado y el nombre de la tienda (sin enviar contraseñas).

"La tienda todavía se está configurando" (vendedor)

Tu tienda quedó reclamada pero el admin todavía no cargó (o no validó) la conexión con VTEX en Admin → Conexión. Ningún vendedor puede loguearse hasta que el admin complete ese paso y la tienda pase a estado activo.

La conexión con VTEX no se guarda / "VTEX rechazó las credenciales"

Revisá, en este orden:

1. Que la Cuenta VTEX sea el accountName real (sin https://, sin espacios).
2. Que la URL de la tienda sea absoluta y use https://.
3. Que la App Key tenga los tres roles exactos: Catalog (read), OMS (ver pedidos), Master Data v2 (read).
4. El detalle de error muestra el resultado por recurso (Catalog/OMS/Master Data): el que diga distinto de "OK" es el rol que falta.

El catálogo, dashboard o CRM devuelven error de conexión

Es el mismo error (VTEX_NOT_CONFIGURED) para los tres: significa que tu tienda todavía no tiene una conexión VTEX válida guardada. Pedile al admin que la complete en Admin → Conexión.

No aparecen productos en Hot Items / Novedades

1. Confirmá que el ID de colección sea correcto (usá Verificar en la propia pantalla de configuración antes de guardar).
2. Confirmá que estés dentro de la vigencia configurada (desde/hasta); fuera de rango, la sección muestra estado vacío a propósito.
3. Recordá que solo se muestran productos con stock mayor a cero: una colección con productos sin stock puede aparecer vacía.

El vendedor no recibió el email de bienvenida o de recuperación

El envío de emails es best-effort: si el proveedor (Resend) no está configurado para tu tienda, el envío se omite sin romper el alta ni el reset. En una alta por CSV, la contraseña temporal se muestra igual en pantalla al admin como respaldo — comunicásela manualmente si el email no llegó. Para un reset, no hay un respaldo visible: hay que reintentar "Olvidé mi contraseña" una vez que el proveedor esté configurado.

"Iniciar sesión con VTEX ID" no funciona

Ese botón está deshabilitado a propósito: es una función planeada, todavía no implementada. Usá el login normal con email y contraseña.

El toggle "Automatizar en mis estados" no hace nada

Es una función planeada para una fase futura, visible en la interfaz pero no operativa todavía. No representa un error.

Límites funcionales

La versión actual:

• No es una VTEX Admin App: vive fuera del Admin de VTEX, en una URL propia y compartida entre todas las tiendas que la contratan.
• No tiene un campo para pegar manualmente el Website ID de Koru: la tienda se identifica automáticamente al loguearse con un usuario de Koru Suite.
• Solo admite una cuenta VTEX por tienda (un tenant = una fila con un único set de credenciales VTEX).
• El catálogo del vendedor muestra máximo 20 productos por sección y solo productos con stock disponible.
• Las métricas de ventas y el ranking están acotados al mes calendario en curso; no hay selector de rango de fechas.
• El historial de compras del CRM muestra solo las últimas 3 órdenes facturadas por cliente.
• Las imágenes (logo, banners, calendario) se suben a Cloudflare KV con un máximo de 5 MB por archivo (PNG, JPG, WEBP, GIF o SVG).
• Los shortlinks tienen un TTL de 90 días; pasado ese plazo, el link deja de resolver.
• No hay purga total ni exportación masiva de datos desde la interfaz.
• El botón "Iniciar sesión con VTEX ID" y el toggle "Automatizar en mis estados" están visibles pero deshabilitados: son funciones planeadas, no disponibles todavía.
• El modelo multi-tienda con host único y auto-gestión (login en dos pasos + selector de tienda) es reciente: al momento de esta guía, solo había sido validado end-to-end con una tienda de prueba interna, no con un cliente real de producción.
• No gestiona usuarios de VTEX License Manager ni reemplaza los roles nativos de VTEX Admin: los vendedores son cuentas propias de la app.

Checklist antes de operar

• Website activado con la app Power Seller en Koru Suite, con el admin asociado.
• Tienda "reclamada" desde el selector de Power Seller (Admin → Conexión accesible).
• App Key de VTEX generada con los roles Catalog (read), OMS (ver pedidos) y Master Data v2 (read).
• Conexión VTEX verificada y guardada (estado "Conexión activa").
• Marca (nombre, color, logo) configurada.
• Al menos un vendedor de prueba cargado y probado de punta a punta.
• Hot Items / Novedades configurados y verificados (o dejados vacíos a propósito).
• Banners de Social Selling subidos.
• Proveedor de email (Resend) configurado, o el equipo sabe que debe comunicar las contraseñas temporales a mano.
• Equipo de ventas al tanto de que "Iniciar sesión con VTEX ID" y "Automatizar en mis estados" todavía no están disponibles.
• Responsable definido para auditar el dashboard consolidado periódicamente.