BodegApp — El WMS chileno simple, poderoso y confiable.

El sistema está construido sobre tres principios que lo distinguen:

• La realidad física manda. El inventario del sistema refleja siempre dónde está la mercadería de verdad: lo que se prepara sigue en su bodega de origen, lo que viaja está "en tránsito", y nada aparece en destino antes de ser recepcionado.
• Trazabilidad inmutable. El Kardex nunca se borra ni se edita. Deshacer una operación genera su movimiento inverso, con usuario, motivo y hora. Cada saldo se puede reconstruir movimiento a movimiento.
• Doble registro sincronizado. Cada operación se escribe simultáneamente en la base del WMS y en tu sistema on-premise (ERP), con verificaciones de consistencia y un chequeo de integridad automático cada 6 horas.

Cómo está construido

• Aplicación web responsiva — funciona en computador, tablet y teléfono, sin instalar nada. Los escáneres usan la cámara del dispositivo o pistolas lectoras.
• Doble base de datos: PostgreSQL como motor del WMS (ubicaciones, manifiestos, rutas, kardex) y escritura dual al MySQL on-premise (APP_STOCK), que sigue siendo la base compartida con los sistemas históricos de la empresa. Sincronización automática cada 30 segundos en ambos sentidos.
• Multi-empresa y multi-bodega: varias razones sociales operan las mismas bodegas físicas con inventarios lógicamente separados y KPIs consolidables.

Seguridad

• Sesiones con token firmado (JWT) de 8 horas. Al expirar, la app muestra el aviso de desconexión y vuelve sola a la pantalla de login.
• Permisos en tres dimensiones: empresa, bodega y módulo — un usuario solo ve y opera lo que le corresponde.
• Las credenciales de integraciones (API keys, WooCommerce, WhatsApp) se guardan cifradas u ocultas tras escritura ("write-only": se ingresan una vez y no vuelven a mostrarse).
• Respaldo automático diario (03:00) de base de datos y código, con retención de 7 días.

⭐ Perfiles personalizados: el acceso a la medida de tu organización

Además de los roles estándar, cada empresa puede crear perfiles propios con distintos niveles de acceso según su requerimiento (Configuración → Perfiles). Un perfil define exactamente qué módulos del menú ve y opera cada usuario — nada más, nada menos:

• Ejemplos reales: "Recepcionista" (solo Recepción + Consulta de Stock), "Jefe de Despacho" (Picking, Packing, Despacho y Monitor), "Analista" (solo Dashboard y Kardex, sin operación), "Encargado de Sucursal" (Recepción de Traslado + Putaway + Consultas).
• Los perfiles se asignan por usuario y por empresa — la misma persona puede tener perfiles distintos en empresas distintas.
• Se combinan con el alcance de bodegas de cada usuario: los KPIs, las colas de trabajo y las búsquedas respetan automáticamente ambas dimensiones.
• Los cambios de perfil aplican al instante en el menú del usuario, sin reinstalar ni reiniciar sesión.

Tres códigos gobiernan toda la trazabilidad:

• B-00000000 — Etiqueta de SKU (bulto unitario). Identifica una cantidad concreta de un producto. Nace en la recepción con su etiqueta QR imprimible y acompaña al stock toda su vida: putaway, picking, fraccionamiento, traslado. Es la unidad mínima de trazabilidad.
• PL-00000000 — Pallet / bulto de salida. Agrupa etiquetas B- en la estación de packing para viajar juntas. Es lo que se escanea al recibir un traslado.
• MN-000000 — Manifiesto. El documento que ordena el trabajo: qué se mueve, de dónde a dónde, en qué estado del flujo va (picking → packing → despacho → entrega/recepción).

Regla de oro: escanea, no digites. Cada etiqueta tiene QR; el escáner integrado identifica automáticamente si leíste un B-, un PL-, un SKU o una ubicación, y actúa en consecuencia.

Dos formas de escanear, cero configuración

• 📷 Cámara del dispositivo (teléfono, tablet o notebook): el botón de escaneo abre el visor con enfoque automático. Funciona en Chrome, Edge y Safari; el navegador pedirá permiso de cámara la primera vez.
• 🔫 Pistola lectora (hardware): cualquier lector USB o Bluetooth en modo teclado ("keyboard wedge") funciona de inmediato — dispara la lectura en el campo activo, sin drivers ni configuración. Es la opción recomendada para estaciones fijas de alta frecuencia.

Despacho inteligente de códigos

El lector es contextual: la misma acción de escanear hace lo correcto según la pantalla y el patrón del código leído:

Conectar y sincronizar la impresora (cada dispositivo)

1. Toca el ícono de impresora 🖨️ en la barra superior (junto al selector de empresa): se abre el selector de impresoras.
2. Presiona "📡 Escanear Dispositivos Bluetooth": el navegador muestra las impresoras al alcance; elige la tuya y empareja (una sola vez por dispositivo).
3. El punto de estado del ícono pasa a activo. La impresora queda recordada en ese dispositivo — cada estación o teléfono se vincula con la suya, y varias estaciones imprimen en paralelo sin interferirse.

Requisito: Google Chrome (Android o escritorio) con Bluetooth activo — usa Web Bluetooth (BLE). También se soporta conexión USB/red según el modelo configurado.

Configuración de etiquetas por empresa

En Configuración → Empresas, cada razón social define su perfil de impresión — y toda la operación lo hereda automáticamente:

Anatomía de las etiquetas

• Etiqueta B- (SKU): QR grande del código B-, razón social y RUT, SKU y descripción, cantidad y unidad, bodega, fecha de emisión y — si el producto exige captura de datos — la fila S/N con el serial del fabricante. Color de acento y subtítulo personalizables al fraccionar.
• Etiqueta PL- (pallet): QR del código PL-, tipo de documento y folio, tipo de movimiento, bodega destino, operador, fecha, total de ítems y unidades — la "carátula" que viaja pegada al bulto y que se escanea en la recepción del destino.

Cómo se usa

1. Menú → Recepción. Selecciona bodega y tipo de ingreso.
2. Escanea o busca el SKU (también puedes escanear su N° de serie genérico si el producto lo tiene configurado en el maestro).
3. Indica cantidad. Si el producto exige captura de datos, escanea el serial único del fabricante de cada unidad (garantía y trazabilidad unitaria).
4. Confirma: se crea la etiqueta B- y se imprime en la térmica (ESC/POS por Bluetooth/USB, formato configurable por empresa).
5. El stock queda en la ubicación genérica 00-00-00 de la bodega, listo para putaway.

Inventario Inicial (carga base de una bodega)

La puerta de entrada de una bodega nueva a BodegApp: carga el inventario existente etiquetándolo pieza a pieza — sin detener la operación y sin depender de que los saldos históricos estén perfectos.

1. En la misma pantalla de Recepción, cambia el tipo de ingreso a "Inventario inicial (carga base)" — la opción solo aparece en bodegas habilitadas para carga inicial.
2. Presiona "▶ Iniciar carga de inventario inicial" y trabaja en modo sesión: escanea SKU, ingresa la cantidad contada, imprime la etiqueta B- y pégala — repite producto por producto o zona por zona.
3. Cada carga es aditiva: crea una etiqueta B- nueva con las unidades ingresadas y las suma al saldo (nunca pisa lo anterior) — puedes cargar el mismo SKU en varias pasadas o desde varios dispositivos a la vez.
4. La carga masiva alternativa: sube un CSV/Excel con SKU y cantidades por bodega (Configuración, con plantilla descargable) — ideal para el arranque cuando ya existe un conteo digitado.
5. Mientras la carga avanza, la bodega puede operar con inventario negativo: si se pickea algo aún no cargado, el saldo queda negativo y visible en el reporte de Inventarios Negativos; el ajuste posterior (fijar el saldo al conteo real) lo regulariza con auditoría.

Requisito: la bodega debe tener habilitado "Permitir picking con inventario negativo" (Configuración → Bodegas) — es el flag que marca a una bodega como "en proceso de carga inicial".

1. Menú → Almacenamiento. Escanea la etiqueta del bulto (B- o PL-).
2. Escanea la etiqueta de la ubicación física destino (ej: A-01-02).
3. Confirmado: el bulto sale de la genérica y el KPI de "stock sin ubicar" baja en tiempo real.

1. Menú → Picking Manual. Define el documento (tipo de movimiento, folio, bodega, destino si es traslado).
2. Escanea el bulto origen (B- o ID) y la cantidad a extraer hacia el pallet de salida.
3. Extracción parcial: se genera un B- hijo con la cantidad extraída (el padre conserva el saldo). Extracción total: viaja la misma etiqueta.
4. ¿Te equivocaste? El botón deshacer de la sesión revierte la extracción completa: el stock vuelve a su ubicación y bodega originales, con su reversa registrada en Kardex.
5. Al finalizar, el picking se convierte en manifiesto y avanza a packing.

1. Menú → Packing: la cola muestra los manifiestos LISTO_PARA_PACKING.
2. Escanea cada etiqueta B- del manifiesto y asígnala a un pallet PL- (se genera e imprime su etiqueta madre con resumen).
3. ¿Un bulto es muy grande? Fracciona en packing: divide un B- en dos sin salir de la estación (con reversa disponible).
4. Cierra el packing: el manifiesto avanza a DESPACHO.

1. Menú → Despacho: manifiestos en estado DESPACHO listos para salir.
2. Ingresa los datos de transporte (patente, conductor, RUT, transportista — se recuerdan para reutilizar).
3. Confirma: los bultos pasan de EN_PREPARACION a su estado final — EN_TRANSITO (traslados) o DESPACHADO (despachos y retiros) — y se disparan las notificaciones al cliente.

Ciclo de vida completo

Recepción de Traslado

1. Menú → Recepción de Traslado en la bodega destino.
2. Escanea el QR del bulto (PL-): el sistema resuelve el destino desde el manifiesto, deja el stock disponible en la genérica y cierra el manifiesto como RECIBIDO cuando llega el último bulto.
3. Luego ubica con putaway normal. ¿Escaneaste por error? Un supervisor puede anular la recepción (mientras no haya putaway) y el bulto vuelve a tránsito.

Bodegas "solo destino" (sucursales sin BodegApp)

Las bodegas que aún operan con el sistema antiguo se marcan como no operativas en Configuración → Bodegas. Los traslados hacia ellas se auto-recepcionan al confirmar la entrega en ruteo (o por barrido tras 24 h) al estado POR_VERIFICAR: aislado, visible, pero no disponible. Cuando la sucursal se implemente, el asistente de puesta en marcha exige resolver cada ítem uno a uno (✅ a stock / ➗ parcial / ❌ cerrar con motivo) antes de activarla — el día uno parte con inventario real, no heredado.

1. Menú → Fraccionamiento. Escanea el bulto padre (el producto debe estar marcado fraccionable en el maestro).
2. Indica la cantidad a separar y la ubicación destino; personaliza la etiqueta (color, subtítulo, QR).
3. Se genera el B- hijo vinculado al padre. La reversa devuelve la cantidad al padre y anula el hijo conservando su historial.

1. Menú → Inventario Cíclico: crea una sesión de conteo (por bodega, ubicación o SKU).
2. Cuenta físico vs. sistema; las diferencias se muestran al cerrar.
3. El ajuste fija el saldo al conteo real, con movimiento de Kardex y auditoría. La exactitud alimenta el KPI del dashboard (meta world-class: ≥98%).

1. Menú → Consulta de Stock. Busca por SKU, nombre, etiqueta B- o bulto PL-.
2. El resumen agrupa por bodega; toca una tarjeta para el detalle de bultos y ubicaciones.

El stock no disponible se muestra en grupos propios, nunca mezclado con el disponible:

• 📦 En preparación — pickeado en un pallet, aún no despachado (cuenta en su bodega de origen).
• 🚚 En tránsito — viajando, con su destino ("→ Temuco") tomado del manifiesto.
• 📋 Por verificar — auto-recepcionado en sucursal, pendiente de conteo físico.

1. Menú → Kardex. Busca por SKU, nombre, etiqueta B-, bulto PL-, tipo de movimiento o documento.
2. Cada fila muestra tipo, cantidad, bodega/ubicación origen y destino, usuario, fecha y notas.

• Vista Kanban o lista, con filtros por bodega y estado, y refresco automático.
• Acciones por manifiesto: PDF, envío por correo, y para supervisores la reversa ↩️ (retroceder un paso del flujo con motivo).
• Herramientas de supervisión en el encabezado: Desarmar PL-, Anular ingreso, Anular recepción.
• Los flujos de estados son configurables por empresa y tipo de movimiento (Configuración → Flujos).
• Display Público opcional: pantalla para TV de bodega con los manifiestos activos.

• Resumen: movimientos, ocupación, manifiestos, SKUs activos, tipos de movimiento (Entradas/Salidas/Internos por SKUs con movimiento) y estado de manifiestos.
• Productividad: operaciones físicas por operador (recepciones, pickings, posicionamientos, transformaciones) con ranking. Excluye estados, correcciones y cargas del sistema.
• Inventario: unidades por bodega, top SKUs, ocupación de ubicaciones.
• Nivel de Servicio: completitud por tipo de documento.
• KPIs Avanzados: OTIF, tiempo de ciclo recepción→putaway, rotación, stock sin ubicar, edad del stock, líneas/día, exactitud de inventario — con semáforos world-class.

1. Filtros globales: período (por defecto 7 días), bodega y empresa — el consolidado multi-empresa es el default si tienes acceso a varias.
2. Pasa el mouse por el badge ⓘ de cualquier tarjeta o gráfico para ver qué mide y su fórmula exacta.

1. Dashboard → 🎯 Avance ERP. Filtra por bodega, familia o SKU.
2. Tiles: avance global SKU×bodega, SKUs 100% cuadrados, unidades y valorización BodegApp vs ERP (valores resumidos en K/M).
3. Barras duales por bodega, % cuadrado por familia (peor primero) y tabla de mayores diferencias valorizadas.
4. Exporta el detalle a Excel (columnas separadas de stock BodegApp y ERP), con opción de incluir SKUs sin diferencias.

Planificación

1. Menú → Transporte y Ruteo. Toma manifiestos despachables de la cola y créales un documento de transporte con chofer y vehículo.
2. Define por parada: ventana horaria y prioridad (normal/alta/urgente).
3. Optimizar: el motor ordena las paradas minimizando el costo real del recorrido, respetando ventanas y priorizando urgentes. Reordenamiento manual por arrastre disponible (con recálculo de ETAs).

Torre de control

• Mapa en vivo con cada camión (posición GPS del chofer) y cada parada con su ETA.
• Alertas automáticas: sin señal >10 min, ruta atrasada, ritmo lento, ventana en riesgo/perdida, cliente respondió por WhatsApp.
• Paradas fallidas: reprogramar a la cola de despacho o directamente a otra ruta.
• Posición de todos los choferes activos visible según tu alcance de empresa/bodega, tengan o no ruta asignada.

1. El chofer entra con su usuario (rol CHOFER aterriza directo en Mi Ruta) y activa el GPS.
2. Cada parada trae: dirección, contacto (botón llamar), Waze y WhatsApp con iconos oficiales, y el botón "Llegué" (check-in con hora).
3. Entregar: nombre de quien recibe + foto de evidencia + firma. No entregar: motivo tipificado (cliente ausente, dirección incorrecta, rechazado, sin acceso, fuera de horario) + foto.
4. ¿Sin señal? La app encola todo localmente y sincroniza sola al volver la cobertura, con la hora real de cada evento. Banner 📵 y marcadores ⏳ indican lo pendiente.

El mapa que acompaña

• Rotación heading-up: el mapa gira para que el camión siempre apunte hacia arriba, con movimiento continuo (sin saltos).
• Seguimiento inteligente: encuadre automático mientras te mueves; al detenerte más de 10 s, el mapa se libera. Tocar una parada la centra 30 s.
• La pantalla no se bloquea mientras Mi Ruta está activa (Wake Lock).

• Cada parada genera un link único /t/… que se envía por WhatsApp al salir la ruta.
• Muestra: estado (preparando / en ruta / entregado / no entregado), ETA, paradas restantes, quién recibió, y botón "Escríbenos" al WhatsApp de la empresa.
• Mapa en vivo con la posición del vehículo (actualización cada 25 s). El link expira 48 h después de terminado el pedido.

1. Configuración → 💬 WhatsApp (por empresa): URL del conector, API key, canal, número de contacto y las 3 plantillas.
2. Los envíos se disparan solos: al iniciar ruta, al entregar y al fallar — siempre "best-effort" (jamás bloquean la operación).
3. Si el cliente responde, su mensaje queda anotado en la parada y genera la alerta 💬 en la torre de control.

• Ficha completa: SKU, nombre, unidad, proveedor, familia, código de barras, serial genérico, fraccionable, captura de datos, stock mín/máx, foto y PDFs adjuntos.
• Sincronizado con el ERP: precio de lista y stock ERP por bodega se refrescan cada 5 minutos y se muestran en la grilla.
• Fotos desde WooCommerce: Configuración → 🛒 importa las imágenes publicadas en tu tienda cruzando por SKU (normalizadas y livianas). La foto manual siempre puede reemplazarlas.
• Papelera (borrado lógico): eliminar exige stock cero en ambas bases; lo borrado no cuenta en ninguna estadística y es restaurable con su historial íntegro.
• Protecciones: la unidad de medida no se puede cambiar con stock vigente; renombrar un SKU (operación restringida de administración) propaga el cambio al on-premise con auditoría.
• Carga masiva por CSV/Excel con plantilla descargable.

1. Configuración → 🧹 Registros Erróneos. Busca por B-, PL-, SKU o descripción (la grilla muestra la bodega de cada registro).
2. Revisa el detalle (stock, movimientos, manifiestos, genealogía) y elimina de raíz.
3. Si el registro está en estado sensible (en tránsito, despachado, en manifiesto abierto) el sistema lo advierte y sugiere la reversa como vía correcta antes de permitir continuar.
4. El historial de eliminaciones se consulta bajo demanda con filtros (código/SKU/usuario/fechas) y exporta a CSV.

• Panel 🩺 Integridad de datos en Configuración → Registros Erróneos, con ejecución bajo demanda.
• Chequeos: ítems de manifiesto sin etiqueta, paradas sin manifiesto, transitorios >7 días, stock de productos en papelera, tránsitos >7 días sin recepción, negativos en bodegas sin inventario negativo habilitado.
• Guardas estructurales activas: no se puede desactivar/eliminar una bodega con stock; los cambios manuales de estado de manifiesto solo aceptan transiciones válidas del flujo.

• ERP on-premise (dual-write): toda operación se escribe también en APP_STOCK; la sincronización bidireccional corre cada 30 s y los precios/stock ERP cada 5 min desde vistas homologadas por empresa.
• API externa de solo lectura (/api/ext/v1): productos (con precio y stock ERP), stock dual BodegApp+ERP por bodega, bodegas y usuarios. Autenticación por API key con hash, scopes y rate-limit; gestión y rotación desde Configuración.
• Pedidos desde el POS (oomnisale): ingresan como manifiestos. Mientras la integración esté en modo prueba, sus pedidos quedan aislados de KPIs y colas operativas (interruptor OOMNISALE_TEST_MODE).
• WooCommerce: importación de fotos del catálogo por SKU.
• oomnichat: WhatsApp Business API con plantillas y webhook de respuestas.

Las cuatro capas

Flujo de una operación (ejemplo: picking de traslado)

1. Escaneo → la SPA envía la operación al API con el token del usuario.
2. Validación → el API verifica permisos (empresa + bodega + módulo), estado del bulto y saldo.
3. Escritura dual → primero el on-premise (APP_STOCK), luego PostgreSQL en transacción; si el on-premise no calza con lo esperado, la operación aborta sin efectos parciales.
4. Kardex → se registra el movimiento con usuario, origen, destino y documento (append-only).
5. Convergencia → los ciclos de sincronización reconcilian cualquier desfase residual entre bases.

Ciclos automáticos del sistema

Modelo de datos principal

Decisiones de diseño (el porqué)

• On-premise primero, con verificación: en operaciones sensibles (correcciones, reversas, recepciones) se escribe primero la base compartida y se verifica el resultado esperado; si no calza, nada se modifica. Elimina de raíz las divergencias silenciosas.
• Kardex append-only: deshacer = movimiento inverso. El historial de cualquier SKU siempre suma cero contra la realidad — auditable por construcción.
• Idempotencia: las operaciones del chofer offline y las reversas usan guardas de estado — reintentar una operación jamás la duplica.
• Diseño B de traslados: la mercadería pertenece a su bodega de origen hasta la recepción física en destino; el destino viaja en el manifiesto, no en el stock.
• Taxonomía canónica de KPIs: una sola clasificación de movimientos para todos los indicadores, que excluye ruido (estados, correcciones, cargas del sistema, datos de prueba).
• Estados desconocidos = no disponibles: cualquier estado fuera de STOCK/EN_PALLET queda automáticamente fuera del stock vendible — el sistema falla hacia el lado seguro.

Mapa funcional (módulo → capa de datos)

Recepción e Inventario Inicial crean etiquetas · Putaway y Fraccionamiento las reorganizan · Picking/Packing/Despacho las comprometen a un manifiesto · Traslados y Ruteo las mueven entre bodegas y hacia clientes · Recepción de Traslado y las Reversas las devuelven a disponibilidad · Kardex, Consulta de Stock y KPIs las observan sin tocarlas · Corrección e Integridad las gobiernan.

Estados del stock (bultos B-)

Estados del manifiesto (MN-)

LISTO_PARA_PICKING → EN_PICKING → LISTO_PARA_PACKING → PACKING → DESPACHO → EN_TRANSITO / LISTO_PARA_RETIRO → ENTREGADO / RECIBIDO → CERRADO — configurable por empresa y tipo de movimiento. Retroceder es siempre vía reversa supervisada (↩️), un paso a la vez.