Zapier, Make og n8n

Integrationsplatforme forbinder Sursa med hundredvis af andre værktøjer uden kode. De behøver ikke en særlig Sursa-app: Deres generiske trin til HTTP-anmodninger og webhooks virker direkte med API’et. Denne vejledning dækker de tre mest almindelige opskrifter:

Uanset hvilken platform du bruger, så gem nøglen i platformens lager til legitimationsoplysninger eller forbindelser, ikke i selve trinnet, så den ikke kopieres ind i hvert scenarie og hver kørselslog.

Send poster som kort

Opret en brugerdefineret kilde i Sursa (Sources → New source → Custom source), og opret derefter en nøgle til den på kildens side under API keys. Nøglen begynder med kbsrc_ og kan kun skrive dokumenter i denne kilde, og derfor er den den rigtige nøgle at gemme på en tredjepartsplatform.

Den almindelige opsætning er »når en post oprettes eller opdateres i X, så 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}}"
}

• Knyt et stabilt id for posten til external_id, aldrig et tidspunkt eller et kørselsnummer. Så opdaterer en ny afsendelse af den samme post det samme kort, og et trin, der forsøges igen, gør ingen skade: Svaret er unchanged.
• Til en udløser af typen »post slettet« tilføjer du et andet workflow med metoden DELETE og URL’en https://api.example.com/v1/push/sources/42/documents/{{record_id}}.
• Test forbindelsen med GET https://api.example.com/v1/push/sources/42 og den samme Authorization-header. Den returnerer kildens navn og antallet af dokumenter i den.

Dokumentets felter er de samme som i kode.

Zapier

Brug Webhooks by Zapier → Custom Request:

• Method: POST.
• URL: https://api.example.com/v1/push/sources/42/documents.
• Data Pass-Through: slået fra. Data: JSON’en ovenfor med felter indsat fra udløseren.
• Headers: Authorization = Bearer kbsrc_…, Content-Type = application/json.

Make

Brug modulet 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 værdier fra tidligere moduler.
• Slå Parse response til for at bruge result (created, updated, unchanged) i senere moduler.
• Vil du sende en fil, så vælg Body type Multipart/form-data med et file-felt (filen fra et tidligere modul) og et tekstfelt document, der indeholder JSON-felterne uden content.

n8n

Brug noden HTTP Request:

• Method POST, URL som ovenfor.
• Authentication Generic Credential Type → Header Auth med navnet Authorization og værdien Bearer kbsrc_….
• Send Body slået til, Body Content Type JSON, felter knyttet til med udtryk som {{ $json.id }}.

Til en planlagt fuld eksport kæder du tre HTTP Request-noder sammen: Åbn en synkronisering (POST …/syncs med {"type": "initial"} første gang og {"type": "incremental"} derefter), send elementerne, og luk synkroniseringen med {"status": "complete"}. n8n kører en node én gang pr. element; vil du sende færre anmodninger, så saml elementerne med en Aggregate-node, og send dem til …/documents/batch som {"sync_number": …, "documents": [...]}.

Stil et spørgsmål i et workflow

Et workflow kan spørge Sursa og bruge svaret: skrive et udkast til et svar på en supportsag, berige en post i dit CRM, sende et svar i en chatkanal. Brug en API-nøgle for organisationen med scopet ask og en rolle, der ser de rigtige samlinger.

Svaret har selve svarteksten i answer (Markdown) og dens kilder i sources, hver med doc_name. Når vidensbasen ikke har noget om spørgsmålet, er empty sat (fx no_hits): Tilføj et filtertrin, så workflowet ikke sender et tomt svar. Se Byg en Q&A-bot.

Svar kan tage flere sekunder. Har platformens HTTP-trin en kort standard-timeout, så hæv den til mindst 60 sekunder.

Start et workflow ud fra en hændelse i Sursa

Alle tre platforme kan modtage webhooks:

1. Opret udløseren, og kopiér den HTTPS-adresse, den giver dig.
2. Registrér en webhook i Sursa med den adresse og de hændelser, du vil have, under Administration → Integrations → Webhooks and API eller med POST /v1/webhooks.
3. Send en testhændelse fra webhookens side, og knyt hændelsens felter (type, data.card.title, …) til de næste trin.

Validér signaturen. Udløserens adresse er offentlig: Alle, der kender den, kan sende anmodninger til den. Validér signaturen på hver levering, før du handler på den, især hvis workflowet ændrer data:

• I n8n tilføjer du en Code-node efter Webhook-noden med signaturvalideringen til Node.js fra Modtag webhooks og slår Webhook-nodens indstilling for rå brødtekst til, så de nøjagtige bytes er tilgængelige.
• I Zapier og Make, hvor den rå brødtekst er sværere at få fat i, skal du i det mindste holde adressen hemmelig, filtrere på type og læse objektet igen fra API’et, før du handler på det.

Nye forsøg og dubletter gælder for platforme som for enhver anden modtager: Filtrér på hændelsens id, hvis en dobbelt kørsel ville gøre skade.

Tips

• Ved 429 lader du platformens automatiske nye forsøg vente det antal sekunder, der står i Retry-After. Foretræk batches til store eksporter.
• Platforme logger alle anmodninger og svar. Sæt aldrig en nøgle i en URL, og foretræk kbsrc_-nøglen, hvor workflowet ikke gør andet end at skrive dokumenter.
• Mislykkes et trin med 401 sources.push_key_invalid, så kontrollér, at kildens id i URL’en passer til nøglen.