Zapier, Make och n8n

Integrationsplattformar kopplar Sursa till hundratals andra verktyg utan kod. De behöver ingen särskild Sursa-app: deras allmänna steg för HTTP-anrop och webhookar fungerar direkt med API:et. Den här guiden tar upp de tre vanligaste recepten:

Oavsett vilken plattform du använder förvarar du nyckeln bland plattformens autentiseringsuppgifter eller anslutningar, inte i själva steget, så att den inte kopieras till varje scenario och varje körlogg.

Skicka poster som kort

Skapa en egen källa i Sursa (Sources → New source → Custom source) och sedan en nyckel för den på källans sida under API keys. Nyckeln börjar med kbsrc_ och kan bara skriva dokument till den här källan, vilket gör den till rätt nyckel att förvara på en extern plattform.

Den vanliga konfigurationen är ”när en post skapas eller uppdateras i X, skicka den till 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}}"
}

• Mappa ett stabilt id för posten till external_id, aldrig en tid eller ett körningsnummer. Då uppdaterar samma post samma kort när den skickas igen, och ett steg som körs om gör ingen skada: svaret är unchanged.
• För en utlösare av typen ”post borttagen” lägger du till ett andra arbetsflöde med metoden DELETE och URL:en https://api.example.com/v1/push/sources/42/documents/{{record_id}}.
• Testa anslutningen med GET https://api.example.com/v1/push/sources/42 och samma huvud Authorization. Det returnerar källans namn och antalet dokument i den.

Dokumentets fält är desamma som för kod.

Zapier

Använd Webhooks by Zapier → Custom Request:

• Method: POST.
• URL: https://api.example.com/v1/push/sources/42/documents.
• Data Pass-Through: av. Data: JSON-koden ovan, med fält som infogas från utlösaren.
• Headers: Authorization = Bearer kbsrc_…, Content-Type = application/json.

Make

Använd modulen HTTP → Make a request:

• Method POST, URL som ovan, Headers Authorization: Bearer kbsrc_….
• Body type Raw, Content type JSON (application/json), Request content: JSON-koden ovan med mappade värden.
• Slå på Parse response för att använda result (created, updated, unchanged) i senare moduler.
• För att skicka en fil väljer du Body type Multipart/form-data med ett fält file (filen från en tidigare modul) och ett textfält document som innehåller JSON-fälten utan content.

n8n

Använd noden HTTP Request:

• Method POST, URL som ovan.
• Authentication Generic Credential Type → Header Auth, med namnet Authorization och värdet Bearer kbsrc_….
• Send Body på, Body Content Type JSON, fält som mappas med uttryck som {{ $json.id }}.

För en schemalagd fullständig export kedjar du tre noder av typen HTTP Request: öppna en synkning (POST …/syncs med {"type": "initial"} första gången, {"type": "incremental"} därefter), skicka elementen och stäng synkningen med {"status": "complete"}. n8n kör en nod en gång per element; för att skicka färre anrop grupperar du elementen med en nod av typen Aggregate och skickar dem till …/documents/batch som {"sync_number": …, "documents": [...]}.

Ställ en fråga i ett arbetsflöde

Ett arbetsflöde kan fråga Sursa och använda svaret: skissa ett svar på ett supportärende, berika en post i CRM:et, publicera ett svar i en chattkanal. Använd en API-nyckel för organisationen med omfånget ask och en roll som ser rätt samlingar.

Svaret har svarstexten i answer (Markdown) och dess källor i sources, var och en med doc_name. När kunskapsbasen inte har något om frågan är empty satt (till exempel no_hits): lägg till ett filtersteg så att arbetsflödet inte publicerar ett tomt svar. Se Bygg en fråga-svar-bot.

Svar kan ta flera sekunder. Om plattformens HTTP-steg har en kort tidsgräns som standard höjer du den till minst 60 sekunder.

Starta ett arbetsflöde från en händelse i Sursa

Alla plattformar kan ta emot webhookar:

1. Skapa utlösaren och kopiera HTTPS-adressen som den ger dig.
2. Registrera i Sursa en webhook med den adressen och de händelser som du vill ha, under Administration → Integrations → Webhooks and API eller med POST /v1/webhooks.
3. Skicka en testhändelse från webhookens sida och mappa händelsens fält (type, data.card.title, …) i nästa steg.

Kontrollera signaturen. Utlösarens adress är offentlig: alla som får reda på den kan skicka anrop till den. Verifiera signaturen för varje leverans innan du agerar på den, särskilt om arbetsflödet ändrar data:

• I n8n lägger du till en nod av typen Code efter Webhook-noden med verifieraren för Node.js från Ta emot webhookar, och aktiverar Webhook-nodens alternativ för rå brödtext så att de exakta byten finns tillgängliga.
• I Zapier och Make, där den råa brödtexten är svårare att komma åt, håller du åtminstone adressen hemlig, filtrerar på type och läser objektet igen från API:et innan du agerar på det.

Nya försök och dubbletter gäller plattformar precis som alla andra mottagare: filtrera på händelsens id om en dubbel körning skulle göra skada.

Tips

• Vid 429 låter du plattformens automatiska nya försök vänta i Retry-After sekunder. Använd hellre batchar för stora exporter.
• Plattformar loggar varje anrop och svar. Lägg aldrig en nyckel i en URL, och använd hellre kbsrc_-nyckeln när arbetsflödet bara skriver dokument.
• Om ett steg misslyckas med 401 sources.push_key_invalid kontrollerar du att källans id i URL:en stämmer med nyckeln.