Inicio Rápido

Paso 1 — Registrar tu empresa

Ingresa a Balam IoT.com y haz clic en Solicitar Acceso. Completa el formulario con los datos de tu empresa (nombre, RFC, cargo y teléfono). Recibirás un correo de verificación en minutos.

Paso 2 — Crear tu primera Planta

1. 1

   Accede al Superadmin

   Una vez verificado, inicia sesión y ve a Superadmin → Plantas. Haz clic en Nueva Planta.

2. 2

   Define nombre y ubicación

   Ingresa el nombre de tu planta (ej. "Planta Monterrey"), la ciudad y la zona horaria correcta.

3. 3

   Agrega procesos y máquinas

   Dentro de la planta, crea los Procesos (líneas de producción) y dentro de cada proceso, agrega las Máquinas a monitorear.

4. 4

   Conecta sensores

   Cada máquina recibe un ID único. Configura tu dispositivo para enviar datos a ese ID. Ver guía completa en Conectar Sensores.

Paso 3 — Verificar datos en vivo

Cuando el sensor esté enviando datos, ve a Vista de Proceso o Vista de Planta. Los indicadores cambiarán de gris a verde y los valores se actualizarán en tiempo real cada pocos segundos.

Arquitectura de Balam IoT

Modelo de datos

Balam IoT usa un modelo jerárquico multi-tenant donde cada empresa opera en su propio espacio aislado:

# Jerarquía de Balam IoT
Tenant (Empresa)
  └── Planta (Ubicación física)
        └── Proceso (Línea de producción)
              └── Máquina (Activo industrial)
                    └── Sensor (Variable física)

Seguridad y aislamiento

• Cada tenant tiene su propio namespace de datos — ningún tenant puede ver datos de otro.
• Los tokens JWT incluyen el tenant_id y user_id, validados en cada request.
• Los webhooks de entrada están protegidos con HMAC-SHA256.
• Las claves de Edge Agents viajan solo en headers HTTP, nunca en URLs o body.

Panel de Inicio

Panel de inicio con KPIs de negocio y gráficas de P&L, pipeline CRM y margen por división.

Métricas de negocio

El dashboard principal muestra indicadores clave de desempeño sincronizados con tu ERP (Odoo) a través del flujo de automatización n8n:

Vistas disponibles

El dashboard tiene dos pestañas principales:

• Negocio — P&L mensual, ventas por división, pipeline CRM, top clientes, margen por división.
• Operaciones — OEE de líneas, alertas activas, estado de máquinas, producción del día.

Selector de planta

Si tu empresa tiene múltiples plantas, usa el selector en la parte superior del sidebar para cambiar entre ellas. Los KPIs y vistas se filtran automáticamente a la planta seleccionada.

Vista de Planta

Vista de planta mostrando los procesos y zonas con indicadores de estado en tiempo real.

¿Qué muestra?

La Vista de Planta es una representación visual del floor layout de tu instalación industrial. Cada área o proceso se muestra como un bloque con indicadores de estado:

Interacción

• Clic en un proceso — abre el detalle con las máquinas y sensores de ese proceso.
• Hover sobre una máquina — muestra el último valor registrado de cada sensor.
• Botón de configuración — permite editar nombre, posición y parámetros del proceso (requiere rol Administrador).

Personalizar el layout

Puedes arrastrar y soltar los bloques de proceso para que el mapa refleje la distribución real de tu planta. Los cambios se guardan automáticamente y son visibles para todos los usuarios de tu tenant.

Vista de Proceso

Vista de proceso con lecturas en tiempo real de temperatura, presión, velocidad y variables de producción.

Datos disponibles

Para cada máquina, la Vista de Proceso muestra:

• Valor actual de cada sensor con unidad de medida
• Tendencia — si el valor sube, baja o está estable
• Estado — normal, alerta o crítico según los umbrales configurados
• Última actualización — timestamp del último dato recibido
• Gráfica histórica — los últimos 60 minutos de datos (expandible)

Tipos de sensores soportados

Historial y análisis

Haz clic en cualquier sensor para expandir su gráfica. Puedes seleccionar rangos de tiempo: última hora, 8 horas, 24 horas, 7 días o rango personalizado. Los datos históricos se almacenan con compresión de series de tiempo para máxima eficiencia.

Alertas

Panel de alertas con historial de incidentes, severidad y tiempo de respuesta.

Tipos de alertas

Crear una regla de alerta

1. 1

   Ir a Reglas

   En el sidebar, ve a Reglas bajo el grupo de Producción.

2. 2

   Seleccionar sensor

   Elige la planta, proceso, máquina y sensor que quieres monitorear.

3. 3

   Definir condición

   Establece el operador (>, <, ==, !=) y el valor umbral.

4. 4

   Configurar notificación

   Elige cómo notificar: dentro de la plataforma, por email, WhatsApp (vía n8n) o webhook externo.

Gestionar alertas activas

En el panel de Alertas puedes:

• Reconocer una alerta — indica que el equipo ya la vio y está trabajando en ella.
• Cerrar una alerta — marca el incidente como resuelto con una nota de causa raíz.
• Escalar — envía la alerta a un supervisor o técnico específico.

Tareas

Panel de tareas con vista kanban, asignación de responsables y estados de avance.

Tipos de tareas

Estados del flujo de trabajo

Las tareas siguen un flujo kanban: Pendiente → En proceso → En revisión → Completada.

Asignación y prioridad

• Cada tarea puede asignarse a un usuario o equipo específico.
• Se puede establecer una fecha límite y un nivel de prioridad (baja, media, alta, crítica).
• Las tareas vencidas aparecen resaltadas en rojo automáticamente.
• Los usuarios asignados reciben una notificación al ser designados.

Crear una tarea manualmente

Haz clic en + Nueva Tarea, selecciona el tipo, la máquina relacionada, asigna responsable y define la fecha límite. Las tareas también pueden crearse automáticamente cuando una alerta se reconoce o cierra.

Equipos Críticos

Lista de equipos críticos con OEE, MTBF y historial de fallas por máquina.

¿Qué es un equipo crítico?

Son las máquinas cuya falla impacta directamente la producción o seguridad. Balam IoT los monitorea con métricas avanzadas de confiabilidad industrial:

Ficha de equipo

Al hacer clic en un equipo, se abre su ficha completa con:

• Datos técnicos: marca, modelo, número de serie, fecha de instalación.
• Historial de fallas con causa raíz y tiempo de reparación.
• Próximas actividades de mantenimiento preventivo.
• Documentación adjunta: manuales, planos, garantías.
• Sensores vinculados y su estado actual.

Marcar un equipo como crítico

Ve a Vista de Planta → Proceso → Máquina, haz clic en editar y activa la opción "Equipo Crítico". La máquina aparecerá en este panel con monitoreo prioritario.

Flotilla GPS

Módulo de flotilla con mapa en vivo, vehículos, conductores y geofencias activas.

Funcionalidades principales

Agregar un vehículo

1. 1

   Ir a Flotilla → Vehículos

   Haz clic en + Nuevo Vehículo.

2. 2

   Ingresar datos

   Número de serie/placa, marca, modelo, año y unidad GPS asignada.

3. 3

   Configurar dispositivo GPS

   El sistema te proporcionará el endpoint y token para configurar el dispositivo rastreador.

4. 4

   Asignar conductor

   Vincula un conductor al vehículo. El sistema registrará los viajes bajo ese conductor.

Crear un Geofence

En el mapa, haz clic en + Geofence y dibuja el polígono delimitando la zona. Define el nombre, tipo (entrada/salida/ambos) y el nivel de alerta. Cuando un vehículo cruce la geofence, el sistema notificará automáticamente.

Usuarios y Permisos

Roles disponibles

Crear un usuario

1. 1

   Ir a Configuración → Usuarios

   Solo los Admins tienen acceso a esta sección.

2. 2

   Completar datos

   Nombre, correo electrónico, rol y plantas a las que tendrá acceso.

3. 3

   Enviar invitación

   El usuario recibirá un correo con enlace para crear su contraseña y activar su cuenta.

Acceso por planta

Un usuario puede tener acceso a una o varias plantas. Si tiene acceso a múltiples plantas, puede cambiar entre ellas con el selector en la parte superior del sidebar. El rol se aplica por igual en todas las plantas asignadas.

Auditoría de accesos

Cada acción relevante (crear, editar, eliminar registros; reconocer alertas; cerrar tareas) queda registrada con usuario, timestamp y descripción. Los logs de auditoría están disponibles para Admins en Configuración → Auditoría.

Panel Superadmin

Panel de Superadmin con gestión de empresas, planes activos y métricas de la plataforma.

Funciones del Superadmin

Planes disponibles

Conectar Sensores

Opción 1 — HTTP directo (más simple)

Envía un POST HTTP desde cualquier microcontrolador o PLC con conectividad a internet:

# Ejemplo: enviar temperatura desde ESP32 o PLC
POST https://api.Balam IoT.com/api/v1/sensors/ingest
Content-Type: application/json
X-Edge-ID: maquina_001
X-Edge-Key: tu_api_key_aqui

{
  "sensor_id": "temp_interior",
  "value": 165.3,
  "unit": "°C",
  "timestamp": "2026-06-21T14:30:00Z"
}

Opción 2 — MQTT (recomendado para IoT)

Para instalaciones con muchos sensores, usa MQTT. Publica en el topic asignado a tu máquina:

# Topic format: Balam IoT/{tenant_id}/{planta_id}/{maquina_id}/{sensor_id}
mosquitto_pub \
  -h mqtt.Balam IoT.com \
  -p 8883 \
  -t "Balam IoT/tu-tenant/planta-01/maquina-001/temperatura" \
  -u "tu_mqtt_user" \
  -P "tu_mqtt_pass" \
  -m '{"value": 165.3, "unit": "°C"}'

Opción 3 — Edge Agent (offline-first)

Para plantas sin conexión a internet continua o con redes industriales aisladas, instala el Balam IoT Edge Agent en un servidor local (Raspberry Pi, PC industrial):

• El Edge Agent colecta datos localmente y los sincroniza en batch cuando hay conexión.
• Soporta protocolos industriales: Modbus TCP, Modbus RTU, OPC-UA.
• Se configura con un archivo agent.yml que define qué registros leer y con qué frecuencia.

# agent.yml — ejemplo Modbus TCP
tenant_id: tu-tenant
planta_id: planta-monterrey
api_key: tu_api_key_aqui

sources:
  - type: modbus_tcp
    host: 192.168.1.50
    port: 502
    registers:
      - address: 40001
        sensor_id: temperatura_horno
        unit: °C
        scale: 0.1
        interval_sec: 5

Integración n8n

¿Qué es n8n?

n8n es una plataforma de automatización visual tipo "low-code" que permite conectar Balam IoT con cientos de servicios externos: WhatsApp, email, Odoo, Slack, Google Sheets, bases de datos, y más.

Casos de uso con Balam IoT

Webhook de alertas

Balam IoT envía un webhook firmado a tu n8n cuando ocurre una alerta. Cada solicitud incluye el header X-Balam IoT-Signature con la firma HMAC-SHA256 para que puedas verificar su autenticidad:

# Payload de webhook de alerta
{
  "event": "alert.triggered",
  "alert_id": "alrt_abc123",
  "severity": "critical",
  "sensor_id": "temp_horno_01",
  "value": 204.5,
  "threshold": 200,
  "planta": "Planta Mazatlán",
  "maquina": "Horno Electrostático #1",
  "timestamp": "2026-06-21T14:35:00Z"
}

Configurar el webhook en Balam IoT

1. 1

   Crear workflow en n8n

   Agrega un nodo Webhook en tu n8n con método POST. Copia la URL generada.

2. 2

   Registrar en Balam IoT

   Ve a Configuración → Webhooks y pega la URL de n8n. Define los eventos que quieres recibir.

3. 3

   Verificar firma

   En n8n, valida el header X-Balam IoT-Signature con tu webhook secret para garantizar la autenticidad.

API Reference

Autenticación

Balam IoT usa JWT (JSON Web Tokens) para autenticar todas las solicitudes. Obtén un token haciendo login:

POST /api/v1/auth/login
Content-Type: application/json

{
  "email": "admin@tuempresa.com",
  "password": "tu_password"
}

# Respuesta
{
  "access_token": "eyJhbGci...",
  "token_type": "bearer",
  "expires_in": 86400
}

Incluye el token en todas las solicitudes posteriores:

Authorization: Bearer eyJhbGci...

Endpoints principales

Códigos de error

Rate Limits

La API tiene los siguientes límites por plan:

Integración con Odoo

¿Qué se sincroniza?

Configurar la integración

1. 1

   Obtener API Key de Odoo

   En Odoo ve a Configuración → Usuarios → tu perfil → API Keys y genera una nueva clave.

2. 2

   Configurar en Balam IoT

   Ve a Configuración → Integraciones → Odoo. Ingresa la URL de tu instancia, nombre de base de datos, usuario y API Key.

3. 3

   Activar sincronización

   Selecciona qué módulos sincronizar (Ventas, CRM, Contabilidad) y la frecuencia (cada hora o en tiempo real vía n8n).

4. 4

   Verificar en Dashboard

   Los KPIs del dashboard deberían actualizarse en la próxima ejecución del sync.

Sincronización vía n8n (recomendado)

Para sincronización en tiempo real, usa un workflow de n8n que:

1. Escucha eventos de Odoo (nuevo pedido, lead actualizado, factura emitida)
2. Consulta los datos vía la API de Odoo
3. Envía los datos actualizados a la API de Balam IoT (POST /api/v1/dashboard/kpis)