Zapier, Make a n8n

Integračné platformy prepájajú Sursu so stovkami ďalších nástrojov bez kódu. Nepotrebujú na to samostatnú aplikáciu Sursa: ich všeobecné kroky požiadavky HTTP a webhooku pracujú priamo s API. Tento návod opisuje tri najčastejšie postupy:

Nech používate ktorúkoľvek platformu, kľúč uchovávajte v jej úložisku prihlasovacích údajov alebo pripojení, nie priamo v kroku, aby sa nekopíroval do každého scenára a logu behu.

Odosielanie záznamov ako kariet

V Surse vytvorte vlastný zdroj (Sources → New source → Custom source – zdroje → nový zdroj → vlastný zdroj) a potom preň na stránke zdroja v sekcii API keys vytvorte kľúč. Kľúč začína na kbsrc_ a smie len zapisovať dokumenty do tohto zdroja, preto je to ten správny kľúč na uloženie v platforme tretej strany.

Bežné nastavenie je „keď sa v X vytvorí alebo zmení záznam, pošli ho do Sursy“:

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

• Do external_id namapujte stabilný identifikátor záznamu, nikdy nie čas ani číslo behu. Opätovné odoslanie toho istého záznamu potom aktualizuje tú istú kartu a opakovaný krok neuškodí: odpoveď je unchanged.
• Pre spúšťač „záznam vymazaný“ pridajte druhý workflow s metódou DELETE a URL https://api.example.com/v1/push/sources/42/documents/{{record_id}}.
• Pripojenie otestujte cez GET https://api.example.com/v1/push/sources/42 s rovnakou hlavičkou Authorization. Vráti názov zdroja a počet jeho dokumentov.

Polia dokumentu sú rovnaké ako pri kóde.

Zapier

Použite Webhooks by Zapier → Custom Request:

• Method: POST.
• URL: https://api.example.com/v1/push/sources/42/documents.
• Data Pass-Through: vypnuté. Data: JSON vyššie s poliami vloženými zo spúšťača.
• Headers: Authorization = Bearer kbsrc_…, Content-Type = application/json.

Make

Použite modul HTTP → Make a request:

• Method POST, URL ako vyššie, Headers Authorization: Bearer kbsrc_….
• Body type Raw, Content type JSON (application/json), Request content: JSON vyššie s namapovanými hodnotami.
• Zapnite Parse response, aby ste mohli v ďalších moduloch použiť result (created, updated, unchanged).
• Ak chcete poslať súbor, zvoľte Body type Multipart/form-data s poľom file (súbor z predchádzajúceho modulu) a textovým poľom document, ktoré obsahuje polia JSON bez content.

n8n

Použite uzol HTTP Request:

• Method POST, URL ako vyššie.
• Authentication Generic Credential Type → Header Auth s názvom Authorization a hodnotou Bearer kbsrc_….
• Send Body zapnuté, Body Content Type JSON, polia namapované výrazmi, napríklad {{ $json.id }}.

Pri plánovanom úplnom exporte zreťazte tri uzly HTTP Request: otvorte synchronizáciu (POST …/syncs s {"type": "initial"} prvýkrát, potom s {"type": "incremental"}), odošlite položky a synchronizáciu uzavrite s {"status": "complete"}. n8n spúšťa uzol raz pre každú položku; ak chcete posielať menej požiadaviek, zoskupte položky uzlom Aggregate a odošlite ich na …/documents/batch ako {"sync_number": …, "documents": [...]}.

Otázka vo workflow

Workflow (pracovný postup) môže položiť otázku Surse a použiť odpoveď: pripraviť návrh odpovede na požiadavku zákazníckej podpory, obohatiť záznam v CRM, zverejniť odpoveď v kanáli chatu. Použite kľúč API organizácie s rozsahom ask a rolou, ktorá vidí správne kolekcie.

Odpoveď obsahuje text odpovede v answer (Markdown) a jej zdroje v sources, každý s doc_name. Keď báza znalostí k otázke nič nemá, nastaví sa empty (napríklad no_hits): pridajte krok filtra, aby workflow nezverejnil prázdnu odpoveď. Pozri Vytvorte bota na otázky a odpovede.

Odpoveď môže trvať niekoľko sekúnd. Ak má krok HTTP platformy krátky predvolený časový limit, zvýšte ho aspoň na 60 sekúnd.

Spustenie workflow z udalosti Sursy

Každá platforma dokáže prijímať webhooky:

1. Vytvorte spúšťač a skopírujte adresu HTTPS, ktorú vám poskytne.
2. V Surse zaregistrujte webhook s touto adresou a požadovanými udalosťami v časti Administration → Integrations → Webhooks and API (administrácia → integrácie → webhooky) alebo cez POST /v1/webhooks.
3. Zo stránky webhooku odošlite testovaciu udalosť a v ďalších krokoch namapujte polia udalosti (type, data.card.title, …).

Overte podpis. Adresa spúšťača je verejná: ktokoľvek, kto ju zistí, na ňu môže posielať požiadavky. Pred spracovaním každého doručenia overte jeho podpis, najmä ak workflow mení údaje:

• V n8n pridajte za uzol Webhook uzol Code s overením podpisu v Node.js z návodu Prijímajte webhooky a v uzle Webhook zapnite možnosť surového tela, aby boli k dispozícii presné bajty.
• V Zapieri a Make, kde sa k surovému telu dostanete ťažšie, aspoň uchovávajte adresu v tajnosti, filtrujte podľa type a pred spracovaním si objekt znova načítajte z API.

Opakovania a duplicity platia pre platformy rovnako ako pre každého príjemcu: ak by duplicitný beh uškodil, filtrujte podľa id udalosti.

Tipy

• Pri 429 nechajte automatické opakovanie platformy počkať počet sekúnd z Retry-After. Pri veľkých exportoch uprednostnite dávky.
• Platformy zapisujú do logu každú požiadavku a odpoveď. Kľúč nikdy nedávajte do URL a všade, kde workflow len zapisuje dokumenty, uprednostnite kľúč kbsrc_.
• Ak krok zlyhá s 401 sources.push_key_invalid, overte, či ID zdroja v URL zodpovedá kľúču.