Koru Pickup Cleaner

Detecta y elimina masivamente pickup points de terceros que ensucian el catálogo de retiro en tienda de VTEX, preservando siempre tus sucursales propias.

Koru Pickup Cleaner es una VTEX Admin App que identifica y elimina masivamente pickup points de logísticas de terceros (Andreani, OCA, Correo Argentino, etc.) que quedan mezclados en el catálogo de puntos de retiro de la tienda, sin tocar nunca las sucursales propias del comercio.

Muchas integraciones de logística crean automáticamente cientos o miles de puntos de retiro con sus propias agencias, disponibles para el checkout. Esto ensucia el catálogo de pickup points, sobre todo cuando esos puntos quedan muy cerca de las sucursales reales de la tienda o duplican su cobertura.

La app está pensada para dos momentos distintos:

• El equipo técnico o la agencia VTEX instala la app, conecta la licencia y define el tag que identifica a las sucursales propias.
• El equipo de ecommerce o logística revisa candidatos, ajusta filtros y radio geográfico, y decide qué limpiar manualmente o mediante automatización.

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 al módulo Logistics. Sin este acceso, la Logistics API responde 401/403 al listar, editar o borrar puntos.
• 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 Pickup Cleaner activa para ese sitio.
• El tag exacto (case-sensitive) que identifica a las sucursales propias en tu catálogo de pickup points.

Koru Pickup Cleaner no crea un rol VTEX propio. El acceso a Logistics 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 standalone: 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}.pickup-cleaner@1.x

vtex list

Abrir la app en VTEX Admin

Podés abrir Pickup Cleaner 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/pickup-cleaner

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

https://{store-account}.myvtex.com/admin/pickup-cleaner

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}.pickup-cleaner@1.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}.pickup-cleaner@1.x
vtex list

Después de actualizar, abrí la app y verificá licencia, tag de sucursales propias, settings de automatización y último resultado del historial. 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}.pickup-cleaner
vtex list

Activación y primer acceso

Obtener el Website ID

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

Puesta a punto recomendada

Seguí este orden para evitar borrar por error puntos que en realidad son propios:

Configuración completa

Toda la configuración vive en los app settings de VTEX (Admin → Apps → Pickup Cleaner, o desde el tab Automatización de la propia app). No existe otro canal de configuración.

General y licencia

Automatización (borrado programado)

Cómo identifica qué limpiar

Criterio de clasificación por tags

Las logísticas de terceros (Andreani, OCA, Correo Argentino, etc.) no marcan el campo nativo isThirdPartyPickup de VTEX al crear sus puntos de retiro. Por eso Koru Pickup Cleaner no puede confiar en ese campo y usa una heurística propia basada en tags:

1. Un punto que tiene el tag configurado en ownBranchTag nunca se considera candidato a eliminar, sin excepción y sin importar otros filtros.
2. Si se configuraron scheduledTags, el punto debe tener al menos uno de esos tags para ser candidato. Si la lista está vacía, cualquier punto sin el tag de sucursal propia es candidato.
3. Si scheduledOnlyInactive está activo, el punto además debe tener isActive: false.

Limpieza por radio geográfico (opcional)

Cuando scheduledGeoEnabled está activo, se aplica un filtro adicional sobre los candidatos ya filtrados por tag: solo se conservan como candidatos definitivos los puntos que están dentro del radio configurado (scheduledGeoRadiusKm) de alguna sucursal propia, calculado con la fórmula de distancia de Haversine sobre latitud y longitud.

Guardarraíles del modo geográfico:

• Se validan que las coordenadas sean numéricas y estén en rango (latitud -90 a 90, longitud -180 a 180). El par (0, 0) se considera un dato vacío, no una ubicación real.
• Si ninguna sucursal propia tiene coordenadas válidas, no se elimina nada.
• Un candidato sin coordenadas válidas tampoco se elimina en modo geográfico: se excluye por seguridad, no se incluye por defecto.
• El radio default es 1,5 km. Si el valor guardado no es un número finito positivo, la app usa ese default.

Acción de limpieza: borrado permanente

La única acción de limpieza es un borrado físico (DELETE) contra la Logistics API de VTEX. Es irreversible desde VTEX: la única forma de "deshacer" un borrado es recrear manualmente el punto a partir de un backup CSV/JSON exportado previamente.

Para evitar sobrecargar la API, los borrados se ejecutan en lotes:

• Lotes de 15 solicitudes en paralelo, con una breve pausa entre lotes.
• La limpieza programada por cron tiene un tope de 2.000 borrados por corrida. Si hay más candidatos, el resto queda para la próxima corrida en la que se cumpla la condición configurada (esto queda explícito en el historial de operaciones).

Otras acciones disponibles

Koru Pickup Cleaner no solo borra puntos de retiro:

• Editar un punto individual: actualiza el registro completo en Logistics (no existe una actualización parcial en la API de VTEX).
• Agregar tags de forma masiva: suma tags nuevos sin reemplazar los existentes sobre la selección actual.
• Importar o actualizar masivamente desde CSV o Excel.
• Exportar CSV de la lista filtrada actual, útil como backup manual y re-importable.

Pantallas y operación diaria

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

Importación por CSV o Excel

Columnas requeridas: id, name, latitude, longitude, postalCode, country, city, state, street, number.

Columnas opcionales: description, instructions, neighborhood, complement, reference, isActive, tagsLabel, seller, y los horarios por día (openMon/closeMon … openSun/closeSun).

Las filas inválidas se muestran en la previsualización con el detalle del error, pero no bloquean la importación del resto de filas válidas.

Automatización y ejecución programada

La limpieza automática corre sobre un heartbeat técnico que VTEX Scheduler dispara cada hora en punto. Ese heartbeat no ejecuta un borrado automáticamente: la app decide internamente, en cada corrida, si corresponde actuar.

Secuencia de cada corrida:

1. Lee los settings actuales.
2. Si Borrado automático activo está apagado, no hace nada.
3. Si la hora actual (en la zona horaria configurada) no coincide con Hora del borrado, no hace nada.
4. Valida la licencia Koru. Si no está activa, se salta esta corrida sin marcar la hora como ejecutada, para que una reactivación posterior corra en la siguiente pasada horaria.
5. Verifica que esa hora específica no se haya ejecutado ya (protección de idempotencia), evitando duplicar el borrado si el heartbeat se repite.
6. Clasifica candidatos con los mismos criterios de tag/geo descriptos arriba y ejecuta el borrado, respetando el tope de 2.000 por corrida.
7. Registra el resultado en el historial de operaciones.

El botón Ejecutar ahora del tab Automatización dispara la misma lógica de forma manual, sin esperar a que llegue la hora configurada — útil para probar la configuración o forzar una limpieza puntual.

Historial y auditoría

Cada acción relevante (borrado manual, importación, limpieza geográfica, tagging masivo, edición individual y corridas de automatización) queda registrada en un historial de operaciones, visible en el tab Automatización.

• Guarda las últimas 100 operaciones, la más reciente primero.
• Cada entrada incluye tipo de operación, cantidad afectada, detalle del resultado y, para acciones manuales, el usuario de VTEX que la ejecutó. Las corridas automáticas se muestran como acción del sistema, sin usuario asociado.
• Cuando una corrida programada deja candidatos sin procesar por el tope de 2.000, el detalle lo indica explícitamente.

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 Pickup Cleaner.

Para tolerar fallas transitorias de red o del servicio de licencias, una autorización positiva se cachea brevemente; una respuesta explícita de licencia revocada bloquea el uso de la app de inmediato.

Datos y credenciales

• El navegador nunca llama directamente a la Logistics API de VTEX: todas las solicitudes pasan por rutas propias de la app, que gestionan la autenticación con tokens internos de VTEX IO.
• La app no solicita ni guarda AppKey/AppToken del merchant. La identidad usada para operar Logistics es la sesión del propio admin logueado (para acciones manuales) o el token propio de la app (para la automatización programada).
• Website ID y App ID identifican recursos, pero no son contraseñas.
• El historial de operaciones se persiste en el almacenamiento interno de la app, no en Master Data ni en las órdenes de VTEX.
• Requiere que el usuario logueado tenga acceso al módulo Logistics en su rol de License Manager; sin ese acceso, las acciones de listar, editar o borrar fallan.

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

La sesión fue rechazada o expiró

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

No puedo listar, editar o borrar puntos

Confirmá que tu usuario tenga acceso al módulo Logistics en su rol de License Manager. Sin ese permiso, la Logistics API rechaza la operación aunque la sesión de VTEX Admin sea válida.

No puedo guardar la configuración

• Confirmá que tu usuario puede modificar app settings.
• Revisá que el Website ID no esté vacío.
• Verificá el formato de hora (HH:MM) y que la zona horaria sea una de las disponibles en la lista.
• Revisá que el radio geográfico sea un número mayor a 0.

La licencia figura inactiva

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

La limpieza programada no elimina nada

Revisá, en este orden:

1. Que Borrado automático activo esté encendido.
2. Que la hora actual coincida con Hora del borrado, considerando la zona horaria configurada.
3. Que el tag de sucursales propias esté cargado correctamente (mayúsculas y minúsculas exactas) en tus sucursales reales.
4. Que existan puntos sin ese tag que cumplan los filtros de scheduledTags y scheduledOnlyInactive configurados.
5. Si usás el modo geográfico, que al menos una sucursal propia tenga coordenadas válidas.
6. El historial de operaciones: puede indicar que la licencia no estaba activa en ese momento, o que ya se ejecutó esa hora específica.

La limpieza geográfica no encuentra candidatos

• Confirmá que las sucursales propias tengan latitud y longitud cargadas (distintas de 0, 0).
• Aumentá el radio de búsqueda de forma temporal para verificar si el problema es de distancia o de datos faltantes.
• Verificá que los puntos candidatos también tengan coordenadas válidas.

La importación rechaza filas

Revisá la previsualización: cada fila inválida muestra el motivo exacto (columna vacía, coordenada fuera de rango, ID con espacios). Corregí el archivo y volvé a subirlo; las filas válidas no se ven afectadas por errores en otras filas.

Límites funcionales

La versión actual:

• Sincroniza hasta 10.000 puntos de retiro por carga (100 páginas de 100). Catálogos más grandes no se cargan completos en una misma sincronización.
• Ejecuta borrados permanentes; no ofrece una papelera de reciclaje propia.
• Limita el borrado programado a 2.000 eliminaciones por corrida.
• Tiene su interfaz en español, independientemente del idioma configurado en la cuenta VTEX.
• Usa matching de tags exacto y sensible a mayúsculas, sin tolerancia a errores de tipeo hechos fuera de la app.
• No valida un tope duro para el radio geográfico más allá de exigir un número mayor a 0 (la UI recomienda no superar 3 km).
• Opera siempre sobre la cuenta VTEX donde está instalada; no gestiona pickup points de otra cuenta desde una misma instalación.
• No integra con VTEX OMS ni Master Data: solo trabaja sobre la Logistics API.

Checklist antes de operar

• Koru Pickup Cleaner instalada en la cuenta y workspace correctos.
• Website ID de la tienda verificado.
• Licencia activa confirmada.
• Usuario con acceso al módulo Logistics en su rol de License Manager.
• Catálogo sincronizado y estadísticas de Propias/Terceros revisadas.
• Tag de sucursales propias verificado contra el catálogo real, mayúsculas incluidas.
• Backup CSV exportado antes del primer borrado real.
• Borrado de prueba acotado ejecutado y validado en el historial.
• Radio geográfico probado en modo análisis antes de habilitarlo en automatización.
• Automatización configurada (hora, zona horaria, tags, filtros) solo después de validar manualmente.
• Responsable definido para revisar el historial de operaciones periódicamente.