Zapier, Make ja n8n

Integratsiooniplatvormid ühendavad Sursa sadade teiste tööriistadega ilma koodita. Need ei vaja eraldi Sursa rakendust: nende üldised HTTP-päringu ja veebihaagi sammud töötavad otse API-ga. See juhend käsitleb kolme kõige levinumat retsepti:

Ükskõik millist platvormi kasutate, hoidke võtit selle autentimisandmete või ühenduste hoidlas, mitte sammus endas, et seda ei kopeeritaks igasse stsenaariumi ja käivituslogisse.

Kirjete saatmine kaartidena

Looge Sursas kohandatud allikas (Sources → New source → Custom source), seejärel allika lehel jaotises API keys selle võti. Võti algab eesliitega kbsrc_ ja saab kirjutada dokumente ainult sellesse allikasse, mistõttu on see õige võti kolmanda osapoole platvormil hoidmiseks.

Tavaline seadistus on „kui X-is luuakse või uuendatakse kirje, saada see Sursasse“:

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

• Vastendage väljale external_id kirje püsiv ID, mitte kunagi aeg ega käivituse number. Siis uuendab sama kirje uuesti saatmine sama kaarti ja korratud samm on ohutu: vastus on unchanged.
• Käivitaja „kirje kustutatud“ jaoks lisage teine töövoog, mille meetod on DELETE ja URL https://api.example.com/v1/push/sources/42/documents/{{record_id}}.
• Testige ühendust päringuga GET https://api.example.com/v1/push/sources/42 ja sama päisega Authorization. See tagastab allika nime ja selle dokumentide arvu.

Dokumendi väljad on samad mis koodis.

Zapier

Kasutage toimingut Webhooks by Zapier → Custom Request:

• Method: POST.
• URL: https://api.example.com/v1/push/sources/42/documents.
• Data Pass-Through: väljas. Data: ülaltoodud JSON, mille väljad on lisatud käivitajast.
• Headers: Authorization = Bearer kbsrc_…, Content-Type = application/json.

Make

Kasutage moodulit HTTP → Make a request:

• Method POST, URL nagu ülal, Headers Authorization: Bearer kbsrc_….
• Body type Raw, Content type JSON (application/json), Request content: ülaltoodud JSON vastendatud väärtustega.
• Lülitage sisse Parse response, et kasutada hilisemates moodulites välja result (created, updated, unchanged).
• Faili saatmiseks valige Body type Multipart/form-data väljaga file (fail varasemast moodulist) ja tekstiväljaga document, mis sisaldab JSON-välju ilma väljata content.

n8n

Kasutage sõlme HTTP Request:

• Method POST, URL nagu ülal.
• Authentication Generic Credential Type → Header Auth, nimega Authorization ja väärtusega Bearer kbsrc_….
• Send Body sisse lülitatud, Body Content Type JSON, väljad vastendatud avaldistega, näiteks {{ $json.id }}.

Ajastatud täieliku ekspordi jaoks ühendage kolm sõlme HTTP Request ahelaks: avage sünkroonimine (POST …/syncs, esimesel korral kehaga {"type": "initial"}, hiljem {"type": "incremental"}), saatke elemendid ja sulgege sünkroonimine kehaga {"status": "complete"}. n8n käivitab sõlme iga elemendi jaoks üks kord; vähemate päringute saatmiseks rühmitage elemendid sõlmega Aggregate ja saatke need lõpp-punktile …/documents/batch kujul {"sync_number": …, "documents": [...]}.

Küsimuse esitamine töövoos

Töövoog saab Sursalt küsida ja vastust kasutada: koostada tugipiletile vastuse mustandi, rikastada CRM-i kirjet, postitada vastuse vestluskanalisse. Kasutage organisatsiooni API-võtit ulatusega ask ja rolliga, mis näeb õigeid kogusid.

Vastuses on vastus väljal answer (Markdown) ja selle allikad väljal sources, igaühel doc_name. Kui teadmusbaasis ei ole küsimuse kohta midagi, on empty määratud (näiteks no_hits): lisage filtrisamm, et töövoog ei postitaks tühja vastust. Vt Küsimuste ja vastuste boti loomine.

Vastuse koostamine võib võtta mitu sekundit. Kui platvormi HTTP-sammul on lühike vaikimisi ajalõpp, suurendage see vähemalt 60 sekundini.

Töövoo käivitamine Sursa sündmusest

Iga platvorm saab veebihaake vastu võtta:

1. Looge käivitaja ja kopeerige HTTPS-aadress, mille see annab.
2. Registreerige Sursas selle aadressi ja soovitud sündmustega veebihaak jaotises Administration → Integrations → Webhooks and API või päringuga POST /v1/webhooks.
3. Saatke veebihaagi lehelt testsündmus ja vastendage järgmistes sammudes sündmuse väljad (type, data.card.title, …).

Kontrollige allkirja. Käivitaja aadress on avalik: igaüks, kes selle teada saab, võib sinna päringuid saata. Kontrollige iga edastuse allkirja enne selle põhjal tegutsemist, eriti kui töövoog muudab andmeid:

• n8n-is lisage sõlme Webhook järele sõlm Code Node.js-i allkirja kontrollimise koodiga juhendist Veebihaagide vastuvõtmine ja lülitage sõlmes Webhook sisse toore keha valik, et täpsed baidid oleksid saadaval.
• Platvormidel Zapier ja Make, kus toorest keha on raskem kätte saada, hoidke vähemalt aadress salajas, filtreerige välja type järgi ja lugege objekt enne selle põhjal tegutsemist API-st uuesti.

Korduskatsed ja duplikaadid kehtivad platvormidele nagu igale vastuvõtjale: filtreerige sündmuse välja id järgi, kui korduv käivitus võiks kahju teha.

Nõuanded

• Vastuse 429 korral laske platvormi automaatsel korduskatsel oodata päises Retry-After antud sekundid. Suurte eksportide puhul eelistage partiisid.
• Platvormid logivad iga päringu ja vastuse. Ärge kunagi pange võtit URL-i ja eelistage võtit kbsrc_ kõikjal, kus töövoog ainult kirjutab dokumente.
• Kui samm ebaõnnestub vastusega 401 sources.push_key_invalid, kontrollige, et URL-is olev allika ID vastaks võtmele.