Koru Shipday

Integra VTEX con Shipday: carga masiva de tarifas por código postal, alta automática de órdenes en la flota de reparto y actualización del tracking y la entrega en VTEX.

Koru Shipday es una VTEX Admin App que conecta una tienda VTEX con Shipday, el software de gestión de última milla con flota propia. Cubre el circuito completo de un envío: cargar las tarifas de envío por código postal en VTEX, dar de alta cada orden pagada en Shipday para que salga a reparto, y devolver a VTEX la referencia de seguimiento y la confirmación de entrega.

La app se organiza en tres módulos, más una capa transversal de configuración, diagnóstico y auditoría:

• Tarifas — reemplaza la tabla de tarifas por código postal de una o varias políticas de envío desde una única planilla, en una sola operación con respaldo automático.
• Órdenes — detecta las órdenes con pago aprobado cuya política de envío está habilitada, calcula los bultos y las crea en Shipday sin duplicarlas.
• Eventos — recibe el webhook de Shipday y refleja en VTEX la referencia de seguimiento y la entrega confirmada.

Antes de empezar

Responsables recomendados

Una misma persona puede cubrir varios roles en una tienda chica.

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 ese acceso, el módulo de Tarifas queda bloqueado: la escritura de tarifas se hace con la sesión del administrador, no con la identidad de la app.
• 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 Shipday activa para ese sitio.
• Una cuenta de Shipday con su API Key (dashboard de Shipday → My Account → Integrations → API Credentials).
• Al menos una política de envío ya configurada en VTEX para asociar a Shipday.

Koru Shipday no crea un rol VTEX propio. El acceso a Logistics se administra con los controles 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 {vendor}.koru-shipday@0.x

vtex list

Abrir la app en VTEX Admin

Podés abrir Koru Shipday 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/koru-shipday

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

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

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

Los settings son por instalación/workspace. Verificá el Website ID, la API Key de Shipday, el token del webhook y las políticas habilitadas en el ambiente definitivo aunque ya los hayas probado en otro workspace.

Actualización y desinstalación

Actualizar

Seleccioná la cuenta/workspace correcto, confirmalo y volvé a instalar el rango:

vtex whoami
vtex install {vendor}.koru-shipday@0.x
vtex list

Después de actualizar, abrí la app y verificá licencia, verificaciones principales, políticas habilitadas y el estado de las automatizaciones. 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}.koru-shipday
vtex list

Activación y primer acceso

Obtener el Website ID

Antes del primer uso, Red Clover debe activar Koru Shipday 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 vive en el código de la app y no puede modificarse desde la tienda.

Conectar la tienda

En el primer acceso, la app muestra Conectar 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 Shipday tenga una licencia activa.

Puesta a punto recomendada

Seguí este orden: cada paso habilita al siguiente, y los dos módulos operativos se desbloquean recién cuando sus verificaciones están en verde.

Qué habilita cada módulo

Tarifas y Órdenes no se habilitan solos: dependen de verificaciones distintas, porque operan con identidades distintas.

Cuando una verificación falla, la app muestra un código de diagnóstico:

Configuración completa

Toda la configuración vive en los app settings de VTEX y se administra desde la pantalla Configuración de la app (o desde Admin → Apps → Koru Shipday). Los cambios no se aplican hasta tocar Guardar cambios.

General y licencia

Conexión con Shipday

Operación

Atributo de bultos

Automatización

Módulo Tarifas

Reemplaza la tabla de tarifas por código postal de una o varias políticas de envío desde una única planilla. No crea ni modifica políticas, muelles ni almacenes: opera sobre la tabla de valores de flete de las políticas que ya existen.

Cómo se usa

Columnas de la plantilla

Validaciones

Qué reemplaza exactamente una carga

La carga reemplaza solo los códigos postales incluidos en el archivo. Los códigos postales que no estén en la planilla conservan su tarifa anterior sin cambios: no es un borrado y recarga de la tabla completa.

Respaldo y reversión

• Antes de escribir sobre una política, la app respalda las tarifas actuales de los códigos postales que la carga va a tocar.
• Si la escritura falla a mitad de camino con varias políticas seleccionadas, la app revierte las que ya se habían aplicado usando ese respaldo.
• El respaldo automático está acotado a 300 códigos postales distintos por carga. Una planilla que supera ese techo se puede aplicar igual, pero la app pide una confirmación explícita: esa carga va sin respaldo y no se puede revertir automáticamente.
• Un código postal que hoy no tiene ninguna tarifa cargada no deja nada para respaldar: la reversión puede restaurar el valor anterior de un CP que ya existía, no "deshacer" el alta de un CP nuevo.

Estados de una carga

Carga masiva de bultos

Está dentro de Configuración, no en una pestaña propia. Sirve para cargar la especificación de bultos en muchos SKUs de una vez, en lugar de completarla producto por producto en el catálogo.

Cada fila se aplica por separado: una que falla no afecta a las demás, y el resultado muestra cuántas se aplicaron y cuántas quedaron con error. Máximo 300 filas por carga — una planilla más grande se rechaza pidiendo dividirla.

Módulo Órdenes

Cómo se detectan las órdenes

La app consulta periódicamente el OMS de VTEX en busca de órdenes nuevas y lleva un marcador de hasta dónde procesó, para no releer siempre lo mismo.

• La primera corrida en un workspace mira las últimas 24 horas.
• Cada corrida procesa hasta 20 páginas de 100 órdenes. Si hay más, el marcador no avanza más allá de lo procesado y la siguiente corrida sigue desde ahí: no se pierde ninguna orden, se reparte en más corridas.
• Si una orden falla al leerse, la corrida se corta ahí mismo sin avanzar el marcador, para no dejarla atrás.

Cuándo una orden es elegible

Una orden se envía a Shipday cuando cumple todas estas condiciones:

ORD-001 es el caso normal de una orden recién creada: se reevalúa sola en la siguiente corrida, no requiere ninguna acción.

Estados de una orden

Reintento manual

Las filas en Error de datos y Error permanente muestran el botón Reintentar. Son los dos únicos estados que la app nunca abandona sola, a propósito: reintentar en un loop una orden que Shipday va a seguir rechazando no arregla nada.

El reintento no duplica la orden: si un intento anterior terminó con una respuesta incierta, la app primero consulta a Shipday si la orden ya existe y, si la encuentra, solo registra la relación.

Qué se envía a Shipday

De cada orden se manda el número de orden de VTEX (que es lo que después permite matchear los eventos entrantes), los datos del destinatario, el punto de retiro configurado, el total, los ítems con precio y cantidad, la forma de pago normalizada y la cantidad de bultos calculada. No se envían datos de pago ni credenciales.

Módulo Eventos (tracking y entrega)

Shipday avisa por webhook cada cambio de estado del reparto. La app registra todos los eventos y refleja en VTEX únicamente dos cosas: la referencia de seguimiento y la confirmación de entrega.

Configurar el webhook

1. Elegí un token de hasta 32 caracteres y guardalo en Configuración → Webhook de Shipday.
2. Copiá la URL que muestra esa misma sección — tiene esta forma:

https://{store-account}.myvtex.com/_v/public/koru-shipday/webhook/shipday

3. Cargá la URL y el token en el dashboard de Shipday.

Qué hace la app con cada evento

Resultados que vas a ver en la pantalla

Facturación y reintentos

Para registrar el tracking o confirmar la entrega, VTEX exige que la orden ya esté facturada. La app nunca factura: asume que la orden ya lo está cuando llega a Shipday (regla operativa: no se despacha sin factura) y solo lee el número de factura.

Si todavía no está facturada, el evento no se pierde: queda en Reintentando y el job de reintento de tracking vuelve a intentarlo cada 10 minutos, con espera creciente. Si el problema no es transitorio, la orden queda marcada para revisión manual.

Automatizaciones

Tres procesos automáticos, visibles en Resumen → Automatizaciones:

El disparador técnico corre siempre; lo que decide si corresponde actuar es el interruptor y el intervalo configurados. La conciliación existe porque el polling normal ya no vuelve a mirar una orden vieja: barre las órdenes que quedaron pendientes o en reintento y las reprocesa, sin duplicar nunca una orden ya creada en Shipday.

Estados de una corrida

El botón Ejecutar ahora dispara la misma lógica de forma manual, sin esperar al horario, y funciona aunque el proceso automático esté apagado. Es la forma recomendada de probar un cambio de configuración de inmediato.

Pantallas

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 Shipday.

Para tolerar fallas transitorias de red o del servicio de licencias, una autorización positiva se conserva brevemente; una respuesta explícita de licencia revocada bloquea el uso de la app de inmediato. El webhook es la excepción: con la licencia revocada o la integración apagada, responde con éxito y descarta el evento dejando registro, en vez de hacer que Shipday reintente para siempre.

Datos y credenciales

• La app no pide ni guarda AppKey/AppToken del merchant. Para operar sobre VTEX usa la sesión del administrador logueado (acciones manuales) o su propia identidad de app (procesos automáticos).
• El único secreto de la app es la API Key de Shipday, guardada en los app settings de VTEX y nunca expuesta al navegador en claro.
• El navegador nunca llama directamente a las APIs de VTEX ni a Shipday: todo pasa por rutas propias de la app.
• Website ID y App ID identifican recursos, pero no son contraseñas.
• El estado de las órdenes, los eventos y el historial de cargas se persisten en el almacenamiento interno de la app, no en Master Data ni en las órdenes de VTEX.
• Cada acción lleva un identificador de correlación que permite seguir su rastro en los logs cuando hace falta soporte.

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

La licencia figura inactiva

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

Tarifas está bloqueado

Es siempre CFG-001: tu usuario no tiene el rol de Logistics en License Manager. Pedile a un administrador de VTEX que lo agregue y volvé a verificar los permisos.

Órdenes está bloqueado

Revisá las cuatro condiciones en Configuración: API Key de Shipday válida, permiso de la app en orden, Integración activa encendida y al menos una política de envío marcada. El aviso indica cuál falta.

La conexión con Shipday falla

• Confirmá que la API Key sea la de esta cuenta de Shipday y que no esté revocada.
• Si el error es temporal (CFG-004), reintentá en unos minutos: no es un problema de configuración.
• Recordá que Probar conexión puede estar probando un valor que todavía no guardaste; la app lo avisa.

No se está enviando ninguna orden

Revisá, en este orden:

1. Que Integración activa esté encendida.
2. Que Buscar órdenes nuevas automáticamente esté encendido, o disparalo a mano desde Resumen.
3. Que la política de envío de esas órdenes esté marcada en Configuración.
4. Que las órdenes tengan el pago aprobado.
5. La pantalla Órdenes: la columna Detalle indica el motivo exacto por orden.

Una orden quedó en "Error de datos"

Es un rechazo de Shipday por los datos de la orden. Revisá que el destinatario tenga nombre, teléfono y dirección completos, y que el punto de retiro configurado sea una dirección legible. Corregido eso, usá Reintentar en esa fila.

No llega ningún evento de Shipday

1. Confirmá que la URL cargada en Shipday sea la que muestra la app para este workspace.
2. Confirmá que el token de Shipday sea idéntico al guardado en la app (hasta 32 caracteres, sin espacios).
3. Verificá que Integración activa esté encendida: con la integración apagada los eventos se descartan.
4. Revisá la pantalla Eventos: si hay eventos con resultado Ignorado, el webhook está llegando bien y lo que ves son estados intermedios que no se propagan.

La entrega no se refleja en VTEX

Mirá el evento en la pantalla Eventos:

• Reintentando con motivo de facturación: la orden todavía no está facturada en VTEX. Se resuelve solo cuando se factura, si el reintento automático de tracking está activo.
• Con error: la actualización en VTEX falló. Revisá que la orden exista, esté facturada y no esté cancelada.
• Sin ningún evento: el problema está en el webhook, no en el tracking. Ver el punto anterior.

La plantilla se rechaza aunque parezca correcta

Descargá la plantilla de nuevo desde la app y completala sin reabrir el archivo en otra herramienta. Reabrir y volver a guardar un .xlsx puede alterar la hoja oculta donde viaja la versión.

Las tarifas no aparecen en el simulador

Si la carga figura como exitosa, esperá: VTEX puede tardar de minutos a más de un día en propagar tarifas nuevas. Verificá primero el estado de la carga en el módulo Tarifas antes de volver a subir el archivo.

Límites funcionales

La versión actual:

• Asume una orden = un envío: no contempla órdenes de marketplace multi-seller que se despachan en más de un envío o factura.
• Usa un único punto de retiro para toda la cuenta, no uno por política de envío.
• Respalda automáticamente hasta 300 códigos postales por carga de tarifas; por encima de eso, la carga va sin respaldo y requiere confirmación explícita.
• Aplica hasta 300 filas por carga masiva de bultos, sin respaldo ni reversión.
• Procesa hasta 20 páginas de 100 órdenes por corrida de detección.
• No factura órdenes en VTEX: asume que ya vienen facturadas.
• No propaga a VTEX los estados intermedios del reparto ni las entregas fallidas: solo la referencia de seguimiento y la confirmación de entrega.
• No crea ni modifica políticas de envío, muelles, almacenes ni transportadoras.
• Opera siempre sobre la cuenta VTEX donde está instalada.

Checklist antes de operar

• Koru Shipday instalada en la cuenta y workspace correctos.
• Website ID verificado y licencia activa confirmada.
• API Key de Shipday cargada y Probar conexión en verde.
• Permisos de VTEX verificados: rol de Logistics del usuario y policies de la app.
• URL y token del webhook cargados en el dashboard de Shipday, para este workspace.
• Punto de retiro completo y legible.
• Atributo de bultos creado en el catálogo, configurado en la app y verificado contra un SKU de muestra.
• Políticas de envío habilitadas seleccionadas.
• Carga de tarifas de prueba aplicada y revisada antes de una carga grande.
• Integración activa encendida.
• Corrida manual de envío de órdenes ejecutada y revisada en la pantalla Órdenes.
• Automatizaciones activadas recién después de validar manualmente.
• Responsable definido para revisar órdenes con error y eventos periódicamente.