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.
Resumen · TL;DR
Un diseño práctico para extraer registros estructurados en n8n, distinguir los fallos transitorios de los datos no válidos y recuperar el proceso de forma segura tras una interrupción.
Puntos clave
- Valida los campos extraídos antes de cualquier escritura posterior y deriva los registros no válidos a revisión en lugar de reintentarlos repetidamente.
- Usa reintentos limitados para los fallos transitorios, con un registro persistente de los intentos y una vía clara de escalamiento cuando se alcance el límite.
- Protege las escrituras en el destino con un mecanismo de idempotencia atómico y concilia los resultados ambiguos antes de reintentar.
- Usa la aprobación de herramientas de AI Agent en n8n para las acciones riesgosas iniciadas por agentes; crea una vía de revisión independiente para corregir datos extraídos.
En esta página (8)
Empieza por un contrato de recuperación
Para la extracción en producción con n8n, haz que cada documento pueda recuperarse de forma independiente: guarda su identidad y estado de procesamiento, valida los campos extraídos antes de escribirlos, reintenta solo los fallos que puedan resolverse y deriva los casos pendientes a una persona. Un flujo de trabajo satisfactorio no es simplemente uno que vuelve a ejecutarse, sino uno que puede hacerlo sin duplicar ni perder registros inadvertidamente.
El siguiente ejemplo extrae datos de facturas y escribe los registros aprobados en un sistema de destino. Es un diseño ilustrativo, no un flujo de trabajo probado. Las opciones de los nodos y las integraciones varían según la versión de n8n y el destino; verifícalas en tu entorno.
Requisitos previos y estructura del flujo
Necesitas una instancia de n8n, acceso a una fuente de documentos y a un servicio de extracción, una base de datos persistente o un almacén de estado equivalente, un destino para los registros validados y un canal de revisión. Restringe el acceso a los documentos de origen y a los mensajes de revisión según su sensibilidad.
Usa esta secuencia lógica:
- Activar y registrar: Recibe una referencia al documento. Crea o busca una tarea persistente mediante un ID de origen estable y la versión del documento.
- Extraer: Obtén el documento y solicita campos estructurados al extractor que hayas elegido.
- Validar: Comprueba los datos devueltos frente a un contrato explícito.
- Dirigir: Envía los registros válidos a la ruta de escritura y los no válidos a una cola de revisión.
- Escribir y conciliar: Escribe usando una clave de idempotencia estable y registra después el ID de destino y el resultado.
- Recuperar: Un flujo programado independiente busca tareas cuyo reintento está pendiente o que llevan bloqueadas más allá de un umbral operativo.
El ID de una ejecución del disparador es útil para el seguimiento, pero no es una identidad fiable del documento entre ejecuciones. Es preferible usar un ID del documento en el sistema de origen junto con una versión o un resumen del contenido. Define cómo recibe una nueva versión un documento corregido antes de activar el reprocesamiento automático.
Valida el registro extraído antes de escribirlo
Para este ejemplo, exige invoice_id, currency y amount_minor. Representa los importes en unidades monetarias menores, como centavos, para evitar redondeos de punto flotante durante la validación. El contrato presupone que el extractor ya ha convertido el importe según las reglas de la moneda; una implementación real también debe comprobar que la moneda sea compatible y que cualquier conversión sea adecuada.
Coloca un nodo Code después de la extracción. El siguiente JavaScript ilustrativo comprueba cada elemento entrante y devuelve un resultado revisable en lugar de lanzar un error ante datos incorrectos. Configura el nodo para procesar todos los elementos entrantes y asegúrate de que el JSON de cada elemento sea el registro extraído antes de ejecutar este nodo.
return $input.all().map((item) => {
const record = item.json;
const errors = [];
if (typeof record.invoice_id !== 'string' || !record.invoice_id.trim()) {
errors.push('invoice_id must be a non-empty string');
}
if (typeof record.currency !== 'string' || !/^[A-Z]{3}$/.test(record.currency)) {
errors.push('currency must be a three-letter uppercase code');
}
if (!Number.isSafeInteger(record.amount_minor) || record.amount_minor < 0) {
errors.push('amount_minor must be a non-negative safe integer');
}
return {
json: {
record,
validation: { valid: errors.length === 0, errors },
},
};
});
A continuación, añade un nodo IF que compruebe validation.valid. Conserva el ID de la tarea y la referencia de origen junto con este resultado, ya sea en el elemento o mediante una consulta a tu almacén de estado. La expresión regular comprueba la forma de un código de moneda, no si corresponde a una moneda real compatible. Añade comprobaciones de negocio, como la coincidencia del proveedor y la detección de facturas duplicadas, antes de la escritura.
Las respuestas mal formadas que no puedan analizarse como un elemento necesitan su propia ruta de error. No des por hecho que el nodo de validación recibirá un registro utilizable después de cada fallo de extracción. Guarda un diagnóstico seguro y deriva a revisión los fallos de análisis persistentes.
Define reglas de reintento y escalamiento
Haz explícitas las decisiones de reintento. La siguiente política es un punto de partida, no una garantía de que todos los servicios usen estos códigos de estado de la misma manera.
| Fallo | Acción inicial | Tras alcanzar el límite o investigar |
|---|---|---|
| Tiempo de espera agotado, fallo de conexión o error temporal del servicio | Reintenta con un intervalo limitado y aleatorización. Respeta el intervalo de reintento documentado cuando se proporcione. | Marca el caso para que lo investigue un operador. |
| Límite de solicitudes | Espera según las indicaciones del servicio; reduce la concurrencia si es necesario. | Escala el caso si la tarea no puede avanzar dentro de su ventana de servicio. |
| Campo ausente o validación de negocio fallida | No repitas indefinidamente la misma solicitud; envía el registro y los errores a revisión. | Vuelve a validar el registro corregido antes de escribirlo. |
| Error de autenticación o permisos | Detén los reintentos automáticos y alerta a un operador. | Reanuda el proceso cuando se hayan corregido las credenciales o los permisos. |
| Tiempo de espera agotado durante la escritura con resultado desconocido | Consulta el destino usando la clave de operación estable antes de volver a escribir. | Concilia manualmente si el resultado sigue siendo desconocido. |
Por ejemplo, permite hasta tres intentos totales de extracción, con esperas de aproximadamente uno y cinco minutos entre intentos, más una variación aleatoria. Registra de forma persistente el número de intentos, la categoría del último error, el próximo momento en que se puede reintentar y el resultado final. Decide si una espera indicada por el proveedor tiene prioridad sobre las esperas de este ejemplo. Evita acumular reintentos a nivel de nodo y reintentos programados sin contabilizar ambos: de lo contrario, el número real de intentos puede superar la política.
Usa las opciones de gestión de errores y reintentos disponibles en n8n cuando corresponda, pero no dependas únicamente de un registro de ejecución como cola. Un flujo de recuperación programado debe consultar el estado persistente de las tareas y reclamar de forma atómica las que puedan procesarse, para que dos procesos no puedan trabajar en la misma tarea simultáneamente. Verifica la configuración exacta de los nodos y el comportamiento de los bloqueos de la base de datos en tu implementación.
Haz que las escrituras puedan recuperarse de forma segura
Antes de la primera escritura en el destino, guarda de forma persistente una clave de operación estable derivada de la identidad y la versión del documento de origen. Reutiliza esa misma clave en cada reintento. El destino debe imponer la unicidad o respetar una clave de idempotencia de forma atómica; comprobar si existe un registro e insertarlo después en una operación separada deja margen a conflictos entre procesos concurrentes.
Si el destino no dispone de esa capacidad, usa un almacén intermediario con una restricción de unicidad atómica y un proceso de conciliación. Esto por sí solo no puede garantizar que los efectos se produzcan exactamente una vez en un sistema independiente: una escritura puede completarse allí mientras tu proceso pierde la respuesta. En ese caso, consulta el destino mediante una referencia externa estable antes de reintentar, o deriva el caso a un operador si no es posible consultarlo de forma fiable.
Haz seguimiento de estados como received, extracting, review_required, ready_to_write, write_unknown y completed. Establece una concesión temporal o un plazo para el trabajo en curso y haz que el proceso de recuperación revise las concesiones vencidas. Guarda el ID del registro de destino solo después de confirmar la escritura. Conserva el historial de intentos y las transiciones de estado para que un operador pueda explicar lo ocurrido sin exponer contenido innecesario de los documentos en los registros.
Incorpora la revisión humana en el punto adecuado
Para los resultados de extracción no válidos, crea una tarea de revisión que incluya la referencia de origen, los campos propuestos, los errores de validación y el ID de la tarea. Ofrece un mecanismo autenticado para aprobar una corrección o rechazar la tarea. Cuando se haga una corrección, guarda quién la hizo y cuándo, vuelve a ejecutar la validación y usa la misma ruta de escritura protegida. Define un responsable del escalamiento y un plazo para las revisiones sin atender; no interpretes el silencio como aprobación.
Otra función de n8n se aplica cuando un AI Agent llama a una herramienta. La documentación de n8n sobre supervisión humana indica que determinadas llamadas a herramientas pueden pausarse para su aprobación o rechazo, mostrando a la persona revisora la herramienta y los parámetros propuestos. En el panel Tools del Agent, añade un paso de revisión humana, configura un canal compatible y conecta las herramientas que requieren aprobación. La documentación también recomienda indicar al agente en su prompt de sistema qué herramientas requieren aprobación y cómo gestionar un rechazo.
Esta aprobación de herramientas no sustituye la validación de esquemas ni una cola general de corrección de registros. Una herramienta aprobada se ejecuta con la entrada propuesta por la IA; si una persona revisora necesita cambiar los campos extraídos, usa una ruta de corrección y vuelve a validar antes de cualquier escritura.
Comprobaciones operativas antes del lanzamiento
- Prueba un campo ausente, una respuesta de extracción mal formada, un límite de solicitudes, una credencial vencida y una revisión rechazada.
- Simula una escritura en el destino que se completa pero no devuelve respuesta; confirma que la recuperación concilia el resultado en lugar de volver a insertar el registro sin comprobarlo.
- Confirma que los procesos de recuperación concurrentes no puedan reclamar la misma tarea y que los límites de reintento incluyan todas las capas de reintento.
- Configura alertas para tareas de revisión antiguas, reintentos agotados, concesiones vencidas y resultados de escritura desconocidos. Comprueba que un operador pueda localizar el origen y reanudar o cerrar cada tarea de forma segura.
Empieza con límites de reintento y reglas de revisión conservadores y ajústalos después según las categorías de fallo observadas. Mantén los controles de validación e idempotencia incluso a medida que amplíes la automatización.
Fuentes
- n8n: Human-in-the-loop for tools — comportamiento de la aprobación de herramientas, configuración, canales y orientación para el prompt del agente.
FAQ
¿Debe un flujo de n8n reintentar un registro que no supera la validación de esquema?
Por lo general, no con la misma entrada y configuración. Derívalo a revisión o a un proceso de corrección definido y valida el registro corregido antes de escribirlo. Una política de nueva extracción con límites independientes puede ser adecuada cuando la causa es transitoria.
¿La revisión humana de n8n valida automáticamente los datos extraídos?
No. La función documentada de revisión de herramientas de AI Agent pide a una persona que apruebe o rechace una llamada propuesta a una herramienta. La validación de esquemas y cualquier proceso de corrección de registros necesitan su propio diseño de flujo de trabajo.
¿Cómo puede un flujo evitar escrituras duplicadas después de que se agote el tiempo de espera?
Reutiliza una clave de operación estable y haz que el destino la aplique de forma atómica. Si el resultado es desconocido, concílialo con el destino antes de reintentar; escala el caso cuando no se pueda determinar el resultado.
Artículos relacionados
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 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.
Guides
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.
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.