Zapier, Make i n8n

Platforme za integracije povezuju Sursu sa stotinama drugih alata bez pisanja koda. Ne treba im namjenska aplikacija za Sursu: njihovi opći koraci za HTTP zahtjeve i webhookove rade izravno s API-jem. Ovaj vodič obuhvaća tri najčešća recepta:

Koju god platformu koristili, ključ čuvajte u njezinu spremištu vjerodajnica ili veza, a ne u samom koraku, kako se ne bi kopirao u svaki scenarij i zapisnik izvođenja.

Slanje zapisa kao kartica

U Sursi stvorite vlastiti izvor (Sources → New source → Custom source – izvori, novi izvor, vlastiti izvor), a zatim ključ za njega na stranici izvora u odjeljku API keys. Ključ počinje s kbsrc_ i može samo zapisivati dokumente u ovaj izvor, zbog čega je pravi ključ za pohranu na platformi treće strane.

Uobičajena postavka glasi „kad se zapis stvori ili ažurira u X, pošalji ga u Sursu”:

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

• Na external_id mapirajte stabilan ID zapisa, nikada vrijeme ili broj izvođenja. Ponovno slanje istog zapisa tada ažurira istu karticu, a ponovljeni korak je bezopasan: odgovor je unchanged.
• Za okidač „zapis izbrisan” dodajte drugi tijek rada s metodom DELETE i URL-om https://api.example.com/v1/push/sources/42/documents/{{record_id}}.
• Vezu testirajte pomoću GET https://api.example.com/v1/push/sources/42 s istim zaglavljem Authorization. Vraća ime izvora i broj njegovih dokumenata.

Polja dokumenta ista su kao i za kod.

Zapier

Koristite Webhooks by Zapier → Custom Request:

• Method: POST.
• URL: https://api.example.com/v1/push/sources/42/documents.
• Data Pass-Through: isključeno. Data: JSON iznad, s poljima umetnutima iz okidača.
• Headers: Authorization = Bearer kbsrc_…, Content-Type = application/json.

Make

Koristite modul HTTP → Make a request:

• Method POST, URL kao gore, Headers Authorization: Bearer kbsrc_….
• Body type Raw, Content type JSON (application/json), Request content: JSON iznad s mapiranim vrijednostima.
• Uključite Parse response kako biste u kasnijim modulima mogli koristiti result (created, updated, unchanged).
• Da biste poslali datoteku, odaberite Body type Multipart/form-data s poljem file (datoteka iz ranijeg modula) i tekstnim poljem document koje sadrži JSON polja bez content.

n8n

Koristite čvor HTTP Request:

• Method POST, URL kao gore.
• Authentication Generic Credential Type → Header Auth, s imenom Authorization i vrijednošću Bearer kbsrc_….
• Send Body uključeno, Body Content Type JSON, polja mapirana izrazima kao što je {{ $json.id }}.

Za zakazani potpuni izvoz povežite tri čvora HTTP Request: otvorite sinkronizaciju (POST …/syncs s {"type": "initial"} prvi put, a nakon toga s {"type": "incremental"}), pošaljite stavke i zatvorite sinkronizaciju s {"status": "complete"}. n8n pokreće čvor jednom za svaku stavku; da biste slali manje zahtjeva, grupirajte stavke čvorom Aggregate i pošaljite ih na …/documents/batch kao {"sync_number": …, "documents": [...]}.

Pitanje u tijeku rada

Tijek rada može postaviti pitanje Sursi i iskoristiti odgovor: napisati nacrt odgovora na zahtjev za podršku, obogatiti zapis u CRM-u, objaviti odgovor u kanalu chata. Koristite API ključ organizacije s opsegom ask i ulogom koja vidi prave zbirke.

Odgovor sadrži tekst odgovora u answer (Markdown) i njegove izvore u sources, svaki s doc_name. Kad baza znanja nema ništa o pitanju, postavlja se empty (na primjer no_hits): dodajte korak filtriranja kako tijek rada ne bi objavio prazan odgovor. V. Izrada bota za pitanja i odgovore.

Odgovori mogu trajati nekoliko sekundi. Ako HTTP korak platforme ima kratko zadano vrijeme čekanja (timeout), povećajte ga na najmanje 60 sekundi.

Pokretanje tijeka rada iz događaja u Sursi

Svaka platforma može primati webhookove:

1. Stvorite okidač i kopirajte HTTPS adresu koju vam daje.
2. U Sursi registrirajte webhook s tom adresom i događajima koje želite, u Administration → Integrations → Webhooks and API (administracija, integracije, webhookovi i API) ili pomoću POST /v1/webhooks.
3. Pošaljite probni događaj sa stranice webhooka i u sljedećim koracima mapirajte polja događaja (type, data.card.title, …).

Provjerite potpis. Adresa okidača je javna: svatko tko je sazna može na nju slati zahtjeve. Prije nego što postupite prema isporuci, provjerite njezin potpis, osobito ako tijek rada mijenja podatke:

• U n8n-u nakon čvora Webhook dodajte čvor Code s provjerom potpisa za Node.js iz vodiča Primanje webhookova i uključite opciju sirovog tijela u čvoru Webhook kako bi točni bajtovi bili dostupni.
• U Zapieru i Makeu, gdje je do sirovog tijela teže doći, barem čuvajte adresu u tajnosti, filtrirajte prema type i prije nego što postupite ponovno pročitajte objekt putem API-ja.

Ponovni pokušaji i duplikati vrijede za platforme kao i za svakog primatelja: filtrirajte prema id događaja ako bi dvostruko izvođenje bilo štetno.

Savjeti

• Pri 429 neka automatski ponovni pokušaj platforme pričeka onoliko sekundi koliko navodi Retry-After. Za velike izvoze prednost dajte paketima.
• Platforme bilježe svaki zahtjev i odgovor. Nikada ne stavljajte ključ u URL i prednost dajte ključu kbsrc_ gdje god tijek rada samo zapisuje dokumente.
• Ako korak ne uspije s 401 sources.push_key_invalid, provjerite odgovara li ID izvora u URL-u ključu.