n8n ile sevDesk: Polling Tetikleyicisi, API Sınırları

sevDesk, n8n çekirdeğinde yerel bir sevDesk düğümü bulunmadığı ve dolayısıyla sevDesk'teki değişiklikleri otomatik olarak bir iş akışına bildiren bir webhook tetikleyicisi olmadığı için n8n'e yalnızca HTTP Request düğümü üzerinden bağlanabilir. n8n içinde yeni faturalar, kişiler veya belgeler gibi sevDesk verilerini işlemek isteyenler bu nedenle bir polling tetikleyicisi oluşturur: bir Schedule Trigger düğümü belirli aralıklarla sevDesk API'sini HTTP Request üzerinden çağırır ve yanıtı iş akışının geri kalanına aktarır. sevDesk API'sinin kendisi sorgu başına sayfa boyutunu çağrı başına en fazla 1000 kayıtla sınırlar ve Nisan 2025'ten beri bir URL parametresi yerine bir Authorization başlığı üzerinden kimlik doğrulama gerektirir. Güncelleme: Temmuz 2026.

Neden webhook tetikleyicisi mümkün değil

n8n, çekirdeğe entegre edilmiş yerel düğümler ile ayrı ayrı kurulan topluluk düğümleri arasında ayrım yapar. sevDesk için yerel bir düğüm bulunmadığından, sevDesk'teki olaylara tepki veren hazır bir tetikleyici düğüm de yoktur. Resmi sevDesk API belgelerinde, sevDesk'in bir dış sisteme aktif olarak veri gönderdiği bir webhook mekanizması hiçbir yerde açıklanmamıştır. Bu, pratikte şu anlama gelir: bir iş akışı, sevDesk'te yeni bir fatura oluşturulduğunu veya bir belgenin kaydedildiğini kendiliğinden öğrenmez. Aktif olarak sorması gerekir ve tam olarak bunu polling tetikleyicisi yapar.

Yapı: Schedule Trigger artı HTTP Request

Schedule Trigger Node düğümü, iş akışını sabit bir aralıkla, saniye, dakika, saat, gün ya da özel bir cron ifadesi üzerinden başlatır. Hemen ardından HTTP Request Node düğümü gelir; bu düğüm sevDesk API'sine karşı asıl sorguyu gerçekleştirir, örneğin Invoice veya Contact gibi bir endpoint'e karşı. HTTP Request düğümü bunun için Header Auth gibi genel kimlik doğrulama yöntemlerinin yanı sıra, limit ve offset gibi parametrelerin her çağrıda otomatik olarak artırılmasını sağlayan yerleşik sayfalama (pagination) seçeneklerini destekler. Yanıt, iş akışına JSON olarak gelir ve ardından filtrelenebilir, dönüştürülebilir ve hedef sistemlere aktarılabilir.

sevDesk API token'ı ile kimlik doğrulama

Her sevDesk yöneticisinin, hesap ayarlarında bulunan 32 karakterlik onaltılık (hexadecimal) bir dizeden oluşan bir API token'ı vardır. Kimlik doğrulama hakkındaki sevDesk API belgelerine göre token'ın süresi sınırsızdır ve HTTP Request düğümünde Authorization başlığının değeri olarak iletilmelidir. Eski iş akışları için önemli: Nisan 2025'e kadar token bir URL parametresi olarak da iletilebiliyordu, ancak sevDesk bu yöntemi güvenlik nedeniyle kaldırdı. URL'de token bulunan eski bir entegrasyonu hâlâ kullananların bunu Authorization başlığına geçirmesi gerekir, aksi halde kimlik doğrulama başarısız olur.

Sayfalama (pagination) ve belgelenen API sınırları

sevDesk, liste sorgularını limit ve offset parametreleri üzerinden sayfalar. Resmi belgelerdeki örneklerde, başka bir belirtim olmadan yapılan bir sorgu varsayılan olarak en fazla 100 kayıt döndürür. sevDesk'in yeni sayfalama sınırlarına ilişkin duyurusuna göre sevDesk, 30 Mayıs 2025'ten itibaren ayrıca sabit bir üst sınır uygulamaktadır: limit parametresi 1 ile 1000 arasında bir tam sayı olmalıdır, aksi takdirde API, yalnızca bu aralıktaki değerlerin geçerli olduğu bilgisiyle HTTP 400 yanıtı verir. Daha önce çok daha büyük hatta rastgele değerler de aktarılabiliyordu. Bir polling iş akışı için bu şu anlama gelir: daha büyük veri hacimlerinde artan offset değerleriyle birden fazla çağrı gerekir; bu, HTTP Request düğümünde "Update a Parameter in Each Request" sayfalama ayarı üzerinden gerçekleştirilebilir. sevDesk belgeleri bu noktada dakika veya saat başına istek sayısına ilişkin somut rakamlar vermez, ancak temel bir hız sınırlaması (rate limiting) mevcuttur ve sorgu aralığı seçilirken dikkate alınmalıdır.

Aralık seçimi ve bakım yükünün planlanması

Webhook olmadan gerçek zamanlı bildirim yoktur; iki zamanlanmış çalıştırma arasındaki her gecikme, işlemedeki gerçek bir gecikmedir. Daha kısa bir aralık daha güncel veriler sağlar, ancak API çağrılarının sayısını ve dolayısıyla kamuya açık olarak belirtilmemiş sınırlara çarpma riskini artırır. Ayrıca iş akışının kendisi, halihazırda işlenmiş kayıtların iki kez işlenmemesini sağlamalıdır; örneğin son başarılı çalıştırmanın zamanını kaydedip bir sonraki sorguda filtre olarak kullanarak. Bu mantığı yerel bir düğümde genellikle düğümün kendisi üstlenir; salt HTTP Request tabanlı bir çözümde ise bu mantığın iş akışına dahil edilmesi ve 2025'teki iki breaking change gibi API değişikliklerinde de bakımının yapılması gerekir. Bu yükü kendisi taşımak istemeyenler, bu tür entegrasyonların kurulumunda örneğin NordFlux'un n8n otomasyonu veya daha genel olarak otomasyon hizmetinden destek alabilir.

sevDesk ve n8n hakkında sık sorulan sorular

n8n için resmi bir sevDesk düğümü var mı?

Hayır, sevDesk n8n çekirdeğinde yerel bir düğüm değildir. Bağlantı, sevDesk'in REST API'sine karşı genel HTTP Request düğümü üzerinden kurulur.

Schedule Trigger, sevDesk API'sini ne sıklıkla sorgulamalıdır?

Bu, kullanım senaryosuna bağlıdır. Muhasebe süreçleri için genellikle 15 ile 60 dakika arasında bir aralık yeterlidir, zamana duyarlı kullanım senaryoları için daha kısa olmalıdır. sevDesk dakika başına istek sayısına ilişkin genel rakamlar yayınlamadığından, çok kısa bir döngü yerine hata yönetimiyle birlikte ölçülü bir aralık önerilir.

sevDesk API'si sorgu başına kaç kayıt döndürür?

Mayıs 2025'ten itibaren limit parametresi yalnızca 1 ile 1000 arasında tam sayı değerlere izin verir, bu aralığın dışındaki her değer bir HTTP 400 hatasına yol açar. Daha büyük veri hacimleri, artan offset değerleriyle birden fazla çağrı gerektirir.

Eski URL parametresi üzerinden kimlik doğrulama hâlâ çalışıyor mu?

Hayır. sevDesk bu mekanizmayı 29 Nisan 2025 itibarıyla devre dışı bıraktı. O tarihten beri API token'ı her istekte Authorization başlığıyla birlikte gönderilmelidir.