Kişiler, fırsatlar ve konuşmalar için n8n CRM node’u

Node’un kurulumu

Node, npm’e n8n-nodes-crmsolid adıyla yayımlandı ve her topluluk node’u gibi kuruluyor: sunucuya dosya kopyalayarak değil, n8n’in içinden.

1. Ayarlar, ardından Community Nodes bölümünü açın. Bunun için kurulum sahibi hesabı gerekir; üye hesapları paket kuramaz.
2. Install’a basıp n8n-nodes-crmsolid yazın. Topluluk node’u uyarısını onaylayıp kurun. n8n paketi indirir, node birkaç saniye içinde tuval aramasında görünür.
3. CRM Solid node’unu bir iş akışına ekleyin. Kaynak seçmenize izin vermeden önce kimlik bilgisi ister; sırada o var.

Kendi sunucunuzdaki n8n’de komut satırından da kurabilirsiniz:

npm install n8n-nodes-crmsolid
# then restart n8n

Planınızı buna göre kurmadan önce bilinmesi gereken bir kısıt var: n8n Cloud yalnızca n8n’in kendi incelemesinden geçirip doğruladığı topluluk node’larını sunuyor ve bu paket henüz o incelemeden geçmedi. Kendi sunucunuzdaki n8n yayımlanmış her paketi kurar. Cloud tarafında aynı işlemlere REST API’ye yönlendirilmiş bir HTTP Request node’uyla ulaşılır; bu, atlamayı tercih edeceğimiz bir ayrıntı değil, işin doğrusu.

Paketin çalışma zamanı bağımlılığı yok. Her istek n8n’in kendi HTTP yardımcısından geçiyor; kimlik bilgisinin Authorization başlığını eklemesini sağlayan ve kurulumu küçük tutan şey de bu.

Kimlik bilgisini oluşturma

Node, bir CRM Solid API anahtarıyla kimlik doğrular: tek anahtar, tek başlık, OAuth turu yok.

1. CRM Solid panelinde Ayarlar, ardından Geliştiriciler bölümünü açın. Bir anahtar oluşturun ve onu kullanacak iş akışının adını verin; iptal ettiğiniz gün neyin duracağını böyle bilirsiniz.
2. Yalnızca o iş akışının ihtiyaç duyduğu kapsamları verin. Kişi yazan bir akışa contacts:read ve contacts:write yeter. Fırsat raporuna deals:read. Konuşmalar contacts:read ile okunur.
3. Token’ı bir kez kopyalayın. Canlı anahtarlar csk_live_, test anahtarları csk_test_ ile başlar. Tam token yalnızca oluşturulurken gösterilir, bir daha gösterilmez; sonrasında panelde sadece ön eki görünür.
4. n8n’de CRM Solid API kimlik bilgisi ekleyip anahtarı yapıştırın. Staging bir kuruluma bağlanmıyorsanız Base URL’i https://api.crmsolid.com olarak bırakın, sonra kimlik bilgisi testini çalıştırın.

Kimlik bilgisi testi, var olan en ucuz kimlikli isteği atar:

curl https://api.crmsolid.com/v1/me \
  -H "Authorization: Bearer csk_live_YOUR_KEY"

API anahtarları Business paketinin bir parçası. Ücretsiz ve Pro paketlerde üretilecek bir anahtar yok, dolayısıyla kimlik bilgisinin tutacağı bir şey de olmuyor. Kuruluma başlamadan önce bakılması gereken tek ön koşul bu.

Varsayılan bütçe, anahtar başına dakikada 60 istek. Her yanıt X-RateLimit-Limit, X-RateLimit-Remaining ve X-RateLimit-Reset başlıklarını taşır; sınırı aşan istek, saniye cinsinden bir Retry-After ile birlikte HTTP 429 alır. Sınır çalışma alanı başına değil anahtar başına olduğu için, döngüye giren bir iş akışı diğer entegrasyonlarınızı aç bırakmaz, kendi kendini kısar.

Üç kaynak üzerinde sekiz işlem

Aşağıdaki liste seçme bir vitrin değil, yüzeyin tamamı.

n8n arayüzü İngilizce olduğu için işlemler tuvalde Create, Get, Get Many, Update ve Delete adlarıyla görünür; kaynaklar da Contact, Deal ve Conversation olarak listelenir.

• Kişi, Oluştur. Ad, kullanıcı adı, telefon, e-posta veya dış kimlikten en az biri gerekir. Ek alanlar e-posta, telefon, kullanıcı adı, platform, not ve kendi dış kimliğinizi taşır.
• Kişi, Getir. Sayısal kimliğiyle tek bir kişi.
• Kişi, Çoklu Getir. Metin araması, platform, e-posta, dış kimlik ve Updated Since filtreleri.
• Kişi, Güncelle. Kısmi güncelleme: listeye eklemediğiniz alan silinmez, olduğu gibi kalır.
• Kişi, Sil. Silmez, arşivler. Mesaj geçmişi ve bağlı fırsatlar durur; panelde aynı işlem de böyle davranır.
• Fırsat, Oluştur. Başlık zorunlu. Tutar, para birimi, aşama, olasılık, beklenen kapanış tarihi, not ve kişi kimliği isteğe bağlı.
• Fırsat, Çoklu Getir. Aşama, kişi ve başlık araması filtreleri. Aşama burada kazanıldı ve kaybedildi değerlerini de kabul eder: kapanmış bir fırsatı yazmak yasak olsa da okumak serbest.
• Konuşma, Çoklu Getir. Bağlı her kanalda son hareket eden konuşmalar, en yeniden eskiye, her biri son mesajın önizlemesiyle.

Kişideki platform alanı Telegram, WhatsApp, Instagram, LinkedIn, X ve E-posta değerlerini kabul eder. Kişinin hangi kanaldan geldiğini kaydeder; CRM konuşmalarını sonrasında buna göre gruplar.

Bu listede olmayan hiçbir şey node’da yok. Mesaj gönderme, etiketleme, potansiyel puanı, görevler, faturalar ve otomasyon akışları REST API’de duruyor; sadece bu sekiz işlemin arasında değiller.

Birinci akış: form gönderimi kişiye dönüşür

Bu node’a uzanmanın en yaygın sebebi. Bir aday formu doldurur ve kayıt, kimse sekme açmadan CRM’de oluşur.

1. Formu tetikleyici yapın. n8n Form Trigger, kendi formunuzun arkasındaki bir Webhook node’u ya da Typeform veya Google Forms node’u. Sonraki node’a bir JSON nesnesi veren her şey iş görür.
2. Alanları Kişi, Oluştur işlemine eşleyin. Ad alanından ad, ardından ek alanlardan e-posta, telefon ve not. Aday mesajlaşma hesabı bırakmadıysa platformu E-posta yapın.
3. Dış kimliğe form gönderim numarasını yazın. İş akışını yeniden çalıştırılabilir yapan alan bu. Aynı dış kimlikle gelen ikinci oluşturma isteği HTTP 409 ile reddedilir ve hata gövdesi hâlihazırdaki kişiyi adlandırır; yani tekrar çalıştırma size ikinci bir kişi değil, bir mükerrerlik uyarısı verir.
4. Tekrar çalıştırmalar olağanlaştığında Continue On Fail’i açın. Açıkken 409, hata mesajı taşıyan bir öğe olarak gelir ve akışın geri kalanı devam eder. Kapalıyken çalıştırma durur; ilk denemede istediğiniz budur, gece üçte istediğiniz bu değildir.

409 yerine gerçek bir upsert davranışı istiyorsanız REST API’de toplu bir uç var: dış kimlik, e-posta, telefon veya kullanıcı adına göre eşleştirir ve istek başına 200 satıra kadar kabul eder. Node bunu sunmuyor. Bir HTTP Request node’unu POST /v1/contacts/batch adresine yöneltin; iki yüz çağrı yerine tek çağrıyla aynı sonucu alırsınız.

İkinci akış: kazanılan fırsat faturaya dönüşür

Kurmadan önce okumaya değer, çünkü akla ilk gelen tasarım yanlış olanı.

Bir fırsat API üzerinden kazanıldı durumuna hiç geçirilemez. Fırsatın kazanılması CRM defterine bir gelir kaydı düşer; bu yüzden o geçiş, bilerek, bir insanın baktığı panele bırakılmıştır. Node bunu birebir yansıtır: Fırsat, Oluştur işlemi kazanıldı ve kaybedildi aşamalarını reddeder ve bir güncelleme işlemi yoktur. Kazanılan fırsatları okursunuz, yazmazsınız.

1. Kazanılan fırsatları zamanlanmış olarak sorgulayın. On beş dakikada bir çalışan bir Schedule Trigger’dan CRM Solid, Fırsat, Çoklu Getir işlemine gidin ve aşama filtresini Kazanıldı yapın.
2. Yalnızca daha önce görmediklerinizi alın. Fırsatlar en yeni kimlikten başlayarak gelir. İşlediğiniz en yüksek kimliği iş akışının kalıcı verisinde saklayıp altındakileri eleyin ya da fırsat kimliğini faturanın referans alanına yazıp tekrarı muhasebe aracının reddetmesine bırakın.
3. Faturayı oluşturun. Başlığı, tutarı ve para birimini zaten kullandığınız faturalama node’una verin. Fırsat bir kişi kimliği taşır; önüne bir Kişi, Getir koyarsanız faturayı göndereceğiniz e-posta adresi de elinizde olur.

On beş dakika size yavaş geliyorsa sorgu aralığını kısaltmayın, abone olun: CRM Solid, deal.won olayında giden bir webhook tetikler. Gövde HMAC-SHA256 ile imzalanıp X-Webhook-Signature başlığında taşınır, olay adı da X-Webhook-Event başlığında gelir. Bunu bir n8n Webhook node’una yöneltirseniz fatura, fırsat kapandıktan saniyeler sonra çıkar ve tek bir sorgu bütçesi harcanmaz. Aynısı contact.created, contact.updated ve message.received için de geçerli.

Üçüncü akış: konuşmaları okuyup yönlendirmek

Konuşma, Çoklu Getir işlemi bağlı her kanalda son hareket eden konuşmaları döndürür: Telegram, WhatsApp, Instagram, X, e-posta ve site içi canlı destek tek listede. Her satır kişi kimliğini, kanalı, okunup okunmadığını ve son mesajın 160 karaktere kadar önizlemesini taşır.

1. Son konuşma listesini zamanlanmış olarak çekin. Çoğu gelen kutusu için 50’lik bir limit yeter. Üzerine bütçe harcamadan önce bir IF node’uyla okunmamışlara daraltın.
2. Önizlemeyi sınıflandırın. Önizleme metnini kullandığınız model node’undan geçirip tek bir etiket isteyin: fiyat sorusu, destek talebi, spam ya da yapılacak bir şey yok.
3. Etikete göre davranın. Fiyat sorularını satış ekibinin takip ettiği kanala düşürün, destek taleplerine kayıt açın, sınıflandırmayı da Kişi, Güncelle ile geri yazın ki sonuç yalnızca sohbette değil, kaydın üstünde dursun.

Bunu kurmadan önce iki sınır bilinmeli. Önizleme gerçekten bir önizlemedir: node tam mesaj geçmişini sayfalayamaz, dolayısıyla sınıflandırıcı yalnızca son mesajı görür. Ve node bir kişiyi etiketleyemez, yanıt gönderemez. İkisi de REST API’de ve MCP sunucusunda var; ikisi de bu sekiz işlemin arasında değil.

Sayfalama, limitler ve bir hatanın görünüşü

Bir iş akışının ilk gerçek haftasını atlatıp atlatamayacağını belirleyen üç davranış.

• Sayfalama imleç tabanlı. Liste yanıtı satırların yanında bir sonraki sayfanın imlecini taşır. Return All bu imleci sayfalar bitene kadar yürütür, limit ise erken durur. Sunucu tarafındaki sayfa sınırı kişiler ve fırsatlar için 100, konuşmalar için 50 satır; yani 4.000 kişilik bir Return All, bir istek değil 40 istektir.
• Hız sınırı anahtar başına. Varsayılan olarak dakikada altmış istek. Sınırı aşarsanız saniye cinsinden Retry-After ile HTTP 429 alırsınız; her yanıttaki üç X-RateLimit başlığı da sınıra ne kadar yaklaştığınızı söyler.
• Hatalar sebebini söyler. 401, anahtarın yanlış veya iptal edilmiş olduğu anlamına gelir. 403, anahtarın geçerli olduğunu ama işlemin bildirdiği kapsamı taşımadığını. 404, kimliğin bu çalışma alanına ait olmadığını; hiç var olmayan bir kimlik de bilerek aynı yanıtı alır. 409 ise bir dış kimlik çakışmasıdır ve o kimliği taşıyan kaydı adlandırır.

Node’un üzerinde durduğu API’den bir liste yanıtı:

{
  "items": [ { "Id": 812, "Name": "Sarah Lin", "Platform": "email" } ],
  "nextCursor": 764,
  "hasMore": true
}

Artımlı senkronlar Updated Since üzerinde çalışır. Son başarılı çalıştırmanın zaman damgasını saklayın, bir sonrakinde geçin; böylece hepsini değil, yalnızca değişen birkaç kişiyi çekersiniz. Gece çalışıp biten bir senkron ile bütün bütçesini kimsenin dokunmadığı satırlara harcayan bir senkron arasındaki fark budur.