Zapier, Make ja n8n

Integraatioalustat yhdistävät Sursan satoihin muihin työkaluihin ilman koodia. Ne eivät tarvitse erillistä Sursa-sovellusta: niiden yleiset HTTP-pyyntö- ja webhook-vaiheet toimivat suoraan API:n kanssa. Tämä opas käsittelee kolme yleisintä reseptiä:

Mitä alustaa käytätkin, säilytä avain sen tunnistetieto- tai yhteysvarastossa eikä itse vaiheessa, jotta sitä ei kopioida jokaiseen skenaarioon ja ajolokiin.

Tietueiden lähettäminen kortteina

Luo Sursaan mukautettu lähde (Sources → New source → Custom source) ja sille avain lähteen sivun API keys -osiossa. Avaimen alussa on kbsrc_, ja sillä voi vain kirjoittaa asiakirjoja tähän lähteeseen, joten se on oikea avain säilytettäväksi kolmannen osapuolen alustalla.

Tavallinen asetelma on ”kun tietue luodaan tai päivitetään X:ssä, lähetä se Sursaan”:

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

• Yhdistä external_id-kenttään tietueen pysyvä tunnus, ei koskaan aikaa tai ajon numeroa. Saman tietueen lähettäminen uudelleen päivittää silloin saman kortin, ja uudelleen yritetty vaihe on vaaraton: vastaus on unchanged.
• Lisää ”tietue poistettu” -käynnistintä varten toinen työnkulku, jossa metodi on DELETE ja URL https://api.example.com/v1/push/sources/42/documents/{{record_id}}.
• Testaa yhteys pyynnöllä GET https://api.example.com/v1/push/sources/42 samalla Authorization-otsakkeella. Se palauttaa lähteen nimen ja sen asiakirjojen määrän.

Asiakirjan kentät ovat samat kuin koodissa.

Zapier

Käytä toimintoa Webhooks by Zapier → Custom Request:

• Method: POST.
• URL: https://api.example.com/v1/push/sources/42/documents.
• Data Pass-Through: pois päältä. Data: yllä oleva JSON, johon kentät on lisätty käynnistimestä.
• Headers: Authorization = Bearer kbsrc_…, Content-Type = application/json.

Make

Käytä moduulia HTTP → Make a request:

• Method POST, URL kuten yllä, Headers Authorization: Bearer kbsrc_….
• Body type Raw, Content type JSON (application/json), Request content: yllä oleva JSON yhdistetyillä arvoilla.
• Ota käyttöön Parse response, jotta voit käyttää result-arvoa (created, updated, unchanged) myöhemmissä moduuleissa.
• Jos haluat lähettää tiedoston, valitse Body type Multipart/form-data, johon tulee file-kenttä (aiemman moduulin tiedosto) ja document-tekstikenttä, jossa ovat JSON-kentät ilman content-kenttää.

n8n

Käytä solmua HTTP Request:

• Method POST, URL kuten yllä.
• Authentication Generic Credential Type → Header Auth, nimenä Authorization ja arvona Bearer kbsrc_….
• Send Body päälle, Body Content Type JSON, kentät yhdistettyinä lausekkeilla, kuten {{ $json.id }}.

Ajastettua täyttä vientiä varten ketjuta kolme HTTP Request -solmua: avaa synkronointi (POST …/syncs, ensimmäisellä kerralla {"type": "initial"}, sen jälkeen {"type": "incremental"}), lähetä kohteet ja sulje synkronointi arvolla {"status": "complete"}. n8n suorittaa solmun kerran kutakin kohdetta kohden; jos haluat lähettää vähemmän pyyntöjä, ryhmittele kohteet Aggregate-solmulla ja lähetä ne osoitteeseen …/documents/batch muodossa {"sync_number": …, "documents": [...]}.

Kysymys työnkulussa

Työnkulku voi kysyä Sursalta ja käyttää vastausta: luonnostella vastauksen tukipyyntöön, rikastaa CRM-tietuetta, julkaista vastauksen chat-kanavalla. Käytä organisaation API-avainta, jolla on käyttöalue ask ja rooli, joka näkee oikeat kokoelmat.

Vastauksessa on itse vastaus answer-kentässä (Markdown) ja sen lähteet sources-kentässä, kussakin doc_name. Kun tietopankissa ei ole kysymyksestä mitään, empty on asetettu (esimerkiksi no_hits): lisää suodatinvaihe, jotta työnkulku ei julkaise tyhjää vastausta. Ks. Kysymys–vastaus-botin rakentaminen.

Vastaukset voivat kestää useita sekunteja. Jos alustan HTTP-vaiheen oletusaikakatkaisu on lyhyt, nosta se vähintään 60 sekuntiin.

Työnkulun käynnistäminen Sursan tapahtumasta

Jokainen alusta voi vastaanottaa webhookeja:

1. Luo käynnistin ja kopioi sen antama HTTPS-osoite.
2. Rekisteröi Sursassa webhook tällä osoitteella ja haluamillasi tapahtumilla kohdassa Administration → Integrations → Webhooks and API tai POST /v1/webhooks -pyynnöllä.
3. Lähetä testitapahtuma webhookin sivulta ja yhdistä tapahtuman kentät (type, data.card.title, …) seuraaviin vaiheisiin.

Tarkista allekirjoitus. Käynnistimen osoite on julkinen: kuka tahansa, joka saa sen tietoonsa, voi lähettää siihen pyyntöjä. Tarkista kunkin toimituksen allekirjoitus ennen kuin toimit sen perusteella, varsinkin jos työnkulku muuttaa tietoja:

• Lisää n8n:ssä Webhook-solmun jälkeen Code-solmu, jossa on Node.js-kielinen allekirjoituksen tarkistuskoodi oppaasta Webhookien vastaanottaminen, ja ota käyttöön Webhook-solmun raakarungon asetus, jotta tarkat tavut ovat saatavilla.
• Zapierissa ja Makessa, joissa raakarunkoon on vaikeampi päästä käsiksi, pidä ainakin osoite salassa, suodata type-kentän mukaan ja lue objekti uudelleen API:sta ennen kuin toimit sen perusteella.

Uusintayritykset ja kaksoiskappaleet koskevat alustoja samoin kuin mitä tahansa vastaanottajaa: suodata tapahtuman id-kentän mukaan, jos kaksinkertainen ajo olisi haitallinen.

Vinkkejä

• Kun vastaus on 429, anna alustan automaattisen uusintayrityksen odottaa Retry-After-otsakkeen ilmoittamat sekunnit. Suosi suurissa vienneissä eriä.
• Alustat kirjaavat lokiin jokaisen pyynnön ja vastauksen. Älä koskaan laita avainta URL-osoitteeseen, ja suosi kbsrc_-avainta aina, kun työnkulku vain kirjoittaa asiakirjoja.
• Jos vaihe epäonnistuu virheellä 401 sources.push_key_invalid, tarkista, että URL-osoitteen lähteen tunnus vastaa avainta.