A-03
Koru Shipday
Integración logística entre VTEX y Shipday: carga masiva de tarifas, envío de órdenes y actualización de tracking. App nativa del Admin de VTEX.
This sheet is not translated yet. Shown in Spanish.
| Client | Koru Suite · producto propio de la agencia |
|---|---|
| Type | producto |
| Platform | VTEX IO |
| Year | 2026 |
| Role | Autor |
| Stack | TypeScript · React · VTEX IO node 7.x · VTEX IO react 3.x · VBase · Vitest |
| Casos de test | 391 tests · bloques it/test en 37 archivos |
| Commits propios | 111 de 111 |
| Código | 17.562 líneas · git ls-files ts/tsx/js, sin node_modules ni dist |
Contexto
Una tienda VTEX que despacha con Shipday tiene tres problemas de sincronización: las tarifas de envío se cargan a mano, las órdenes hay que pasarlas de un sistema al otro, y el estado del envío no vuelve al comprador.
Opciones
La salida rápida en VTEX es pedirle al cliente una AppKey y un AppToken, guardarlos y llamar a la API desde donde sea más cómodo. Funciona el primer día. Después esas credenciales quedan en una configuración que nadie rota, con permisos de más, y el día que se filtran no hay forma de saber qué las usó.
Decisión
Ninguna credencial manual. La app es nativa de VTEX IO y todas las llamadas salen del
builder node, autenticando con tokens IO:
- Las rutas que dispara la interfaz usan la sesión del admin que está logueado. Si esa persona no tiene permiso, la llamada falla donde tiene que fallar.
- El cron horario usa el token de la propia app, que es lo único que corre sin una persona detrás.
El frontend nunca ve un token ni llama a una API de VTEX de forma directa: sólo pega a
rutas propias bajo /_v/private/. Esa regla es la que hace que la app se pueda instalar
en una tienda ajena sin pedirle nada al cliente más que instalarla.
Verificación
391 casos de test repartidos en 37 archivos, escritos contra los contratos reales de las APIs de Logistics y OMS. El historial de operaciones queda en VBase, así que una carga masiva que salió mal se puede leer después.
Consecuencias
Todo pasa por el node, así que no hay atajos: una pantalla nueva necesita su ruta y su
test. Es más lento de arrancar y es la razón por la que la app se puede licenciar a
tiendas que no controlo.