Paperless-ngx avec n8n : classer et transmettre automatiquement les justificatifs

Paperless-ngx peut être connecté à n8n de deux façons : le hook post-consume, qui lance un script après la lecture d'un document, et l'API REST, via laquelle n8n peut interroger des documents, des tags et des métadonnées ou téléverser de nouveaux justificatifs. Pour la transmission à la comptabilité, cela signifie en pratique le plus souvent qu'un script post-consume appelle un webhook n8n, puis que n8n recharge ensuite les données complètes du document via l'API REST, plutôt que d'envoyer toutes les informations dès le premier appel. Un piège bien connu ici est le téléversement de fichiers de n8n vers Paperless-ngx, qui échoue avec une erreur 415 en cas de mauvaise configuration. État : août 2026.

Comment un script post-consume déclenche-t-il un workflow n8n ?

Selon sa propre documentation, Paperless-ngx permet d'exécuter, une fois le traitement du document terminé, un script personnalisé qui reçoit, via des variables d'environnement, l'accès à des métadonnées telles que DOCUMENT_ID, DOCUMENT_CORRESPONDENT, DOCUMENT_TAGS et DOCUMENT_ARCHIVE_PATH. Le script ne peut explicitement pas interrompre le processus de traitement et ne doit pas modifier lui-même les fichiers du document, car il s'exécute de manière synchrone et retarderait sinon la consommation. Dans une installation Docker Compose, vous montez le répertoire des scripts en tant que volume et définissez la variable d'environnement PAPERLESS_POST_CONSUME_SCRIPT sur le chemin dans le conteneur. Le script le plus simple appelle, avec les variables transmises, l'URL de production d'un nœud webhook n8n via curl et transmet l'ID du document et les tags au format JSON. Vous trouverez les détails sur les variables disponibles dans la documentation Paperless-ngx sur l'utilisation avancée.

Comment n8n téléverse-t-il ou récupère-t-il des justificatifs via l'API REST de Paperless-ngx ?

L'API REST de Paperless-ngx s'authentifie via un jeton, que vous générez soit dans la section profil de l'interface web, soit de manière programmatique via un POST vers /api/token/ avec un nom d'utilisateur et un mot de passe ; vous le transmettez ensuite dans l'en-tête Authorization: Token <token>. Pour téléverser un document, n8n appelle le point de terminaison /api/documents/post_document/ sous forme de formulaire au format multipart et peut y joindre en option des champs comme title, correspondent, document_type, storage_path et plusieurs tags, tandis que Paperless-ngx renvoie immédiatement, en cas de démarrage réussi, l'UUID de la tâche de consommation. Pour lire les justificatifs existants, le point de terminaison /api/documents/ est disponible avec des paramètres de recherche et de filtrage tels que text= ou query=. Vous trouverez les détails sur l'authentification et les points de terminaison dans la documentation de l'API Paperless-ngx.

Pourquoi le téléversement de fichier échoue-t-il avec une erreur 415 ?

Dans un cas documenté par la communauté n8n, le téléversement d'un PDF depuis Google Drive vers une instance locale de Paperless-ngx a échoué avec le message « Unsupported media type 'application/pdf' in request », car le nœud HTTP Request n'avait pas envoyé le fichier dans le format multipart/form-data attendu par l'API. L'utilisateur a résolu le problème en reconfigurant la requête sur la base de la documentation officielle de l'API, au lieu de transférer directement le fichier binaire au format brut. Vérifiez donc explicitement dans le nœud HTTP Request que le type de corps est réglé sur multipart-form-data et non sur un corps générique JSON ou binaire, avant de relier le champ contenant le fichier binaire provenant d'un nœud précédent. Dans la pratique, cette erreur survient surtout lors de la première mise en place de l'intégration et ne se reproduit pas ensuite.

Comment attribuer automatiquement des tags, et comment cela se poursuit-il ensuite vers la comptabilité ?

Paperless-ngx attribue les tags via des algorithmes de correspondance configurables, dont Any, All, Exact, Regex, Fuzzy et Auto, Auto reposant sur un modèle entraîné sur les documents existants et se passant entièrement de règles manuelles. Pour la transmission à la comptabilité, le workflow n8n relit, après le déclencheur webhook, les données du document, y compris les tags attribués, via l'API REST, et transmet les justificatifs portant un tag correspondant, par exemple « facture entrante » ou « frais de déplacement », à un système comptable via un nœud HTTP Request ou à la personne responsable via un nœud e-mail. Il en résulte un processus continu, de la numérisation ou de l'import par e-mail jusqu'au classement dans le système comptable, sans que personne n'ait à trier les justificatifs manuellement. NordFlux met en place ce type de workflows de transmission de façon individualisée pour ses clients dans le cadre de l'automatisation n8n, généralement complétés par une notification d'erreur pour les justificatifs qui ne peuvent pas être attribués.

Questions fréquentes sur n8n avec Paperless-ngx

Le hook post-consume est-il vraiment indispensable, ou l'API REST seule suffit-elle ?

L'API REST seule suffit si vous souhaitez interroger régulièrement n8n pour de nouveaux documents, mais le hook post-consume est la voie la plus directe, car Paperless-ngx déclenche alors lui-même activement un workflow. En pratique, la combinaison des deux offre les résultats les plus fiables, car le hook fournit le moment déclencheur et l'API les données complètes.

Pourquoi le téléversement de fichier vers Paperless-ngx échoue-t-il souvent dans n8n ?

La raison la plus fréquente est un type de corps mal configuré dans le nœud HTTP Request, qui ne transmet pas le fichier au format multipart/form-data, comme l'exige le point de terminaison /api/documents/post_document/. Un coup d'œil à la documentation officielle de l'API avant le premier essai vous épargne la recherche d'erreur habituelle liée au message 415.

Puis-je aussi modifier des tags existants dans Paperless-ngx avec n8n ?

Oui, via l'API REST, vous pouvez lire les documents, y compris leur attribution de tags, et les mettre à jour avec un appel PUT ou PATCH, à condition que le jeton utilisé dispose des droits nécessaires. Cela permet par exemple de marquer a posteriori des justificatifs comme « comptabilisés » une fois que la comptabilité les a traités.

L'automatisation fonctionne-t-elle aussi si Paperless-ngx et n8n se trouvent sur des serveurs différents ?

Oui, tant que les deux systèmes peuvent se joindre mutuellement via le réseau et que les URL respectives sont correctement renseignées dans le script et le workflow. Dans ce cas, veillez particulièrement à utiliser HTTPS et une authentification basée sur un jeton plutôt qu'une authentification ouverte, car la connexion transite alors par le réseau public ou un VPN.