Zapier, Make ve n8n

Entegrasyon platformları Sursa’yı kod yazmadan yüzlerce başka araca bağlar. Bunun için özel bir Sursa uygulamasına ihtiyaç duymazlar: genel HTTP isteği ve webhook adımları doğrudan API ile çalışır. Bu kılavuz en yaygın üç tarifi anlatır:

Hangi platformu kullanırsanız kullanın, anahtarı adımın kendisinde değil, platformun kimlik bilgileri ya da bağlantı deposunda tutun; böylece anahtar her senaryoya ve her çalıştırma günlüğüne kopyalanmaz.

Kayıtları kart olarak gönderme

Sursa’da bir özel kaynak oluşturun (Sources → New source → Custom source: kaynaklar → yeni kaynak → özel kaynak), ardından kaynak sayfasındaki API keys bölümünde bu kaynak için bir anahtar oluşturun. Anahtar kbsrc_ ile başlar ve yalnızca bu kaynağa belge yazabilir; bu da onu üçüncü taraf bir platformda saklanacak doğru anahtar yapar.

Yaygın kurulum şudur: “X’te bir kayıt oluşturulduğunda ya da güncellendiğinde onu Sursa’ya gönder”:

{
  "external_id": "{{record_id}}",
  "title": "{{record_title}}",
  "content": "{{record_body_html}}",
  "content_type": "html",
  "url": "{{record_link}}",
  "path": "{{record_category}}",
  "updated_at": "{{record_updated_at}}"
}

• Kaydın değişmeyen bir kimliğini external_id alanına eşleyin; hiçbir zaman bir zamanı ya da çalıştırma numarasını eşlemeyin. Böylece aynı kaydı yeniden göndermek aynı kartı günceller ve yeniden denenen bir adım zarar vermez: yanıt unchanged olur.
• “Kayıt silindi” tetikleyicisi için yöntemi DELETE, URL’si https://api.example.com/v1/push/sources/42/documents/{{record_id}} olan ikinci bir iş akışı ekleyin.
• Bağlantıyı GET https://api.example.com/v1/push/sources/42 isteği ve aynı Authorization başlığıyla test edin. Bu istek kaynağın adını ve belge sayısını döndürür.

Belge alanları, kodla gönderimdekiyle aynıdır.

Zapier

Webhooks by Zapier → Custom Request kullanın:

• Method: POST.
• URL: https://api.example.com/v1/push/sources/42/documents.
• Data Pass-Through: kapalı. Data: alanları tetikleyiciden eklenmiş, yukarıdaki JSON.
• Headers: Authorization = Bearer kbsrc_…, Content-Type = application/json.

Make

HTTP → Make a request modülünü kullanın:

• Method POST, URL yukarıdaki gibi, Headers Authorization: Bearer kbsrc_….
• Body type Raw, Content type JSON (application/json), Request content: değerleri eşlenmiş, yukarıdaki JSON.
• Sonraki modüllerde result değerini (created, updated, unchanged) kullanmak için Parse response seçeneğini açın.
• Dosya göndermek için Body type olarak Multipart/form-data seçin; bir file alanı (önceki bir modüldeki dosya) ve content dışındaki JSON alanlarını içeren bir document metin alanı ekleyin.

n8n

HTTP Request düğümünü kullanın:

• Method POST, URL yukarıdaki gibi.
• Authentication Generic Credential Type → Header Auth; adı Authorization, değeri Bearer kbsrc_….
• Send Body açık, Body Content Type JSON; alanlar {{ $json.id }} gibi ifadelerle eşlenir.

Zamanlanmış bir tam dışa aktarma için üç HTTP Request düğümünü art arda bağlayın: bir senkronizasyon açın (ilk seferde {"type": "initial"}, sonrasında {"type": "incremental"} gövdesiyle POST …/syncs), öğeleri gönderin ve senkronizasyonu {"status": "complete"} ile kapatın. n8n bir düğümü her öğe için bir kez çalıştırır; daha az istek göndermek için öğeleri bir Aggregate düğümüyle gruplayın ve {"sync_number": …, "documents": [...]} biçiminde …/documents/batch adresine gönderin.

Bir iş akışında soru sorma

Bir iş akışı Sursa’ya soru sorup yanıtı kullanabilir: bir destek talebine yanıt taslağı hazırlamak, bir CRM kaydını zenginleştirmek, bir sohbet kanalına yanıt göndermek. ask kapsamına ve doğru koleksiyonları görebilen bir role sahip bir kuruluş API anahtarı kullanın.

Yanıt, asistanın yanıtını answer alanında (Markdown) ve kaynaklarını sources alanında içerir; her kaynakta doc_name bulunur. Bilgi tabanında soruyla ilgili hiçbir şey yoksa empty alanı doldurulur (örneğin no_hits): iş akışının boş bir yanıt göndermemesi için bir filtre adımı ekleyin. Soru-cevap botu oluşturma bölümüne bakın.

Yanıtlar birkaç saniye sürebilir. Platformun HTTP adımının varsayılan zaman aşımı kısaysa onu en az 60 saniyeye çıkarın.

Bir Sursa olayından iş akışı başlatma

Her platform webhook alabilir:

1. Tetikleyiciyi oluşturun ve size verdiği HTTPS adresini kopyalayın.
2. Sursa’da bu adres ve istediğiniz olaylarla bir webhook kaydedin: Administration → Integrations → Webhooks and API (yönetim → entegrasyonlar → webhook’lar ve API) bölümünde ya da POST /v1/webhooks ile.
3. Webhook sayfasından bir test olayı gönderin ve sonraki adımlarda olayın alanlarını (type, data.card.title, …) eşleyin.

İmzayı kontrol edin. Tetikleyici adresi herkese açıktır: adresi öğrenen herkes ona istek gönderebilir. Özellikle iş akışı verileri değiştiriyorsa her teslimin imzasını, ona göre işlem yapmadan önce doğrulayın:

• n8n’de Webhook düğümünden sonra, Webhook’ları alma kılavuzundaki Node.js imza doğrulama koduyla bir Code düğümü ekleyin ve baytların tam olarak kullanılabilmesi için Webhook düğümünün ham gövde seçeneğini etkinleştirin.
• Ham gövdeye ulaşmanın daha zor olduğu Zapier ve Make’te en azından adresi gizli tutun, type alanına göre filtreleyin ve işlem yapmadan önce nesneyi API’den yeniden okuyun.

Yeniden denemeler ve yinelenen teslimler, her alıcıda olduğu gibi platformlar için de geçerlidir: yinelenen bir çalıştırma zarar verecekse olayın id değerine göre filtreleyin.

İpuçları

• 429 yanıtında platformun otomatik yeniden denemesinin Retry-After saniyesi kadar beklemesine izin verin. Büyük dışa aktarmalar için toplu gönderimleri tercih edin.
• Platformlar her isteği ve yanıtı günlüğe kaydeder. Anahtarı hiçbir zaman URL içine koymayın ve iş akışının tek yaptığı belge yazmaksa her yerde kbsrc_ anahtarını tercih edin.
• Bir adım 401 sources.push_key_invalid ile başarısız olursa URL’deki kaynak kimliğinin anahtarla eşleştiğini kontrol edin.