Zapier, Make, dan n8n

Platform integrasi menghubungkan Sursa ke ratusan alat lain tanpa kode. Platform itu tidak membutuhkan aplikasi Sursa khusus: langkah permintaan HTTP dan webhook umumnya bekerja langsung dengan API. Panduan ini membahas tiga resep yang paling umum:

Platform mana pun yang Anda pakai, simpan kunci di penyimpanan kredensial atau koneksi platform itu, bukan di langkahnya sendiri, agar kunci tidak tersalin ke setiap skenario dan log eksekusi.

Mengirim catatan sebagai kartu

Buat sumber kustom di Sursa (Sources → New source → Custom source (Sumber → Sumber baru → Sumber kustom)), lalu buat kunci untuknya di halaman sumber melalui API keys (kunci API sumber). Kunci ini diawali kbsrc_ dan hanya dapat menulis dokumen ke sumber ini, sehingga inilah kunci yang tepat untuk disimpan di platform pihak ketiga.

Pengaturan yang umum adalah “saat catatan dibuat atau diperbarui di X, kirim ke Sursa”:

{
  "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}}"
}

• Petakan ID catatan yang stabil ke external_id, jangan pernah waktu atau nomor eksekusi. Dengan begitu, mengirim catatan yang sama lagi akan memperbarui kartu yang sama, dan langkah yang dicoba ulang tidak berbahaya: jawabannya adalah unchanged.
• Untuk pemicu “catatan dihapus”, tambahkan alur kerja kedua dengan Method DELETE dan URL https://api.example.com/v1/push/sources/42/documents/{{record_id}}.
• Uji koneksi dengan GET https://api.example.com/v1/push/sources/42 dan header Authorization yang sama. Permintaan ini mengembalikan nama sumber dan jumlah dokumennya.

Field dokumen sama dengan yang dipakai dalam kode.

Zapier

Pakai Webhooks by Zapier → Custom Request:

• Method: POST.
• URL: https://api.example.com/v1/push/sources/42/documents.
• Data Pass-Through: nonaktif. Data: JSON di atas, dengan field yang disisipkan dari pemicu.
• Headers: Authorization = Bearer kbsrc_…, Content-Type = application/json.

Make

Pakai modul HTTP → Make a request:

• Method POST, URL seperti di atas, Headers Authorization: Bearer kbsrc_….
• Body type Raw, Content type JSON (application/json), Request content: JSON di atas dengan nilai yang dipetakan.
• Aktifkan Parse response untuk memakai result (created, updated, unchanged) di modul berikutnya.
• Untuk mengirim file, pilih Body type Multipart/form-data dengan field file (file dari modul sebelumnya) dan field teks document yang berisi field JSON tanpa content.

n8n

Pakai node HTTP Request:

• Method POST, URL seperti di atas.
• Authentication Generic Credential Type → Header Auth, dengan nama Authorization dan nilai Bearer kbsrc_….
• Send Body aktif, Body Content Type JSON, field dipetakan dengan ekspresi seperti {{ $json.id }}.

Untuk ekspor penuh terjadwal, rangkai tiga node HTTP Request: buka sinkronisasi (POST …/syncs dengan {"type": "initial"} pada kali pertama, {"type": "incremental"} sesudahnya), kirim item-itemnya, dan tutup sinkronisasi dengan {"status": "complete"}. n8n menjalankan node sekali per item; untuk mengirim lebih sedikit permintaan, kelompokkan item dengan node Aggregate dan kirim ke …/documents/batch sebagai {"sync_number": …, "documents": [...]}.

Mengajukan pertanyaan dalam alur kerja

Alur kerja dapat bertanya kepada Sursa dan memakai jawabannya: menyusun draf balasan untuk tiket dukungan, memperkaya catatan CRM, memposting jawaban di kanal chat. Pakai kunci API organisasi dengan cakupan ask dan peran yang dapat melihat koleksi yang tepat.

Respons berisi jawaban di answer (Markdown) dan sumbernya di sources, masing-masing dengan doc_name. Jika basis pengetahuan tidak memiliki apa pun tentang pertanyaan itu, empty diisi (misalnya no_hits): tambahkan langkah penyaring agar alur kerja tidak memposting jawaban kosong. Lihat Membuat bot tanya jawab.

Jawaban dapat memakan waktu beberapa detik. Jika langkah HTTP platform memiliki timeout default yang singkat, naikkan menjadi setidaknya 60 detik.

Memulai alur kerja dari peristiwa Sursa

Setiap platform dapat menerima webhook:

1. Buat pemicu dan salin alamat HTTPS yang diberikannya.
2. Di Sursa, daftarkan webhook dengan alamat itu dan peristiwa yang Anda inginkan, melalui Administration → Integrations → Webhooks and API (Administrasi → Integrasi → Webhook dan API) atau dengan POST /v1/webhooks.
3. Kirim peristiwa uji dari halaman webhook, dan petakan field peristiwa (type, data.card.title, …) di langkah berikutnya.

Periksa tanda tangan. Alamat pemicu bersifat publik: siapa pun yang mengetahuinya dapat mengirim permintaan ke sana. Periksa tanda tangan setiap pengiriman sebelum menindaklanjutinya, terutama jika alur kerja mengubah data:

• Di n8n, tambahkan node Code setelah node Webhook dengan kode pemeriksa Node.js dari Menerima webhook, dan aktifkan opsi raw body pada node Webhook agar byte yang persis tersedia.
• Di Zapier dan Make, tempat raw body lebih sulit dijangkau, setidaknya rahasiakan alamatnya, saring menurut type, dan baca lagi objeknya dari API sebelum menindaklanjutinya.

Percobaan ulang dan duplikat berlaku untuk platform seperti untuk penerima mana pun: saring menurut id peristiwa jika eksekusi duplikat dapat merugikan.

Tips

• Pada 429, biarkan percobaan ulang otomatis platform menunggu selama jumlah detik di Retry-After. Utamakan batch untuk ekspor besar.
• Platform mencatat setiap permintaan dan respons. Jangan pernah meletakkan kunci di URL, dan utamakan kunci kbsrc_ jika alur kerja hanya menulis dokumen.
• Jika langkah gagal dengan 401 sources.push_key_invalid, periksa bahwa ID sumber di URL sesuai dengan kuncinya.