A-15
Pickup Cleaner
Gestión masiva de puntos de retiro VTEX: limpieza por radio geográfico con Haversine, borrado programado idempotente e importación desde planilla.
| Cliente | Koru Suite · producto propio de la agencia |
|---|---|
| Tipo | producto |
| Plataforma | VTEX IO |
| Año | 2026 |
| Rol | Autor |
| Stack | TypeScript · React · VTEX IO node 7.x · Logistics API · VBase · Vitest |
| Código | 5.085 líneas · git ls-files ts/tsx, sin node_modules ni dist |
| Commits propios | 21 de 21 |
| Casos de test | 77 tests |
Contexto
Una tienda VTEX con logística de terceros acumula miles de puntos de retiro, muchos duplicados: el punto propio de la sucursal y el del operador logístico a cincuenta metros. El comprador ve dos opciones que son el mismo lugar.
Opciones
Se puede depurar a mano desde el admin de VTEX, de a un punto, o borrar por tag y confiar en que los tags estén bien puestos. Lo primero no escala; lo segundo borra cosas que no había que borrar.
Decisión
Limpieza por radio geográfico: distancia Haversine entre los puntos de terceros y las sucursales propias, y se eliminan los que caen dentro del radio configurado. El criterio es la geografía y no un tag, porque la geografía no depende de que alguien haya etiquetado bien.
Tres decisiones que hacen que se pueda usar sin miedo:
Backup JSON antes de cada borrado. Siempre, no como opción.
El cron es idempotente. El borrado programado deja un marcador en VBase, así que una corrida repetida no vuelve a actuar. Está gateado por hora y zona horaria del merchant, porque «las 3 de la mañana» significa cosas distintas según la tienda.
Tope de 2.000 borrados por corrida. Un límite duro: si la configuración está mal, el daño está acotado y hay tiempo de verlo en el historial.
La configuración de la limpieza geográfica se puede promover a automatización con un click, que es la diferencia entre una herramienta que usás una vez y una que queda funcionando.
Verificación
5.085 líneas, 77 casos de test. Las llamadas a la Logistics API son server-side y autentican con tokens IO: la sesión del admin logueado para las rutas, el token de la app para el cron. Sin AppKey ni AppToken manuales.
Consecuencias
El tope de 2.000 significa que una limpieza grande necesita varias corridas. Preferí eso antes que una sola corrida capaz de vaciar la logística de una tienda por un radio mal tipeado.