Paperless-ngx con n8n: clasificar y reenviar comprobantes automáticamente

Paperless-ngx se puede conectar con n8n de dos maneras: el hook post-consume, que inicia un script después de leer un documento, y la API REST, mediante la cual n8n puede consultar documentos, etiquetas y metadatos o subir nuevos comprobantes. Para el traspaso a contabilidad, esto suele significar en la práctica que un script post-consume llama a un webhook de n8n y que n8n vuelve a cargar después los datos completos del documento a través de la API REST, en lugar de enviar toda la información ya en la primera llamada. Un obstáculo conocido aquí es la carga de archivos de n8n a Paperless-ngx, que falla con un error 415 si la configuración es incorrecta. Fecha: agosto de 2026.

¿Cómo activa un script post-consume un flujo de trabajo de n8n?

Según su propia documentación, Paperless-ngx permite ejecutar, una vez finalizado el procesamiento del documento, un script propio que recibe, mediante variables de entorno, acceso a metadatos como DOCUMENT_ID, DOCUMENT_CORRESPONDENT, DOCUMENT_TAGS y DOCUMENT_ARCHIVE_PATH. El script no puede interrumpir explícitamente el proceso de procesamiento y no debería modificar los propios archivos del documento, ya que se ejecuta de forma síncrona y, de lo contrario, retrasaría la consumición. En una instalación con Docker Compose, monta el directorio de scripts como volumen y establece la variable de entorno PAPERLESS_POST_CONSUME_SCRIPT en la ruta dentro del contenedor. El script más sencillo llama, con las variables proporcionadas, a la URL de producción de un nodo webhook de n8n mediante curl y envía el ID del documento y las etiquetas en formato JSON. Encontrará los detalles sobre las variables disponibles en la documentación de Paperless-ngx sobre el uso avanzado.

¿Cómo sube o recupera n8n comprobantes mediante la API REST de Paperless-ngx?

La API REST de Paperless-ngx se autentica mediante un token, que puede generar en la sección de perfil de la interfaz web o solicitar de forma programática mediante un POST a /api/token/ con nombre de usuario y contraseña; después lo incluye en la cabecera Authorization: Token <token>. Para subir un documento, n8n llama al endpoint /api/documents/post_document/ como formulario multipart y puede incluir opcionalmente campos como title, correspondent, document_type, storage_path y varias tags, mientras que Paperless-ngx devuelve inmediatamente, si el inicio es correcto, el UUID de la tarea de consumición. Para leer comprobantes existentes está disponible el endpoint /api/documents/ con parámetros de búsqueda y filtrado como text= o query=. Encontrará los detalles sobre autenticación y endpoints en la documentación de la API de Paperless-ngx.

¿Por qué falla la carga de archivos con un error 415?

En un caso documentado por la comunidad de n8n, la carga de un PDF desde Google Drive a una instancia local de Paperless-ngx falló con el mensaje «Unsupported media type 'application/pdf' in request», porque el nodo HTTP Request no había enviado el archivo en el formato multipart/form-data esperado por la API. El usuario resolvió el problema reconfigurando la solicitud según la documentación oficial de la API, en lugar de transferir el archivo binario directamente en formato bruto. Por eso, compruebe explícitamente en el nodo HTTP Request que el tipo de cuerpo esté configurado en multipart-form-data y no en un cuerpo genérico JSON o binario, antes de vincular el campo con el archivo binario procedente de un nodo anterior. En la práctica, este error aparece sobre todo al configurar la integración por primera vez y después no es un problema recurrente.

¿Cómo se asignan las etiquetas automáticamente y cómo continúa el proceso hacia contabilidad?

Paperless-ngx asigna etiquetas mediante algoritmos de coincidencia configurables, entre ellos Any, All, Exact, Regex, Fuzzy y Auto, donde Auto se basa en un modelo entrenado con los documentos existentes y funciona por completo sin reglas manuales. Para el traspaso a contabilidad, el flujo de trabajo de n8n vuelve a leer, tras el disparador webhook, los datos del documento, incluidas las etiquetas asignadas, a través de la API REST, y reenvía los comprobantes con una etiqueta adecuada, por ejemplo «factura recibida» o «gastos de viaje», a un sistema de contabilidad mediante un nodo HTTP Request o a la persona responsable mediante un nodo de correo electrónico. Así surge un proceso continuo desde el escaneo o la importación por correo electrónico hasta el archivo en el sistema de contabilidad, sin que nadie tenga que clasificar comprobantes manualmente. NordFlux configura este tipo de flujos de traspaso de forma individual para sus clientes en el marco de la automatización con n8n, normalmente complementados con una notificación de error para los comprobantes que no se pueden asignar.

Preguntas frecuentes sobre n8n con Paperless-ngx

¿Es imprescindible el hook post-consume, o basta con la API REST?

La API REST por sí sola es suficiente si desea consultar periódicamente n8n en busca de nuevos documentos, pero el hook post-consume es la vía más directa, porque entonces es el propio Paperless-ngx el que activa un flujo de trabajo. En la práctica, la combinación de ambos ofrece los resultados más fiables, porque el hook aporta el momento y la API los datos completos.

¿Por qué falla a menudo la carga de archivos a Paperless-ngx en n8n?

El motivo más frecuente es un tipo de cuerpo mal configurado en el nodo HTTP Request, que no transmite el archivo como multipart/form-data, tal como exige el endpoint /api/documents/post_document/. Echar un vistazo a la documentación oficial de la API antes de la primera prueba ahorra la típica búsqueda de errores mediante un mensaje 415.

¿Puedo también modificar etiquetas existentes en Paperless-ngx con n8n?

Sí, mediante la API REST se pueden leer documentos, incluida su asignación de etiquetas, y actualizarlos con una llamada PUT o PATCH, siempre que el token utilizado tenga los permisos necesarios. Esto resulta útil, por ejemplo, para marcar posteriormente comprobantes como «contabilizados» una vez que contabilidad los ha procesado.

¿Funciona la automatización también si Paperless-ngx y n8n están en servidores distintos?

Sí, siempre que ambos sistemas puedan alcanzarse mutuamente a través de la red y las URL correspondientes estén correctamente configuradas en el script y el flujo de trabajo. En ese caso, preste especial atención a HTTPS y a una autenticación basada en token en lugar de una autenticación abierta, ya que la conexión pasa entonces por la red pública o una VPN.