Crea un flujo fiable de extracción de datos en n8n con validación de JSON Schema
Diseña en n8n un flujo de extracción que valide las respuestas estructuradas del modelo, reintente los fallos transitorios y derive los registros dudosos o no válidos a revisión humana.
Resumen · TL;DR
Un flujo de extracción robusto trata la salida del modelo como entrada no confiable. Define un contrato JSON acotado, valida el resultado parseado antes de guardarlo, reintenta solo los fallos transitorios y deriva a una persona los casos sin resolver o de alto impacto.
Puntos clave
- Pide un único objeto JSON predecible y valídalo de forma independiente del modelo.
- Distingue los fallos transitorios de la API de los resultados de extracción malformados o incompletos.
- Limita los reintentos y conserva el registro de origen para evitar duplicados al volver a ejecutar el flujo.
- La revisión humana es especialmente importante antes de acciones trascendentes; n8n permite aprobar herramientas seleccionadas del AI Agent.
- Conserva un registro de auditoría del origen, el resultado extraído, los errores de validación, la cantidad de intentos y la decisión del revisor.
En esta página (7)
La decisión de diseño: valida antes de actuar
Que un modelo devuelva JSON con una apariencia válida no demuestra que los datos estén completos, tengan los tipos correctos o sean seguros de usar. En n8n, trata la extracción como un flujo con un contrato claro: recopila un registro de origen, solicita un resultado estructurado, procésalo y valídalo; después, continúa, reintenta o envíalo a revisión. No conectes directamente la salida del modelo a una actualización de base de datos ni a un mensaje externo.
Este artículo utiliza como ejemplo ilustrativo un registro similar a una factura. El esquema y la configuración de los nodos son ejemplos, no una exportación probada ni específica de una versión de n8n. Comprueba las opciones disponibles en los nodos de tu versión de n8n y el formato de salida que admite el endpoint del modelo elegido.
1. Define primero el contrato de salida
Limita el esquema a los campos que realmente necesita el siguiente paso. Especifica los campos obligatorios, usa tipos estables y decide cómo representar la información ausente. Por ejemplo, una fecha de factura que falta debería ser null, no una fecha inventada ni una explicación en texto libre.
{
"type": "object",
"additionalProperties": false,
"required": ["invoice_number", "invoice_date", "currency", "total"],
"properties": {
"invoice_number": { "type": "string", "minLength": 1 },
"invoice_date": { "type": ["string", "null"] },
"currency": { "type": "string", "minLength": 3, "maxLength": 3 },
"total": { "type": "number", "minimum": 0 }
}
}
El esquema expresa reglas estructurales; no puede determinar si el total extraído coincide con el documento de origen. Añade por separado comprobaciones de dominio, como verificar que una fecha se pueda procesar o que un código de moneda esté en la lista de valores aceptados. No conviertas silenciosamente valores inesperados: convertir un importe en texto a número puede ser útil, pero registra la conversión y rechaza los formatos ambiguos.
2. Organiza el flujo de n8n por etapas
Una estructura práctica para el lienzo es:
- Activador y recuperación del origen: acepta un archivo, un registro o una carga útil de webhook. Asigna un ID de origen estable y conserva el texto original o una referencia a él.
- Solicitud de extracción: envía el texto y una instrucción concisa al modelo elegido. Solicita únicamente el objeto definido e indica que los valores dudosos o ausentes deben representarse según lo especificado en el contrato.
- Análisis y validación: procesa la respuesta como JSON y comprueba las claves obligatorias, los tipos, los valores permitidos y las reglas de negocio. Usa un nodo de validación de esquemas si está disponible en tu configuración o un nodo Code con un validador que hayas instalado y probado deliberadamente. No des por hecho que todos los entornos de n8n incluyen un paquete de validación concreto.
- Enrutamiento según el resultado: los registros válidos continúan hacia el destino; los fallos que admiten reintento pasan por una ruta con límite de intentos; los fallos de validación persistentes y los casos ambiguos se envían a revisión.
- Registro del resultado: guarda el ID de origen, el estado, el objeto extraído, los errores de validación, la cantidad de intentos y la decisión final.
Mantén la validación fuera de la solicitud al modelo. Las instrucciones del prompt pueden mejorar la respuesta, pero no sustituyen su comprobación.
3. Reintenta los fallos adecuados
Los reintentos ayudan con errores temporales de transporte, límites de solicitudes o fallos del servicio. No solucionan un número de factura ausente ni una respuesta que incumple repetidamente el esquema. Configura un límite bajo de reintentos y, si el nodo lo permite, una pausa entre intentos. Confirma los controles de reintento exactos de tu versión de n8n: la configuración y el comportamiento pueden variar según el nodo.
Usa rutas separadas para los distintos resultados:
- Error transitorio de solicitud: reintenta hasta alcanzar el límite y, después, marca el registro como fallido para investigarlo más adelante.
- JSON no válido: si resulta útil, permite un intento de reparación controlado y pide los mismos campos conforme al mismo contrato. Vuelve a validar la nueva respuesta; no des por hecho que la reparación funcionó.
- Fallo de esquema o de reglas de negocio: envíalo a revisión en lugar de repetir el proceso indefinidamente.
- Resultado válido: continúa hacia el destino y usa el ID de origen para evitar escrituras duplicadas si se vuelve a ejecutar el flujo.
Un reintento no debería repetir una acción posterior irreversible. Mantén la extracción del modelo y la escritura de datos en etapas separadas, y haz que la escritura sea idempotente cuando sea posible.
4. Añade revisión humana donde reduzca el riesgo
La revisión humana resulta útil cuando un valor es ambiguo, falla una regla de validación o la acción siguiente tiene consecuencias importantes. Proporciona al revisor el origen original, los campos propuestos, los errores de validación concretos y opciones claras para aprobar, editar o rechazar. Conserva la decisión del revisor y cualquier corrección.
La documentación de n8n describe la aprobación humana de herramientas seleccionadas conectadas a un AI Agent: el flujo se pausa, un revisor puede aprobar o denegar la llamada a la herramienta propuesta y esta solo se ejecuta si se aprueba. La aprobación puede gestionarse a través de canales compatibles, como Slack, Telegram o n8n Chat. La documentación también explica cómo usar $tool.name y $tool.parameters para mostrar al revisor la herramienta propuesta y sus parámetros. Esto permite aprobar una llamada a una herramienta del AI Agent; por sí solo, no es una interfaz de revisión general para todos los registros extraídos. Para revisar registros, crea una tarea humana adecuada y una ruta para reanudar el flujo en tu implementación.
Fuente: documentación de n8n: Human-in-the-loop for tools.
5. Investiga los problemas con datos concretos
Si se rechazan repetidamente registros válidos, inspecciona la respuesta sin procesar y los errores del validador antes de cambiar el esquema. Comprueba si la respuesta incluye bloques delimitados de Markdown, texto adicional, campos anulables ausentes o números codificados como cadenas. Si los reintentos generan registros duplicados, mueve la escritura para que ocurra después de la validación y usa un identificador de origen estable. Si los revisores no pueden decidir con rapidez, incluye el fragmento exacto del origen que respalda cada campo dudoso, en lugar de enviar solo un objeto JSON.
No relajes el esquema solo para aumentar la tasa de aceptación. Un contrato modificado debería responder a una necesidad real de los pasos posteriores y sus efectos deberían probarse con entradas representativas, incluidos campos ausentes, documentos malformados y valores contradictorios.
Lista de comprobación reutilizable para publicar
- Están definidos los campos obligatorios, el comportamiento de los valores nulos, los tipos y la política para campos adicionales.
- El análisis, las comprobaciones de esquema y las comprobaciones de dominio se realizan antes de las escrituras posteriores.
- Los reintentos tienen un límite y se reservan para fallos que razonablemente podrían resolverse.
- El reprocesamiento no puede duplicar accidentalmente acciones trascendentes.
- Los revisores ven el origen, los valores propuestos y el motivo de la derivación.
- Los registros conservan suficiente información para investigar sin ocultar las salidas rechazadas.
El patrón fiable es sencillo: extraer, validar, enrutar y solo entonces actuar. Un esquema detecta problemas estructurales; los reintentos limitados gestionan fallos temporales; la revisión humana se ocupa de la ambigüedad y los riesgos que la automatización no debería resolver en silencio.
FAQ
¿Pedirle JSON a un modelo garantiza una salida que cumpla el esquema?
No. Trata la respuesta como entrada no confiable: procésala y valida los campos obligatorios, los tipos y las reglas de negocio en el flujo antes de usarla.
¿Debería n8n reintentar cuando el JSON extraído no supera la validación?
No de forma automática y sin límite. Un único intento de reparación puede ser útil, pero los fallos reiterados del esquema normalmente deberían derivarse o marcarse para su investigación, en lugar de reintentarse indefinidamente.
¿La aprobación con intervención humana de n8n puede revisar registros extraídos?
La función de n8n citada permite aprobar o denegar llamadas a herramientas realizadas por un AI Agent. Por sí sola, no proporciona una interfaz general para revisar registros; para los casos de extracción, implementa una tarea humana adecuada y una ruta para reanudar el flujo.
¿Qué debería ver un revisor?
Muestra el origen original o el fragmento pertinente, los campos estructurados propuestos, los errores de validación o la incertidumbre y opciones explícitas para aprobar, editar o rechazar.
Artículos relacionados
Guides
Crea un flujo de extracción de datos recuperable en n8n
Diseña un flujo de extracción en n8n que valide registros, reintente fallos transitorios y derive las excepciones a revisión humana sin duplicar escrituras.
Guides
Crea un flujo de extracción de datos en n8n que proteja la privacidad
Diseña un flujo de extracción en n8n que valide los resultados estructurados, gestione los fallos de forma segura y envíe las acciones sensibles a revisión humana.
Guides
Crea un flujo de extracción de datos repetible en n8n con validación, reintentos y revisión humana
Diseña un flujo de extracción en n8n que valide los resultados estructurados, reintente los errores temporales, derive los registros dudosos a revisión y pueda evaluarse con casos de prueba fijos.
Guides
Crea en n8n un flujo de preguntas y respuestas sobre documentos con citas validadas y revisión humana
Diseña un flujo de trabajo en n8n que extraiga evidencia documental, valide respuestas estructuradas, reintente de forma segura y derive los resultados inciertos a revisión humana.