checklist/docs/webhook-n8n.md

# Documentación de Webhook - n8n

## Endpoint
El endpoint configurado en `.env`:
```
NOTIFICACION_ENDPOINT=https://n8nw.comercialarmin.com.py/webhook/53284540-edc4-418f-b1bf-a70a805f8212
```

## Evento: Inspección Completada

### Cuándo se envía
Cuando se completa una inspección (endpoint: `POST /api/inspections/{id}/complete`)

### Estructura del JSON

```json
{
  "tipo": "inspeccion_completada",
  "inspeccion": {
    "id": 123,
    "estado": "completed",
    "or_number": "OR-001",
    "work_order_number": "WO-123",
    "vehiculo": {
      "placa": "ABC-123",
      "marca": "Toyota",
      "modelo": "Corolla 2020",
      "kilometraje": 50000
    },
    "cliente": "Juan Pérez",
    "mecanico": {
      "id": 5,
      "nombre": "Carlos Méndez",
      "email": "carlos@example.com",
      "codigo_operario": "OPR-001"
    },
    "checklist": {
      "id": 1,
      "nombre": "Inspección Vehicular Completa"
    },
    "puntuacion": {
      "obtenida": 85,
      "maxima": 100,
      "porcentaje": 85.0,
      "items_criticos": 2
    },
    "fechas": {
      "inicio": "2025-11-26T10:30:00",
      "completado": "2025-11-26T11:45:00"
    },
    "pdf_url": "https://minioapi.ayutec.es/pdfs/2025/11/inspeccion_123_ABC-123.pdf",
    "firma": "data:image/png;base64,..."
  },
  "respuestas": [
    {
      "id": 1,
      "pregunta": {
        "id": 10,
        "texto": "¿Estado de los neumáticos?",
        "seccion": "Neumáticos",
        "orden": 1
      },
      "respuesta": "ok",
      "estado": "ok",
      "comentario": "Neumáticos en buen estado",
      "observaciones": "Presión correcta en las 4 ruedas",
      "puntos_obtenidos": 1,
      "es_critico": false,
      "imagenes": [
        {
          "id": 100,
          "url": "https://minioapi.ayutec.es/images/2025/11/foto1.jpg",
          "filename": "neumatico_delantero.jpg"
        },
        {
          "id": 101,
          "url": "https://minioapi.ayutec.es/images/2025/11/foto2.jpg",
          "filename": "neumatico_trasero.jpg"
        }
      ],
      "ai_analysis": {
        "status": "ok",
        "observations": "Los neumáticos presentan un desgaste uniforme...",
        "recommendation": "Continuar con el mantenimiento preventivo",
        "confidence": 0.95
      }
    },
    {
      "id": 2,
      "pregunta": {
        "id": 11,
        "texto": "¿Luces delanteras funcionan?",
        "seccion": "Iluminación",
        "orden": 2
      },
      "respuesta": "warning",
      "estado": "warning",
      "comentario": "Faro izquierdo opaco",
      "observaciones": "Requiere restauración de faro",
      "puntos_obtenidos": 0.5,
      "es_critico": true,
      "imagenes": [
        {
          "id": 102,
          "url": "https://minioapi.ayutec.es/images/2025/11/foto3.jpg",
          "filename": "faro_izquierdo.jpg"
        }
      ],
      "ai_analysis": {
        "status": "minor",
        "observations": "Se detecta opacidad en el faro izquierdo...",
        "recommendation": "Pulir o restaurar el lente del faro",
        "confidence": 0.9
      }
    }
  ],
  "timestamp": "2025-11-26T11:45:30.123456"
}
```

## Campos Importantes

### Imágenes
- Cada respuesta incluye un array `imagenes` con:
  - `id`: ID del archivo en la base de datos
  - `url`: **URL directa** de la imagen en MinIO (lista para descargar/mostrar)
  - `filename`: Nombre original del archivo

### AI Analysis
- Si la pregunta fue analizada por IA, incluye:
  - `status`: ok/minor/critical
  - `observations`: Observaciones del análisis
  - `recommendation`: Recomendaciones
  - `confidence`: Nivel de confianza (0-1)

### Código de Operario
- Se incluye en `inspeccion.mecanico.codigo_operario`
- Se copia automáticamente del perfil del mecánico al crear la inspección

### PDF
- URL del PDF generado en `inspeccion.pdf_url`
- Incluye miniaturas de todas las imágenes

## Uso en n8n

### 1. Webhook Trigger
Configura un nodo Webhook con la URL del archivo `.env`

### 2. Filtrar por tipo
```javascript
// Verificar si es una inspección completada
{{ $json.tipo === "inspeccion_completada" }}
```

### 3. Acceder a las imágenes
```javascript
// Obtener todas las URLs de imágenes
{{ $json.respuestas.map(r => r.imagenes.map(i => i.url)).flat() }}

// Primera imagen de cada respuesta
{{ $json.respuestas.map(r => r.imagenes[0]?.url) }}

// Imágenes de respuestas críticas
{{ $json.respuestas.filter(r => r.es_critico).map(r => r.imagenes).flat() }}
```

### 4. Descargar imágenes
Las URLs son públicas y directas, se pueden:
- Descargar con HTTP Request
- Enviar por email como adjuntos
- Procesar con Computer Vision
- Subir a otro servicio (Google Drive, Dropbox, etc.)

### 5. Ejemplo: Enviar por email
```javascript
// En un nodo Email
To: {{ $json.inspeccion.cliente_email }}
Subject: Inspección Completada - {{ $json.inspeccion.vehiculo.placa }}
Attachments: {{ $json.inspeccion.pdf_url }}
```

## Logs
El backend imprime logs detallados:
```
🚀 Enviando inspección #123 a n8n...
📤 Enviando 15 respuestas con imágenes a n8n...
✅ Inspección #123 enviada exitosamente a n8n
   - 15 respuestas
   - 23 imágenes
```

## Seguridad
- El webhook es HTTPS
- Las URLs de imágenes son públicas en MinIO
- No se envían passwords ni tokens
- Se incluyen solo datos relevantes de la inspección