Zapier, Make og n8n

Integrasjonsplattformer kobler Sursa til hundrevis av andre verktøy uten kode. De trenger ikke en egen Sursa-app: De generelle stegene deres for HTTP-forespørsler og webhooks fungerer direkte med API-et. Denne veiledningen dekker de tre vanligste oppskriftene:

Uansett hvilken plattform du bruker, bør du lagre nøkkelen i plattformens lager for påloggingsinformasjon eller tilkoblinger, ikke i selve steget, slik at den ikke kopieres inn i hvert scenario og hver kjøringslogg.

Send poster som kort

Opprett en egendefinert kilde i Sursa (Sources → New source → Custom source: kilder, ny kilde, egendefinert kilde) og deretter en nøkkel for den på kildens side under API keys. Nøkkelen begynner med kbsrc_ og kan bare skrive dokumenter til denne kilden, og derfor er den den riktige nøkkelen å lagre på en tredjepartsplattform.

Det vanlige oppsettet er «når en post opprettes eller oppdateres i X, send den til Sursa»:

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

• Koble en stabil ID for posten til external_id, aldri et tidspunkt eller et kjøringsnummer. Når du sender den samme posten på nytt, oppdateres da det samme kortet, og et steg som prøves på nytt, gjør ingen skade: Svaret er unchanged.
• For en utløser av typen «post slettet» legger du til en ny arbeidsflyt med metoden DELETE og URL-en https://api.example.com/v1/push/sources/42/documents/{{record_id}}.
• Test tilkoblingen med GET https://api.example.com/v1/push/sources/42 og den samme Authorization-headeren. Den returnerer navnet på kilden og antallet dokumenter i den.

Dokumentfeltene er de samme som for kode.

Zapier

Bruk Webhooks by Zapier → Custom Request:

• Method: POST.
• URL: https://api.example.com/v1/push/sources/42/documents.
• Data Pass-Through: av. Data: JSON-en ovenfor, med felt satt inn fra utløseren.
• Headers: Authorization = Bearer kbsrc_…, Content-Type = application/json.

Make

Bruk modulen HTTP → Make a request:

• Method POST, URL som ovenfor, Headers Authorization: Bearer kbsrc_….
• Body type Raw, Content type JSON (application/json), Request content: JSON-en ovenfor med koblede verdier.
• Slå på Parse response for å bruke result (created, updated, unchanged) i senere moduler.
• For å sende en fil velger du Body type Multipart/form-data med et file-felt (filen fra en tidligere modul) og et tekstfelt document som inneholder JSON-feltene uten content.

n8n

Bruk noden HTTP Request:

• Method POST, URL som ovenfor.
• Authentication Generic Credential Type → Header Auth, med navnet Authorization og verdien Bearer kbsrc_….
• Send Body på, Body Content Type JSON, felt koblet med uttrykk som {{ $json.id }}.

For en planlagt full eksport kjeder du sammen tre HTTP Request-noder: Åpne en synkronisering (POST …/syncs med {"type": "initial"} første gang og {"type": "incremental"} senere), send elementene, og lukk synkroniseringen med {"status": "complete"}. n8n kjører en node én gang per element; for å sende færre forespørsler grupperer du elementene med en Aggregate-node og sender dem til …/documents/batch som {"sync_number": …, "documents": [...]}.

Still et spørsmål i en arbeidsflyt

En arbeidsflyt kan spørre Sursa og bruke svaret: skrive et utkast til svar på en supportsak, berike en post i CRM-systemet, legge ut et svar i en chattekanal. Bruk en API-nøkkel for organisasjonen med scopet ask og en rolle som ser de riktige samlingene.

HTTP-svaret har assistentens svar i answer (Markdown) og kildene i sources, hver med doc_name. Når kunnskapsbasen ikke har noe om spørsmålet, er empty satt (for eksempel no_hits): Legg til et filtersteg, slik at arbeidsflyten ikke legger ut et tomt svar. Se Bygg en bot for spørsmål og svar.

Svar kan ta flere sekunder. Hvis HTTP-steget på plattformen har et kort standard tidsavbrudd, øker du det til minst 60 sekunder.

Start en arbeidsflyt fra en hendelse i Sursa

Alle plattformene kan motta webhooks:

1. Opprett utløseren, og kopier HTTPS-adressen du får.
2. Registrer en webhook i Sursa med denne adressen og hendelsene du vil ha, under Administration → Integrations → Webhooks and API (administrasjon, integrasjoner, webhooks og API) eller med POST /v1/webhooks.
3. Send en testhendelse fra webhookens side, og koble feltene i hendelsen (type, data.card.title, …) i de neste stegene.

Valider signaturen. Utløseradressen er offentlig: Alle som får vite den, kan sende forespørsler til den. Valider signaturen på hver leveranse før du handler på den, særlig hvis arbeidsflyten endrer data:

• I n8n legger du til en Code-node etter Webhook-noden med Node.js-valideringen fra Motta webhooks, og slår på alternativet for rå brødtekst i Webhook-noden, slik at de nøyaktige bytene er tilgjengelige.
• I Zapier og Make, der den rå brødteksten er vanskeligere å komme til, bør du i det minste holde adressen hemmelig, filtrere på type og lese objektet på nytt fra API-et før du handler på det.

Nye forsøk og duplikater gjelder for plattformer som for alle andre mottakere: Filtrer på hendelsens id hvis en duplisert kjøring ville gjøre skade.

Tips

• Ved 429 lar du plattformens automatiske nye forsøk vente i så mange sekunder som Retry-After angir. Foretrekk batcher for store eksporter.
• Plattformene logger alle forespørsler og svar. Legg aldri en nøkkel i en URL, og foretrekk kbsrc_-nøkkelen når arbeidsflyten ikke gjør annet enn å skrive dokumenter.
• Hvis et steg mislykkes med 401 sources.push_key_invalid, kontrollerer du at kildens ID i URL-en stemmer med nøkkelen.