Zapier, Make a n8n

Integrační platformy propojují Sursu se stovkami dalších nástrojů bez psaní kódu. Nepotřebují k tomu vyhrazenou aplikaci Sursa: jejich obecné kroky pro požadavky HTTP a webhooky pracují s API přímo. Tento návod popisuje tři nejběžnější postupy:

Ať používáte kteroukoli platformu, uchovávejte klíč v jejím úložišti přihlašovacích údajů nebo připojení, ne přímo v kroku, aby se nekopíroval do každého scénáře a protokolu běhu.

Odesílání záznamů jako karet

V Surse vytvořte vlastní zdroj (Sources → New source → Custom source – zdroje → nový zdroj → vlastní zdroj) a pak pro něj klíč na stránce zdroje v sekci API keys (klíče API zdroje). Klíč začíná na kbsrc_ a může jen zapisovat dokumenty do tohoto zdroje, a proto je to ten správný klíč k uložení na platformě třetí strany.

Běžné nastavení zní „když se v X vytvoří nebo aktualizuje 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 mapujte stabilní identifikátor záznamu, nikdy čas ani číslo běhu. Opětovné odeslání stejného záznamu pak aktualizuje stejnou kartu a zopakovaný krok nic nepokazí: odpověď je unchanged.
• Pro spouštěč „záznam smazán“ přidejte druhé workflow s metodou DELETE a URL https://api.example.com/v1/push/sources/42/documents/{{record_id}}.
• Připojení otestujte pomocí GET https://api.example.com/v1/push/sources/42 se stejnou hlavičkou Authorization. Vrátí název zdroje a počet jeho dokumentů.

Pole dokumentu jsou stejná jako při práci z kódu.

Zapier

Použijte Webhooks by Zapier → Custom Request:

• Method: POST.
• URL: https://api.example.com/v1/push/sources/42/documents.
• Data Pass-Through: vypnuto. Data: JSON výše s poli vloženými ze spouštěče.
• Headers: Authorization = Bearer kbsrc_…, Content-Type = application/json.

Make

Použijte modul HTTP → Make a request:

• Method POST, URL jako výše, Headers Authorization: Bearer kbsrc_….
• Body type Raw, Content type JSON (application/json), Request content: JSON výše s namapovanými hodnotami.
• Zapněte Parse response, aby bylo možné result (created, updated, unchanged) použít v dalších modulech.
• Chcete-li odeslat soubor, zvolte Body type Multipart/form-data s polem file (soubor z dřívějšího modulu) a textovým polem document, které obsahuje pole JSON bez content.

n8n

Použijte uzel HTTP Request:

• Method POST, URL jako výše.
• Authentication Generic Credential Type → Header Auth s názvem Authorization a hodnotou Bearer kbsrc_….
• Send Body zapnuto, Body Content Type JSON, pole namapovaná výrazy, například {{ $json.id }}.

Pro plánovaný úplný export zřetězte tři uzly HTTP Request: otevřete synchronizaci (POST …/syncs s {"type": "initial"} poprvé a {"type": "incremental"} později), odešlete položky a synchronizaci uzavřete s {"status": "complete"}. n8n spouští uzel jednou pro každou položku; chcete-li odesílat méně požadavků, seskupte položky uzlem Aggregate a odešlete je na …/documents/batch jako {"sync_number": …, "documents": [...]}.

Otázka ve workflow

Workflow (pracovní postup) se může zeptat Sursy a odpověď použít: připravit návrh odpovědi na požadavek podpory, doplnit záznam v CRM, zveřejnit odpověď v chatovacím kanálu. Použijte klíč API organizace s rozsahem ask a rolí, která vidí správné kolekce.

Odpověď obsahuje text odpovědi v answer (Markdown) a její zdroje v sources, každý s doc_name. Když znalostní báze k otázce nic nemá, je nastaveno empty (například no_hits): přidejte krok s filtrem, aby workflow nezveřejnilo prázdnou odpověď. Viz Vytvořte bota pro otázky a odpovědi.

Odpovědi mohou trvat několik sekund. Pokud má krok HTTP platformy krátký výchozí časový limit, zvyšte ho alespoň na 60 sekund.

Spuštění workflow událostí Sursy

Každá platforma umí přijímat webhooky:

1. Vytvořte spouštěč a zkopírujte adresu HTTPS, kterou vám přidělí.
2. V Surse zaregistrujte webhook s touto adresou a požadovanými událostmi, v Administration → Integrations → Webhooks and API (administrace → integrace → webhooky) nebo pomocí POST /v1/webhooks.
3. Ze stránky webhooku odešlete testovací událost a v dalších krocích namapujte pole události (type, data.card.title, …).

Ověřte podpis. Adresa spouštěče je veřejná: kdokoli, kdo ji zná, na ni může posílat požadavky. Před zpracováním každého doručení ověřte jeho podpis, zvlášť pokud workflow mění data:

• V n8n přidejte za uzel Webhook uzel Code s ověřením podpisu v Node.js z návodu Příjem webhooků a zapněte u uzlu Webhook možnost nezpracovaného těla (raw body), aby byly k dispozici přesné bajty.
• V Zapieru a Make, kde se k nezpracovanému tělu dostanete hůř, alespoň udržujte adresu v tajnosti, filtrujte podle type a před zpracováním si objekt znovu přečtěte z API.

Opakování a duplicity platí pro platformy stejně jako pro jakéhokoli příjemce: pokud by duplicitní běh škodil, filtrujte podle id události.

Tipy

• Při 429 nechte automatické opakování platformy počkat po dobu Retry-After v sekundách. U velkých exportů dávejte přednost dávkám.
• Platformy zaznamenávají každý požadavek a odpověď. Nikdy nedávejte klíč do URL a všude, kde workflow jen zapisuje dokumenty, dávejte přednost klíči kbsrc_.
• Pokud krok selže s 401 sources.push_key_invalid, zkontrolujte, že ID zdroje v URL odpovídá klíči.