Zapier, Make ir n8n

Integracijų platformos be kodo sujungia Sursą su šimtais kitų įrankių. Joms nereikia atskiros Sursos programos: jų bendrieji HTTP užklausos ir webhook žingsniai tiesiogiai veikia su API. Ši instrukcija aprašo tris dažniausius receptus:

Kad ir kurią platformą naudotumėte, raktą laikykite jos prisijungimo duomenų ar ryšių saugykloje, o ne pačiame žingsnyje, kad jis nebūtų kopijuojamas į kiekvieną scenarijų ir vykdymo žurnalą.

Įrašų siuntimas kortelių pavidalu

Sursoje sukurkite pasirinktinį šaltinį (Sources → New source → Custom source, t. y. šaltiniai, naujas šaltinis, pasirinktinis šaltinis), tada šaltinio puslapio skiltyje API keys sukurkite jam raktą. Raktas prasideda kbsrc_ ir gali tik rašyti dokumentus į šį šaltinį, todėl būtent jį tinka saugoti trečiosios šalies platformoje.

Įprasta sąranka – „kai X sistemoje sukuriamas ar atnaujinamas įrašas, siųsti jį į Sursą“:

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

• Su external_id susiekite pastovų įrašo ID, niekada ne laiką ar vykdymo numerį. Tada vėl išsiuntus tą patį įrašą atnaujinama ta pati kortelė, o pakartotas žingsnis nepakenkia: atsakas – unchanged.
• Paleidikliui „įrašas ištrintas“ pridėkite antrą darbo eigą su metodu DELETE ir URL https://api.example.com/v1/push/sources/42/documents/{{record_id}}.
• Ryšį patikrinkite užklausa GET https://api.example.com/v1/push/sources/42 su ta pačia antrašte Authorization. Ji grąžina šaltinio pavadinimą ir jo dokumentų skaičių.

Dokumento laukai tokie patys kaip ir kode.

Zapier

Naudokite Webhooks by Zapier → Custom Request:

• Method: POST.
• URL: https://api.example.com/v1/push/sources/42/documents.
• Data Pass-Through: išjungta. Data: aukščiau pateiktas JSON su laukais, įterptais iš paleidiklio.
• Headers: Authorization = Bearer kbsrc_…, Content-Type = application/json.

Make

Naudokite modulį HTTP → Make a request:

• Method POST, URL kaip aukščiau, Headers Authorization: Bearer kbsrc_….
• Body type Raw, Content type JSON (application/json), Request content: aukščiau pateiktas JSON su susietomis reikšmėmis.
• Įjunkite Parse response, kad vėlesniuose moduliuose galėtumėte naudoti result (created, updated, unchanged).
• Kad išsiųstumėte failą, pasirinkite Body type Multipart/form-data su lauku file (failas iš ankstesnio modulio) ir tekstiniu lauku document, kuriame yra JSON laukai be content.

n8n

Naudokite mazgą HTTP Request:

• Method POST, URL kaip aukščiau.
• Authentication Generic Credential Type → Header Auth, su pavadinimu Authorization ir reikšme Bearer kbsrc_….
• Send Body įjungta, Body Content Type JSON, laukai susieti išraiškomis, pavyzdžiui, {{ $json.id }}.

Pagal tvarkaraštį vykdomam visiškam eksportui sujunkite tris HTTP Request mazgus: atidarykite sinchronizaciją (POST …/syncs su {"type": "initial"} pirmą kartą, vėliau – su {"type": "incremental"}), išsiųskite elementus ir uždarykite sinchronizaciją su {"status": "complete"}. n8n mazgą vykdo kartą kiekvienam elementui; kad užklausų būtų mažiau, sugrupuokite elementus mazgu Aggregate ir siųskite juos į …/documents/batch kaip {"sync_number": …, "documents": [...]}.

Klausimas darbo eigoje

Darbo eiga gali paklausti Sursos ir panaudoti atsakymą: parengti atsakymo į pagalbos užklausą juodraštį, papildyti CRM įrašą, paskelbti atsakymą pokalbių kanale. Naudokite organizacijos API raktą su apimtimi ask ir vaidmeniu, kuris mato reikiamus rinkinius.

Atsake atsakymas pateikiamas lauke answer (Markdown), o jo šaltiniai – lauke sources, kiekvienas su doc_name. Kai žinių bazėje apie klausimą nieko nėra, nustatomas empty (pavyzdžiui, no_hits): pridėkite filtro žingsnį, kad darbo eiga neskelbtų tuščio atsakymo. Žr. Klausimų ir atsakymų boto kūrimas.

Atsakymas gali užtrukti kelias sekundes. Jei platformos HTTP žingsnio numatytasis laiko limitas trumpas, padidinkite jį bent iki 60 sekundžių.

Darbo eigos paleidimas pagal Sursos įvykį

Kiekviena platforma gali gauti webhook pranešimus:

1. Sukurkite paleidiklį ir nukopijuokite jo pateiktą HTTPS adresą.
2. Sursoje užregistruokite webhook galinį tašką su tuo adresu ir norimais įvykiais – skiltyje Administration → Integrations → Webhooks and API (administravimas, integracijos, webhook pranešimai ir API) arba operacija POST /v1/webhooks.
3. Iš webhook galinio taško puslapio išsiųskite bandomąjį įvykį ir tolesniuose žingsniuose susiekite įvykio laukus (type, data.card.title, …).

Patikrinkite parašą. Paleidiklio adresas viešas: kiekvienas, kas jį sužino, gali į jį siųsti užklausas. Pirmiausia patikrinkite kiekvieno pristatymo parašą ir tik tada imkitės veiksmų, ypač jei darbo eiga keičia duomenis:

• n8n po mazgo Webhook pridėkite mazgą Code su Node.js parašo tikrinimo kodu iš Webhook pranešimų gavimas ir įjunkite mazgo Webhook neapdoroto turinio parinktį, kad būtų prieinami tikslūs baitai.
• Zapier ir Make, kur neapdorotą turinį pasiekti sunkiau, bent jau laikykite adresą slaptą, filtruokite pagal type ir prieš imantis veiksmų dar kartą nuskaitykite objektą per API.

Pakartojimai ir dublikatai platformoms taikomi kaip ir bet kuriam gavėjui: jei pakartotinis vykdymas pakenktų, filtruokite pagal įvykio id.

Patarimai

• Gavus 429, leiskite platformos automatiniam pakartojimui palaukti Retry-After nurodytą sekundžių skaičių. Dideliems eksportams rinkitės partijas.
• Platformos registruoja kiekvieną užklausą ir atsaką. Niekada nerašykite rakto URL adrese ir rinkitės kbsrc_ raktą visur, kur darbo eiga tik rašo dokumentus.
• Jei žingsnis nepavyksta su 401 sources.push_key_invalid, patikrinkite, ar šaltinio ID URL adrese atitinka raktą.