n8n ile Paperless-ngx: Fişleri Otomatik Sınıflandırma ve İletme

Paperless-ngx, n8n ile iki şekilde bağlanabilir: bir belge okunduktan sonra bir betiği başlatan post-consume hook ve n8n'in belgeleri, etiketleri ve meta verileri sorgulayabildiği veya yeni fişler yükleyebildiği REST API. Muhasebeye aktarım söz konusu olduğunda bu, pratikte genellikle bir post-consume betiğinin bir n8n webhook'unu çağırması ve n8n'in ardından tüm bilgileri ilk çağrıda göndermek yerine REST API üzerinden belgenin tam verilerini yeniden yüklemesi anlamına gelir. Burada bilinen bir tuzak, yanlış yapılandırıldığında 415 hatasıyla başarısız olan n8n'den Paperless-ngx'e dosya yüklemedir. Güncelleme: Ağustos 2026.

Bir post-consume betiği bir n8n iş akışını nasıl tetikler?

Paperless-ngx, kendi belgelerine göre, belge işleme tamamlandıktan sonra ortam değişkenleri aracılığıyla DOCUMENT_ID, DOCUMENT_CORRESPONDENT, DOCUMENT_TAGS ve DOCUMENT_ARCHIVE_PATH gibi meta verilere erişim sağlayan kendi betiğinizi çalıştırmanıza izin verir. Betik, işleme sürecini açıkça iptal edemez ve senkron çalıştığı için belge dosyalarının kendisini değiştirmemelidir, aksi takdirde tüketim gecikir. Bir Docker Compose kurulumunda betik dizinini bir volume olarak bağlar ve PAPERLESS_POST_CONSUME_SCRIPT ortam değişkenini konteyner içindeki yola ayarlarsınız. En basit betik, aktarılan değişkenlerle bir n8n webhook node'unun üretim URL'sini curl ile çağırır ve belge kimliğini ve etiketleri JSON olarak iletir. Mevcut değişkenlerle ilgili ayrıntıları Paperless-ngx gelişmiş kullanım belgelerinde bulabilirsiniz.

n8n, Paperless-ngx REST API'si üzerinden fişleri nasıl yükler veya geri alır?

Paperless-ngx REST API'si, web arayüzünün profil bölümünde oluşturabileceğiniz veya kullanıcı adı ve şifreyle /api/token/ adresine programatik bir POST isteğiyle talep edebileceğiniz bir token üzerinden kimlik doğrulaması yapar; ardından bunu Authorization: Token <token> başlığında iletirsiniz. Bir belgeyi yüklemek için n8n, /api/documents/post_document/ uç noktasını multipart formatlı bir form olarak çağırır ve isteğe bağlı olarak title, correspondent, document_type, storage_path gibi alanları ve birden fazla tags değerini gönderebilir; Paperless-ngx başarılı bir başlangıçta hemen tüketim görevinin UUID'sini döndürür. Mevcut fişleri okumak için text= veya query= gibi arama ve filtre parametreleriyle /api/documents/ uç noktası kullanılabilir. Kimlik doğrulama ve uç noktalarla ilgili ayrıntıları Paperless-ngx API belgelerinde bulabilirsiniz.

Dosya yüklemesi neden 415 hatasıyla başarısız oluyor?

n8n topluluğundan belgelenmiş bir olayda, Google Drive'dan yerel bir Paperless-ngx örneğine bir PDF yüklemesi, HTTP Request node'unun dosyayı API'nin beklediği multipart/form-data biçiminde göndermemesi nedeniyle "Unsupported media type 'application/pdf' in request" mesajıyla başarısız oldu. Kullanıcı, ikili dosyayı doğrudan ham biçimde aktarmak yerine, isteği resmi API belgelerine dayanarak yeniden yapılandırarak sorunu çözdü. Bu nedenle, önceki bir node'dan gelen ikili dosya alanını bağlamadan önce HTTP Request node'unda gövde türünün genel bir JSON veya ikili gövde yerine multipart-form-data olarak ayarlandığını açıkça kontrol edin. Bu hata pratikte esas olarak entegrasyonun ilk kurulumunda ortaya çıkar ve sonrasında tekrarlayan bir sorun değildir.

Etiketleri otomatik olarak nasıl atarsınız ve süreç muhasebeye nasıl devam eder?

Paperless-ngx, aralarında Any, All, Exact, Regex, Fuzzy ve Auto'nun bulunduğu yapılandırılabilir eşleştirme algoritmaları aracılığıyla etiketler atar; Auto, mevcut belgeler üzerinde eğitilmiş bir modele dayanır ve manuel kurallara hiç ihtiyaç duymaz. Muhasebeye aktarım için n8n iş akışı, webhook tetikleyicisinden sonra atanan etiketler dahil belge verilerini REST API üzerinden yeniden okur ve örneğin "gelen fatura" veya "seyahat masrafları" gibi uygun bir etikete sahip fişleri bir HTTP Request node'u aracılığıyla bir muhasebe sistemine veya bir e-posta node'u aracılığıyla ilgili kişiye iletir. Böylece taramadan veya e-posta içe aktarımından muhasebe sistemine kaydedilmesine kadar, kimsenin fişleri manuel olarak sınıflandırmasına gerek kalmadan uçtan uca bir süreç ortaya çıkar. NordFlux, bu tür aktarım iş akışlarını n8n otomasyonu kapsamında müşteriler için ayrı ayrı kurar; genellikle atanamayan fişler için bir hata bildirimiyle tamamlanır.

n8n ile Paperless-ngx hakkında sıkça sorulan sorular

Post-consume hook kesinlikle gerekli mi, yoksa yalnızca REST API yeterli mi?

n8n'de yeni belgeleri düzenli olarak sorgulamak istiyorsanız yalnızca REST API yeterlidir, ancak post-consume hook daha doğrudan bir yoldur, çünkü Paperless-ngx bu durumda bir iş akışını kendisi etkin olarak tetikler. Pratikte ikisinin birleşimi en güvenilir sonuçları verir, çünkü hook zamanlamayı, API ise tam verileri sağlar.

n8n'de Paperless-ngx'e dosya yüklemesi neden sık sık başarısız oluyor?

En yaygın neden, /api/documents/post_document/ uç noktasının gerektirdiği gibi dosyayı multipart/form-data olarak iletmeyen, HTTP Request node'unda yanlış yapılandırılmış bir gövde türüdür. İlk test çalıştırmasından önce resmi API belgelerine bir göz atmak, 415 mesajı üzerinden yapılan olağan hata aramasından tasarruf sağlar.

n8n ile Paperless-ngx'teki mevcut etiketleri de değiştirebilir miyim?

Evet, kullanılan token'ın gerekli izinlere sahip olması koşuluyla REST API üzerinden belgeler etiket ataması dahil okunabilir ve bir PUT veya PATCH çağrısıyla güncellenebilir. Bu, örneğin muhasebe fişleri işledikten sonra bunları sonradan "kaydedildi" olarak işaretlemek için uygundur.

Paperless-ngx ve n8n farklı sunucularda bulunsa da otomasyon çalışır mı?

Evet, her iki sistem de ağ üzerinden birbirine ulaşabildiği ve ilgili URL'ler betik ve iş akışında doğru şekilde tanımlandığı sürece çalışır. Bu durumda, bağlantı genel ağ veya bir VPN üzerinden gittiği için özellikle HTTPS'e ve açık bir kimlik doğrulama yerine token tabanlı bir kimlik doğrulamaya dikkat edin.