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

{
  "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

// Verificar si es una inspección completada
{{ $json.tipo === "inspeccion_completada" }}

3. Acceder a las imágenes

// 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

// 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