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.

Permisos que pide la app

Al instalarla, VTEX pide aceptar estos permisos:

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 {vendor}.pickup-cleaner@2.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 {vendor}.pickup-cleaner@2.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 {vendor}.pickup-cleaner@2.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 {vendor}.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. El App ID de Koru viene incorporado en la app y no se configura.

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 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. La app valida cada valor antes de guardarlo y vuelve a validarlo al leerlo: si un valor guardado es inválido (por ejemplo, una hora que no es HH:MM), la app muestra la pantalla La configuración de la app tiene un valor inválido hasta que se corrija en Admin → Apps → Pickup Cleaner.

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 y el máximo, 50 km.

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.
• El borrado programado y Ejecutar ahora borran hasta 400 puntos por corrida. En el borrado programado, si quedan más candidatos, las consultas siguientes de la misma hora continúan (hasta unos 1.600 por hora). El historial lo indica.

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. Cada tab incluye un tour guiado que se abre la primera vez que lo visitás y que podés volver a ver con el botón Ver tour. La interfaz está en español, inglés y portugués, según el idioma de VTEX Admin.

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

Al instalar o actualizar la app, se registra una tarea en VTEX Scheduler que consulta a la app cada 15 minutos. Esa consulta no borra por sí sola: la app decide en cada una si corresponde actuar.

Secuencia de cada consulta:

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. Si esa hora ya se completó, no hace nada. Así no se repite el borrado dentro de la misma hora.
5. Valida la licencia Koru. Si la licencia está inactiva, o si Koru no responde y no hay una validación positiva reciente, la consulta queda bloqueada, no borra nada y no marca la hora: si se resuelve dentro de esa hora, la consulta siguiente la ejecuta.
6. Clasifica candidatos con los mismos criterios de tag/geo descriptos arriba y borra hasta 400.
7. Si no quedan candidatos, marca la hora como completada. Si quedan, la consulta siguiente de la misma hora continúa.
8. Registra el resultado en el historial y en el estado de la automatización.

Dos consultas no se ejecutan a la vez: si una sigue borrando cuando llega la siguiente, la segunda espera su turno.

Ejecutar ahora

El botón Ejecutar ahora corre el mismo borrado sin esperar el horario, con la configuración guardada:

• No depende del toggle, de la hora ni de que la hora ya se haya completado.
• Si hay cambios sin guardar en el formulario, el botón queda deshabilitado hasta guardarlos, para que lo que se ve en pantalla sea lo que se ejecuta.
• Antes de ejecutar pide confirmación, muestra los filtros que va a aplicar y ofrece descargar un backup JSON de los puntos candidatos.
• Borra hasta 400 puntos por ejecución.

Reparar programación

Si el borrado programado dejó de correr (por ejemplo, el estado no muestra consultas recientes), Reparar programación vuelve a registrar la tarea en VTEX Scheduler. No borra nada.

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 deja candidatos sin procesar por el tope de 400, 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.

La licencia se valida siempre desde el servidor de la app, nunca desde el navegador. Para tolerar fallas transitorias:

• Una validación positiva se reutiliza durante unos minutos.
• Si Koru Suite no responde, la app sigue funcionando con la última validación positiva de las últimas 72 horas. Sin esa validación, muestra La licencia no se puede verificar temporalmente y la automatización queda bloqueada: no es un problema de la licencia, alcanza con reintentar más tarde.
• Si Koru Suite informa la licencia como inactiva, la app deja de operar en pocos minutos y muestra la pantalla de licencia inactiva. Una reactivación impacta en alrededor de un minuto.

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á {vendor}.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 y de hasta 50 km.

La app muestra "La configuración de la app tiene un valor inválido"

Un valor guardado en los app settings no es válido (una hora que no es HH:MM, una zona horaria inexistente o un radio fuera de rango). Corregilo en Admin → Apps → Pickup Cleaner y reintentá.

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 app muestra "La licencia no se puede verificar temporalmente"

Koru Suite no respondió y no hay una validación positiva de las últimas 72 horas. No es un problema de la licencia: reintentá en unos minutos. Mientras dure, la automatización queda bloqueada y no borra nada.

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 estado de la automatización (arriba del tab Automatización): muestra el resultado de la última consulta y su motivo, por ejemplo que no era la hora configurada, que la hora ya se había completado o que la licencia estaba bloqueada.
7. Si el estado no muestra consultas recientes, usá Reparar programación.

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.
• Borra hasta 400 puntos por corrida. El borrado programado continúa en las consultas siguientes de la misma hora (hasta unos 1.600 por hora).
• Usa matching de tags exacto y sensible a mayúsculas, sin tolerancia a errores de tipeo hechos fuera de la app.
• Acepta un radio geográfico de hasta 50 km en la automatización; el tab Limpieza geo 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.
• Estado de la automatización revisado después de la primera hora programada.
• Responsable definido para revisar el historial de operaciones periódicamente.