Zapier, Make és n8n

Az integrációs platformok kód nélkül kapcsolják össze a Sursát több száz más eszközzel. Nincs szükségük külön Sursa-alkalmazásra: az általános HTTP-kérés- és webhooklépéseik közvetlenül működnek az API-val. Ez az útmutató a három leggyakoribb receptet mutatja be:

Bármelyik platformot használod, a kulcsot a platform hitelesítőadat- vagy kapcsolattárában tartsd, ne magában a lépésben, hogy ne másolódjon bele minden forgatókönyvbe és futási naplóba.

Rekordok küldése kártyaként

Hozz létre egy egyéni forrást a Sursában (Sources → New source → Custom source, vagyis források → új forrás → egyéni forrás), majd a forrás oldalán az API keys szakaszban egy hozzá tartozó kulcsot. A kulcs kbsrc_ előtaggal kezdődik, és csak ebbe a forrásba írhat dokumentumokat, ezért ez a megfelelő kulcs egy külső platformon való tároláshoz.

A szokásos beállítás: „ha X-ben létrejön vagy frissül egy rekord, küldd el a Sursának”:

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

• Az external_id mezőhöz a rekord stabil azonosítóját rendeld, soha ne időpontot vagy futásszámot. Így ugyanannak a rekordnak az újraküldése ugyanazt a kártyát frissíti, és egy újrapróbált lépés ártalmatlan: a válasz unchanged.
• A „rekord törölve” eseményindítóhoz hozz létre egy második munkafolyamatot DELETE metódussal és a https://api.example.com/v1/push/sources/42/documents/{{record_id}} URL-lel.
• A kapcsolatot a GET https://api.example.com/v1/push/sources/42 kéréssel teszteld, ugyanazzal az Authorization fejléccel. Visszaadja a forrás nevét és a dokumentumai számát.

A dokumentum mezői ugyanazok, mint kódból.

Zapier

Használd a Webhooks by Zapier → Custom Request lépést:

• Method: POST.
• URL: https://api.example.com/v1/push/sources/42/documents.
• Data Pass-Through: kikapcsolva. Data: a fenti JSON, az eseményindítóból beillesztett mezőkkel.
• Headers: Authorization = Bearer kbsrc_…, Content-Type = application/json.

Make

Használd a HTTP → Make a request modult:

• Method POST, URL a fentiek szerint, Headers Authorization: Bearer kbsrc_….
• Body type Raw, Content type JSON (application/json), Request content: a fenti JSON a leképezett értékekkel.
• Kapcsold be a Parse response beállítást, hogy a későbbi modulokban használhasd a result értékét (created, updated, unchanged).
• Fájl küldéséhez válaszd a Body type Multipart/form-data beállítást egy file mezővel (egy korábbi modul fájljával) és egy document szövegmezővel, amely a content nélküli JSON-mezőket tartalmazza.

n8n

Használd a HTTP Request csomópontot:

• Method POST, URL a fentiek szerint.
• Authentication Generic Credential Type → Header Auth, Authorization névvel és Bearer kbsrc_… értékkel.
• Send Body bekapcsolva, Body Content Type JSON, a mezők kifejezésekkel leképezve, például {{ $json.id }}.

Ütemezett teljes exportáláshoz fűzz össze három HTTP Request csomópontot: nyiss meg egy szinkronizálást (POST …/syncs először {"type": "initial"}, azután {"type": "incremental"} értékkel), küldd el az elemeket, és zárd le a szinkronizálást a {"status": "complete"} értékkel. Az n8n elemenként egyszer futtat egy csomópontot; ha kevesebb kérést szeretnél küldeni, csoportosítsd az elemeket egy Aggregate csomóponttal, és küldd el őket a …/documents/batch végpontra {"sync_number": …, "documents": [...]} formában.

Kérdés egy munkafolyamatban

Egy munkafolyamat kérdezhet a Sursától, és felhasználhatja a választ: válaszvázlatot írhat egy ügyfélszolgálati jegyre, kiegészíthet egy CRM-rekordot, vagy választ tehet közzé egy csevegőcsatornán. Használd a szervezet egy ask hatókörű API-kulcsát, olyan szerepkörrel, amely a megfelelő gyűjteményeket látja.

A válasz az answer mezőben tartalmazza a választ (Markdown), a sources mezőben pedig a forrásait, mindegyiket doc_name értékkel. Ha a tudásbázisban semmi nincs a kérdésről, az empty be van állítva (például no_hits): adj hozzá egy szűrőlépést, hogy a munkafolyamat ne tegyen közzé üres választ. Lásd: Kérdés-válasz bot készítése.

A válaszok több másodpercig is eltarthatnak. Ha a platform HTTP-lépésének rövid az alapértelmezett időkorlátja, emeld meg legalább 60 másodpercre.

Munkafolyamat indítása Sursa-eseményből

Mindegyik platform tud webhookokat fogadni:

1. Hozd létre az eseményindítót, és másold ki a kapott HTTPS-címet.
2. A Sursában regisztrálj egy webhookot ezzel a címmel és a kívánt eseményekkel, az Administration → Integrations → Webhooks and API (adminisztráció → integrációk → webhookok és API) alatt vagy a POST /v1/webhooks végponttal.
3. Küldj teszteseményt a webhook oldaláról, és a következő lépésekben képezd le az esemény mezőit (type, data.card.title, …).

Ellenőrizd az aláírást. Az eseményindító címe nyilvános: bárki, aki megtudja, kéréseket küldhet rá. Mielőtt egy kézbesítés alapján bármit tennél, ellenőrizd az aláírását, különösen akkor, ha a munkafolyamat adatokat módosít:

• Az n8n-ben a Webhook csomópont után adj hozzá egy Code csomópontot a Webhookok fogadása útmutató Node.js-es aláírás-ellenőrző kódjával, és kapcsold be a Webhook csomópont nyers törzsre vonatkozó beállítását, hogy a pontos bájtok elérhetők legyenek.
• A Zapierben és a Make-ben, ahol a nyers törzs nehezebben érhető el, legalább tartsd titokban a címet, szűrj a type értékére, és mielőtt bármit tennél, olvasd ki újra az objektumot az API-ból.

Az újrapróbálkozások és az ismétlődések a platformokra ugyanúgy vonatkoznak, mint bármely fogadóra: ha egy ismétlődő futás kárt okozna, szűrj az esemény id értékére.

Tippek

• 429 esetén hagyd, hogy a platform automatikus újrapróbálkozása kivárja a Retry-After másodperceit. Nagy exportálásoknál részesítsd előnyben a kötegeket.
• A platformok minden kérést és választ naplóznak. Soha ne tegyél kulcsot URL-be, és ahol a munkafolyamat csak dokumentumokat ír, ott a kbsrc_ kulcsot részesítsd előnyben.
• Ha egy lépés 401 sources.push_key_invalid hibával meghiúsul, ellenőrizd, hogy az URL-ben szereplő forrásazonosító egyezik-e a kulccsal.