LAVALO — Protocolo de Integración de Máquinas

📑 Contenido

Introducción
Autenticación
Máquinas Habilitadas
Endpoints del Fabricante
Webhooks
Diagrama de Estados
Perfil de Marca
Códigos de Error
Testing

1. Introducción

LAVALO es una plataforma abierta que permite a cualquier fabricante de equipos de lavado vehicular integrar sus máquinas. Este documento define el protocolo de integración — el contrato bidireccional entre LAVALO y las máquinas del fabricante.

Flujo de un lavado:

Cliente escanea QR → Elige programa → Paga
      ↓
LAVALO API → POST /machines/:id/start → Máquina del fabricante
                                              ↓
                                         Lavado en curso (countdown)
                                              ↓
Notificación al cliente ← LAVALO API ← Webhook "finished" ← Máquina termina

El Simulador FOMO (ver panel) es la implementación de referencia del protocolo. La marca ficticia "FOMO Equipment" con 3 modelos demuestra cómo integrar máquinas reales.

2. Autenticación

Cada fabricante recibe un API Token único que identifica la marca y da acceso a sus máquinas habilitadas. Todos los endpoints autenticados requieren:

Authorization: Bearer <API_TOKEN>

🔑 Token Demo — Marca FOMO

Usá este token para probar los endpoints con las máquinas FOMO:

fomo-live-token-2026

Marca: FOMO Equipment | País: UY | API Version: 1.0 | Máquinas: 6

Ejemplo curl:

curl -s https://simulator.lavalo.mx/machines \
  -H "Authorization: Bearer fomo-live-token-2026"

Respuestas de error:

Status	Error	Causa
`401`	Token requerido	Falta el header Authorization
`401`	Token inválido	Token no reconocido
`403`	Sin acceso	La máquina no pertenece a tu marca

3. Máquinas Habilitadas

Con el token FOMO tenés acceso a estas 6 máquinas:

FOMO-TUN-001

Túnel de Lavado #1

Modelo: FW-100 (TunnelPro 3000) | Tipo: tunnel

FOMO-TUN-002

Túnel de Lavado #2

Modelo: FW-100 (TunnelPro 3000) | Tipo: tunnel

FOMO-VAC-001

Aspiradora #1

Modelo: FV-200 (VacuumMax 500) | Tipo: vacuum

FOMO-VAC-002

Aspiradora #2

Modelo: FV-200 (VacuumMax 500) | Tipo: vacuum

FOMO-DRY-001

Secadora #1

Modelo: FD-300 (DryWind 200) | Tipo: dryer

FOMO-PRE-001

Lavado Premium #1

Modelo: FW-100 (TunnelPro 3000) | Tipo: premium

4. Endpoints

GET /machines Lista las máquinas de tu marca

Request

curl -s https://simulator.lavalo.mx/machines \
  -H "Authorization: Bearer fomo-live-token-2026"

Response (200)

[
  {
    "id": "FOMO-TUN-001",
    "name": "Túnel de Lavado #1",
    "type": "tunnel",
    "brandId": "fomo",
    "model": "FW-100",
    "status": "idle",
    "program": null,
    "duration": 0,
    "timeLeft": 0,
    "startedAt": null,
    "operationId": null,
    "completedCount": 0
  },
  ...
]

GET /machines/:id/status Estado actual de una máquina

Request

curl -s https://simulator.lavalo.mx/machines/FOMO-TUN-001/status \
  -H "Authorization: Bearer fomo-live-token-2026"

Response (200)

{
  "id": "FOMO-TUN-001",
  "name": "Túnel de Lavado #1",
  "type": "tunnel",
  "status": "idle",
  "program": null,
  "timeLeft": 0,
  "completedCount": 3
}

GET /machines/:id/info Información del equipo (modelo, capabilities)

Request

curl -s https://simulator.lavalo.mx/machines/FOMO-TUN-001/info \
  -H "Authorization: Bearer fomo-live-token-2026"

Response (200)

{
  "machineId": "FOMO-TUN-001",
  "brand": "FOMO Equipment",
  "model": "FW-100",
  "modelName": "TunnelPro 3000",
  "type": "tunnel",
  "capabilities": ["cold_water", "hot_water", "foam", "wax", "drying"],
  "programs": [...],
  "firmwareVersion": "2.1.0",
  "apiVersion": "1.0"
}

POST /machines/:id/start Iniciar lavado

Request

curl -s -X POST https://simulator.lavalo.mx/machines/FOMO-TUN-001/start \
  -H "Authorization: Bearer fomo-live-token-2026" \
  -H "Content-Type: application/json" \
  -d '{
    "program": "Estándar",
    "duration": 300,
    "operationId": "op-uuid-123"
  }'

Body

Campo	Tipo	Requerido	Descripción
`program`	string	sí	Nombre del programa: Básico, Estándar, Premium, Completo
`duration`	number	no	Duración en segundos (default: según programa)
`operationId`	string	no	ID de la operación en LAVALO (para tracking)

Response (200)

{ "ok": true, "machine": { "id": "FOMO-TUN-001", "status": "washing", "program": "Estándar", ... } }

Errores

Status	Error	Causa
`400`	machine_busy	La máquina ya está lavando
`404`	not_found	Máquina no existe

POST /machines/:id/stop Parada de emergencia

Request

curl -s -X POST https://simulator.lavalo.mx/machines/FOMO-TUN-001/stop \
  -H "Authorization: Bearer fomo-live-token-2026"

Response (200)

{ "ok": true, "machine": { "id": "FOMO-TUN-001", "status": "idle", ... } }

GET /brand Información de tu marca y máquinas

Request

curl -s https://simulator.lavalo.mx/brand \
  -H "Authorization: Bearer fomo-live-token-2026"

Response (200)

{
  "brandId": "fomo",
  "name": "FOMO Equipment",
  "country": "UY",
  "apiVersion": "1.0",
  "models": {
    "FW-100": { "name": "TunnelPro 3000", "type": "tunnel", "capabilities": [...] },
    "FV-200": { "name": "VacuumMax 500", "type": "vacuum", "capabilities": [...] },
    "FD-300": { "name": "DryWind 200", "type": "dryer", "capabilities": [...] }
  },
  "machines": [...]
}

GET /programs Programas de lavado disponibles (público)

curl -s https://simulator.lavalo.mx/programs

Response

[
  { "id": "basico", "name": "Básico", "duration": 180, "capabilities": ["cold_water"], "suggestedPrice": 15.00 },
  { "id": "estandar", "name": "Estándar", "duration": 300, "capabilities": ["cold_water","foam"], "suggestedPrice": 22.00 },
  { "id": "premium", "name": "Premium", "duration": 480, "capabilities": ["hot_water","foam","wax"], "suggestedPrice": 38.00 },
  { "id": "completo", "name": "Completo", "duration": 720, "capabilities": ["hot_water","foam","wax","drying","underbody"], "suggestedPrice": 72.00 }
]

5. Webhooks (Eventos de la Máquina → LAVALO)

La máquina envía eventos a LAVALO vía HTTP POST. En producción, el fabricante configura la URL del webhook de LAVALO.

Headers requeridos:

Authorization: Bearer <API_TOKEN>
Content-Type: application/json
X-Machine-Id: FOMO-TUN-001
X-Event-Type: machine.finished
X-Timestamp: 2026-04-03T01:00:00Z

machine.heartbeat

Enviado cada 30 segundos. Confirma que la máquina está online.

{
  "event": "machine.heartbeat",
  "machineId": "FOMO-TUN-001",
  "status": "idle",
  "metrics": { "temperature": 25.5, "waterPressure": 3.2, "waterLevel": 85 },
  "timestamp": "2026-04-03T01:00:00Z"
}

machine.started

Cuando la máquina confirma que arrancó el lavado.

{
  "event": "machine.started",
  "machineId": "FOMO-TUN-001",
  "operationId": "op-uuid-123",
  "program": "Estándar",
  "duration": 300,
  "timestamp": "2026-04-03T01:00:00Z"
}

machine.progress

Cada 30 segundos durante el lavado.

{
  "event": "machine.progress",
  "machineId": "FOMO-TUN-001",
  "operationId": "op-uuid-123",
  "phase": "soap",
  "progress": 65,
  "timeLeft": 105,
  "timestamp": "2026-04-03T01:02:00Z"
}

machine.finished

Cuando el lavado termina exitosamente.

{
  "event": "machine.finished",
  "machineId": "FOMO-TUN-001",
  "operationId": "op-uuid-123",
  "program": "Estándar",
  "actualDuration": 298,
  "metrics": { "waterUsedLiters": 45.2, "energyUsedKwh": 1.8 },
  "timestamp": "2026-04-03T01:05:00Z"
}

machine.error

Cuando ocurre un error.

{
  "event": "machine.error",
  "machineId": "FOMO-TUN-001",
  "operationId": "op-uuid-123",
  "errorCode": "E001",
  "errorMessage": "Presión de agua baja",
  "severity": "critical",
  "timestamp": "2026-04-03T01:03:00Z"
}

6. Diagrama de Estados

        ┌───────────┐
   ┌───→│   IDLE    │←───────────────────┐
   │    │  (libre)  │                    │
   │    └─────┬─────┘                    │
   │          │ POST /start              │ auto-reset (10s)
   │          ▼                          │
   │    ┌───────────┐             ┌──────┴──────┐
   │    │  WASHING  │────────────→│  FINISHED   │
   │    │ (lavando) │  timeLeft=0 │ (terminado) │
   │    └─────┬─────┘             └─────────────┘
   │          │ error
   │          ▼
   │    ┌───────────┐
   └────│   ERROR   │
        │  (falla)  │
        └───────────┘

Transiciones válidas:
  idle → washing     (POST /start)
  washing → finished (countdown llega a 0)
  washing → idle     (POST /stop — emergencia)
  washing → error    (falla de hardware)
  finished → idle    (auto-reset después de 10s)
  error → idle       (reset manual)

7. Perfil de Marca

Cada fabricante se registra con un perfil que describe su marca, modelos, y capabilities.

Marca: FOMO Equipment

Campo	Valor
Brand ID	`fomo`
Nombre	FOMO Equipment
País	Uruguay (UY)
API Version	1.0

Modelos

Modelo	Nombre	Tipo	Capabilities
`FW-100`	TunnelPro 3000	tunnel	cold_water, hot_water, foam, wax, drying
`FV-200`	VacuumMax 500	vacuum	interior_vacuum, fragrance
`FD-300`	DryWind 200	dryer	drying

Capabilities disponibles

ID	Descripción
`cold_water`	Agua fría
`hot_water`	Agua caliente
`foam`	Espuma activa
`wax`	Cera protectora
`drying`	Secado por aire
`underbody`	Lavado de chasis
`wheels`	Lavado de ruedas
`interior_vacuum`	Aspirado interior
`fragrance`	Aromatización

8. Códigos de Error

Código	Descripción	Severidad
`E001`	Presión de agua baja	critical
`E002`	Falla en bomba de agua	fatal
`E003`	Nivel de jabón bajo	warning
`E004`	Falla en motor de cepillos	critical
`E005`	Sensor de presencia fallido	critical
`E006`	Sobrecalentamiento	fatal
`E010`	Timeout de comunicación	warning
`E011`	Falla de red	warning
`E020`	Nivel de cera bajo	warning
`E099`	Error desconocido	critical

Severidades:

warning — La máquina puede seguir operando. Notificar al operador.
critical — La máquina debe detenerse. Se cancela la operación en curso.
fatal — La máquina pasa a offline. Requiere intervención técnica.

9. Testing y Certificación

Antes de conectar máquinas reales a LAVALO, el fabricante debe:

Implementar todos los endpoints — GET /status, POST /start, POST /stop, GET /info
Implementar webhooks — heartbeat, started, progress, finished, error
Pasar la suite de certificación — LAVALO provee una suite de tests automatizados
Probar en sandbox — Conectar al ambiente de testing de LAVALO
Recibir aprobación — El equipo LAVALO certifica la integración

Test rápido con curl:

# 1. Verificar autenticación
curl -s https://simulator.lavalo.mx/machines \
  -H "Authorization: Bearer fomo-live-token-2026"

# 2. Iniciar un lavado
curl -s -X POST https://simulator.lavalo.mx/machines/FOMO-TUN-001/start \
  -H "Authorization: Bearer fomo-live-token-2026" \
  -H "Content-Type: application/json" \
  -d '{"program":"Básico","duration":180}'

# 3. Verificar estado
curl -s https://simulator.lavalo.mx/machines/FOMO-TUN-001/status \
  -H "Authorization: Bearer fomo-live-token-2026"

# 4. Parada de emergencia
curl -s -X POST https://simulator.lavalo.mx/machines/FOMO-TUN-001/stop \
  -H "Authorization: Bearer fomo-live-token-2026"

LAVALO — Protocolo de Integración de Máquinas v1.0 | Abril 2026
Volver al Panel | lavalo.mx

LAVALO — Protocolo de Integración v1.0

📑 Contenido

1. Introducción

2. Autenticación

🔑 Token Demo — Marca FOMO

Ejemplo curl:

Respuestas de error:

3. Máquinas Habilitadas

4. Endpoints

Request

Response (200)

Request

Response (200)

Request

Response (200)

Request

Body

Response (200)

Errores

Request

Response (200)

Request

Response (200)

Response

5. Webhooks (Eventos de la Máquina → LAVALO)

Headers requeridos:

machine.heartbeat

machine.started

machine.progress

machine.finished

machine.error

6. Diagrama de Estados

7. Perfil de Marca

Marca: FOMO Equipment

Modelos

Capabilities disponibles

8. Códigos de Error

Severidades:

9. Testing y Certificación

Test rápido con curl: