Koru Recovery

Detecta órdenes con pago pendiente en VTEX, agrupa intentos relacionados y organiza el recupero manual con trazabilidad.

Koru Recovery es una VTEX Admin App para equipos que recuperan compras cuyo pago quedó pendiente. Consulta VTEX OMS, aplica las reglas configuradas por la tienda, agrupa intentos relacionados y crea casos operativos para contactar al cliente de forma manual.

La app está pensada para dos momentos distintos:

• El equipo técnico o la agencia VTEX instala la app, conecta la licencia y realiza la puesta a punto.
• El equipo de ecommerce u operaciones revisa casos, copia el mensaje, contacta al cliente por un canal externo y sigue el resultado en 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 para modificar los settings de la app. Si no lo tenés, el guardado devuelve un error de permisos y debe intervenir un administrador de la cuenta.
• El Website ID del ecommerce en Koru Suite y la app Koru Recovery activa para ese sitio.
• Los datos de transferencia que la tienda quiere incluir en el mensaje.
• Acceso operativo a OMS para comprobar órdenes y reflejar pagos mediante el proceso habitual de la tienda.

Koru Recovery no crea un rol VTEX propio. La visibilidad de la app y los permisos humanos se administran con los controles de acceso disponibles en VTEX.

Identificadores que vas a encontrar

Instalación con VTEX CLI

La instalación usa la VTEX CLI oficial. No requiere modificar el Store Theme ni declarar bloques.

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}.koru-recovery@0.x

vtex list

Abrir la app en VTEX Admin

Podés abrir Koru Recovery desde la sección de configuración de la tienda en VTEX Admin o navegar directamente:

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

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

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

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}.koru-recovery@0.x
vtex list

Los settings son por instalación/workspace. Verificá el Website ID y la configuración operativa 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}.koru-recovery@0.x
vtex list

Después de actualizar, abrí la app y verificá licencia, settings, última sincronización y estado de automatización. 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}.koru-recovery
vtex list

Activación y primer acceso

Obtener el Website ID

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

Puesta a punto recomendada

Después de conectar la licencia, seguí este orden para evitar casos que todavía no pueden contactarse:

Configuración completa

La pestaña Configuración guarda reglas por tienda en los app settings de VTEX. Los cambios sin guardar no afectan la detección ni los mensajes.

General

El locale debe usar un código de idioma de dos o tres letras y, opcionalmente, región de dos letras o código numérico. Si queda vacío, la app usa el locale disponible en el entorno.

Reglas operativas

Usar tolerancias altas aumenta las coincidencias: puede reunir compras diferentes o marcar más posibles recompras. Empezá con los defaults y ajustá usando casos reales.

Actualización automática

VTEX Scheduler invoca un heartbeat técnico cada 15 minutos. El backend compara el último intento/éxito con syncIntervalMinutes y decide si corresponde sincronizar. Por eso una frecuencia de 60 minutos no crea un cron separado de 60 minutos.

El rango consultado en cada actualización es:

ahora - (expireAfterHours + syncLookbackMarginHours)  →  ahora

La acción Actualizar ahora ignora la espera funcional, usa el mismo motor idempotente y también intenta reparar el registro del scheduler.

Datos de transferencia

La lista se guarda en la clave paymentFields. Cada fila contiene:

Agregar campos sugeridos crea Titular, CUIT/RUT, Alias y CBU/CVU. Son solamente etiquetas: debés completar los valores reales de la tienda.

No ingreses credenciales bancarias, claves, tokens ni datos que no deban enviarse al cliente. Estos campos están pensados para instrucciones públicas de transferencia.

Métodos de pago elegibles

La selección se guarda en eligiblePaymentMethods. La app descubre los métodos presentes en las órdenes consultadas. Antes de la primera sincronización, la lista puede estar vacía.

Para cada método se muestra:

• Su nombre visible informado por OMS.
• La clave normalizada usada por el motor.
• Una marca cuando coincide con el default recomendado.
• Un selector para incluirlo o excluirlo del recupero.

Defaults habilitados por equivalencia normalizada:

• Tarjeta de crédito.
• Tarjeta de débito.
• Wallet o billetera digital.
• Instant payment y Pix.

Defaults deshabilitados:

• Boleto o bank invoice.
• Transferencia ya seleccionada.
• Efectivo, contraentrega o cash on delivery.
• Promissory o manual.
• Gift card, voucher, puntos o store credit.
• Métodos offline, custom o desconocidos.

La comparación no depende de mayúsculas, acentos o separadores. Usa tanto el nombre como el grupo del medio de pago informado por OMS.

Mensaje para el cliente

El texto se guarda en messageTemplate. La plantilla default en español es:

Hola {{customer.firstName}}, vimos que tu compra {{order.id}} por {{order.amount}} quedó pendiente de pago.
 
Para finalizarla, podés transferir usando estos datos:
{{payment.fields}}
 
Cuando realices la transferencia, avísanos para que podamos continuar con la preparación de tu pedido.
{{store.name}}

La plantilla acepta variables simples; no ejecuta Handlebars, condicionales ni código.

Una variable desconocida o sin valor se reemplaza por vacío y se informa como faltante. Mientras exista una variable faltante, la UI bloquea copiar y marcar el mensaje.

Cómo se crean los casos

Fuente de órdenes

Koru Recovery consulta VTEX OMS con el estado:

payment-pending

El filtro visual Incompleto de VTEX no es equivalente. Una orden incompleta sin estado payment-pending no entra al recupero.

Para cada candidata, el backend consulta el detalle cuando está disponible y obtiene:

• Order ID y order group.
• Transaction IDs.
• Estado OMS.
• Fecha de creación.
• Documento, email, teléfono, ID y nombre del cliente.
• Monto y moneda.
• Nombre y grupo del método de pago.

Elegibilidad

Una orden se convierte en candidata accionable solamente cuando:

1. Está dentro del rango histórico consultado.
2. OMS la informa como payment-pending.
3. Cumplió minOrderAgeMinutes.
4. Tiene al menos un método de pago elegible.
5. Se puede resolver una identidad de cliente o, como fallback, un orderGroup.
6. No existe una recompra exacta pagada que cierre el caso.

Las órdenes demasiado recientes y los métodos no elegibles se contabilizan en el resultado técnico de la sincronización, pero no crean un caso accionable.

Koru Recovery es independiente del gateway. No procesa ni almacena credenciales de tarjeta y no llama al proveedor de pagos. Cualquier método configurado como elegible sigue el mismo flujo de recupero cuando VTEX OMS expone la orden como payment-pending.

Identidad y agrupación

La identidad se resuelve en este orden:

1. Documento.
2. Email.
3. Teléfono.
4. ID de cliente.
5. orderGroup, solamente como fallback de agrupación.

Se agrupan intentos cuando tienen la misma identidad, la misma moneda, un monto dentro de la tolerancia y ocurren dentro de la ventana móvil configurada, medida desde el primer intento del grupo. La ventana no usa buckets fijos del reloj y los intentos posteriores no la extienden transitivamente.

El caso conserva todas las órdenes, transaction IDs y order groups relacionados. La orden principal es la más reciente del grupo.

Montos y monedas

Los montos de OMS se normalizan como unidades menores antes de comparar. La moneda se resuelve usando, en orden:

1. currencyCode de OMS.
2. Preferencias de la orden.
3. Fallback disponible en el contexto.

Órdenes con monedas diferentes nunca se agrupan ni se comparan como recompra. La app admite códigos de moneda válidos entregados por VTEX OMS y formatea cada monto en su propia moneda, sin conversión cambiaria. Si no puede resolver monto y moneda de manera confiable, no genera un mensaje ambiguo.

Recompra exacta y posible recompra

La prevención de contactos duplicados tiene dos niveles:

Ante una posible recompra, abrí las órdenes vinculadas en OMS y verificá que el cliente no haya completado otra compra. Si corresponde continuar, usá Continuar igual. La confirmación queda auditada y no elimina el indicador histórico.

Estados y ciclo de vida

Estados del caso

Transiciones automáticas

• Una sincronización crea o actualiza casos pendiente.
• Si una orden relacionada entra en una etapa paga de OMS, un caso abierto pasa a cerrada-pagada.
• Si todas las órdenes agrupadas están canceladas, un caso abierto pasa a descartada con motivo oms-cancelled.
• Si una sola orden del grupo está cancelada pero otra sigue abierta, el caso no se descarta automáticamente.
• Al alcanzar el timestamp de expiración, un caso abierto pasa a expirada.

Etapas OMS interpretadas como pagas:

window-to-cancel
payment-approved
ready-for-handling
authorize-fulfillment
release-to-fulfillment
handling
waiting-for-fulfillment
ready-for-invoicing
invoice
invoiced

Transiciones manuales

• pendiente → mensaje-enviado: Marcar enviado.
• pendiente o mensaje-enviado → descartada: Descartar caso.
• Un re-chequeo puede cerrar como pagado un caso cuando OMS ya refleja el pago.
• Una nota o una copia de mensaje no cambia el estado.
• Un caso descartado no vuelve automáticamente a pendiente.

Operación diaria

Flujo operativo recomendado

Métricas

El resumen cuenta casos, no órdenes:

• Pendientes.
• Mensajes enviados.
• Cerradas pagadas.
• Descartadas.
• Expiradas.
• Posibles recompras abiertas y todavía no confirmadas.

Un caso con varias órdenes agrupadas suma una sola unidad.

Búsqueda y filtros

Podés filtrar por estado y por posibles recompras. La búsqueda indexa:

• Case ID.
• Orden principal y órdenes relacionadas.
• Transaction IDs.
• Documento, email, teléfono e ID del cliente.
• Nombre y apellido.

La lista se pagina con 10, 20, 50 o 100 casos por página. Los casos se ordenan por última actualización, del más reciente al más antiguo.

La búsqueda no distingue mayúsculas ni acentos y coincide con identificadores normalizados completos, valores indexados completos, palabras individuales del nombre o su forma exclusivamente numérica. No es una búsqueda fuzzy ni por substring arbitrario.

Exportar casos

Exportar genera koru-recovery-cases.csv con todos los casos que coinciden con los filtros actuales de estado, posible recompra y búsqueda, no solamente con la página visible. La app recorre todas las páginas, muestra cuántos casos obtuvo mientras prepara el archivo e incluye estas columnas:

• Cliente.
• Orden principal.
• Estado.
• Método de pago.
• Monto.
• Fecha de actualización.

El tamaño de página seleccionado no limita la exportación.

Detalle de un caso

El detalle muestra:

• Case ID y estado.
• Cliente, email, documento y teléfono.
• Monto y moneda.
• Orden principal con acceso directo a VTEX.
• Estado VTEX observado.
• Transaction ID principal con acceso directo.
• Método de pago.
• Última actualización y expiración.
• Preview del mensaje.
• Órdenes, transaction IDs y order groups relacionados.
• Motivo de descarte cuando existe.
• Notas internas.
• Auditoría.

Acciones disponibles

Auditoría

La auditoría diferencia acciones manuales (admin) y automáticas (system). Registra timestamp, actor, acción, estados anterior/nuevo, órdenes, transacciones, nota/motivo y metadata técnica cuando aplica.

Incluye, entre otros:

• Detección, actualización, elegibilidad y agrupación.
• Recompra exacta o posible.
• Confirmación para continuar.
• Copia y marcado del mensaje.
• Re-chequeo.
• Notas y descartes.
• Cierre por pago, cancelación OMS y expiración.
• Campos de configuración modificados, sin guardar sus valores sensibles en el evento.

Exportar dentro de Auditoría obtiene todos los eventos del caso, no solamente los mostrados inicialmente. El CSV contiene ID del evento, timestamp ISO, fecha localizada, acción visible, código de acción, tipo de actor, actor, estado anterior, estado nuevo, Case ID, órdenes, transaction IDs, nota y metadata. El progreso muestra la cantidad de eventos obtenidos.

Sincronización y automatización

Qué hace cada actualización

Una corrida:

1. Adquiere un lock para evitar sincronizaciones concurrentes.
2. Consulta todas las páginas OMS del rango configurado.
3. Obtiene detalles de las órdenes candidatas.
4. Registra métodos de pago descubiertos.
5. Aplica edad y elegibilidad.
6. Agrupa intentos.
7. Busca recompras exactas y heurísticas.
8. Crea o actualiza casos de forma idempotente.
9. Revisa pagos y cancelaciones de casos abiertos.
10. Expira los casos cuyo límite fue alcanzado.
11. Reconstruye métricas y guarda el estado de la corrida.

Si otra corrida tiene un lock vigente, el resultado es Bloqueada por otra corrida sin duplicar trabajo.

Estado de automatización

Ante un error de OMS, la app registra el fallo y conserva los casos existentes. No borra datos por una sincronización parcial o fallida.

Licencia y seguridad

Validación de licencia

Todas las rutas operativas exigen:

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

La ruta de app settings queda fuera del gate de licencia para permitir el bootstrap, pero sigue requiriendo una sesión admin válida.

Para tolerar fallas transitorias:

• Una autorización positiva se cachea brevemente en memoria.
• Si Koru Suite no responde por red o error de servidor, una validación positiva persistida puede mantener el acceso hasta 72 horas.
• Una revocación explícita bloquea el negocio una vez vencida la breve protección contra respuestas transitorias.

Estos tiempos son internos y no se configuran por tienda.

Datos y credenciales

• React llama únicamente rutas privadas de Koru Recovery.
• El backend usa el contexto y las policies de VTEX IO para OMS.
• La app no solicita ni guarda AppKey/AppToken del merchant.
• No hay secretos Koru en el browser.
• Website ID y App ID identifican recursos, pero no son contraseñas.
• Casos, índices, auditoría, métricas y estado de sync se persisten en VBase bajo el bucket funcional koru-recovery.
• Los casos contienen snapshots operativos del cliente y de las órdenes. Aplicá las políticas de acceso y privacidad de la tienda a los usuarios de VTEX Admin.

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}.koru-recovery.
4. Recargá VTEX Admin.
5. Probá la URL directa /admin/koru-recovery 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 guardar la configuración

• Confirmá que tu usuario puede modificar app settings.
• Revisá campos numéricos fuera de rango.
• Verificá que Website ID y plantilla no estén vacíos.
• Usá un locale válido, por ejemplo es-AR.
• Completá o eliminá filas de transferencia habilitadas que tengan etiqueta o valor faltante.

Un error de permisos requiere intervención de un administrador VTEX; reintentar con el mismo usuario no cambia esa autorización.

La licencia figura inactiva

1. Compará el Website ID con el sitio correcto en Koru Suite.
2. Confirmá que Koru Recovery 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.

No se pudo verificar la licencia

No pudimos verificar la licencia es un estado transitorio de disponibilidad, no una prueba de que haya sido revocada. Reintentá después de unos segundos. Solamente Licencia Koru no activa indica una licencia explícitamente inactiva o sin configurar.

“Actualizar ahora” no crea casos

Revisá, en este orden:

1. Que existan órdenes OMS con estado real payment-pending.
2. Que estén dentro del histórico configurado.
3. Que hayan cumplido la edad mínima.
4. Que su método esté habilitado.
5. Que el detalle OMS tenga cliente, monto y moneda suficientes.
6. Que no exista una recompra exacta pagada.

Una orden visible como Incompleta pero sin payment-pending no es candidata.

No aparecen métodos de pago

Los métodos se descubren durante una sincronización sobre órdenes payment-pending. Ejecutá Actualizar ahora cuando exista al menos una orden de prueba dentro del rango. Un método desconocido queda deshabilitado por defecto.

Copiar mensaje o marcar enviado está bloqueado

Comprobá:

• Al menos un dato de transferencia completo y habilitado.
• Ninguna variable faltante en el preview.
• Estado pendiente para marcar enviado.
• Estado accionable para copiar.
• Confirmación de una posible recompra.

El aviso del preview indica qué variable no pudo resolverse.

El caso no se cerró después del pago

1. Abrí la orden desde el detalle.
2. Confirmá que OMS muestre una etapa interpretada como paga.
3. Ejecutá Re-chequear para ese caso o Actualizar ahora para el conjunto.
4. Si OMS todavía muestra payment-pending, completá primero el proceso operativo de pago en VTEX.

Marcar el mensaje como enviado no marca el pedido como pagado.

La actualización automática está atrasada

• Compará la última comprobación automática con syncIntervalMinutes.
• Un estado “En espera” es normal cuando el heartbeat todavía no está debido.
• Ejecutá Actualizar ahora: además de sincronizar, intenta reparar el schedule.
• Si aparece un error, registrá hora, cuenta, workspace y mensaje.

Para soporte técnico en producción:

vtex logs {account}.koru-recovery

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

Límites funcionales

La versión actual:

• Solo trabaja con órdenes OMS payment-pending.
• Contacta de forma manual; no automatiza canales.
• Ofrece transferencia offline; no procesa pagos.
• No crea ni reactiva links/transacciones de pago.
• No modifica estados OMS por sí misma.
• No convierte monedas.
• No crea roles humanos VTEX.
• No usa Master Data para los casos.
• No reabre automáticamente casos descartados.

Checklist antes de operar

• Koru Recovery instalada en la cuenta y workspace correctos.
• Website ID de la tienda verificado.
• Licencia activa visible.
• Nombre de tienda e idioma/región revisados.
• Reglas operativas aprobadas por ecommerce.
• Frecuencia e histórico adecuados al volumen.
• Al menos un dato de transferencia completo y habilitado.
• Métodos elegibles revisados después de una sincronización.
• Plantilla sin variables faltantes.
• Caso de prueba contrastado con OMS.
• Operadores saben que copiar/enviar no confirma un pago.
• Responsable definido para reflejar transferencias en VTEX.
• Flujo de descarte, notas y posible recompra acordado.
• Última sincronización manual completada sin errores.