Zapier, Make en n8n

Integratieplatforms koppelen Sursa zonder code aan honderden andere tools. Ze hebben geen aparte app voor Sursa nodig: hun algemene stappen voor HTTP-requests en webhooks werken rechtstreeks met de API. Deze handleiding behandelt de drie meest gebruikte recepten:

Welk platform je ook gebruikt, bewaar de sleutel in de opslag voor authenticatiegegevens of verbindingen van het platform, niet in de stap zelf, zodat hij niet in elk scenario en elk runlog wordt gekopieerd.

Records als kaarten versturen

Maak in Sursa een eigen bron (Sources → New source → Custom source, bronnen → nieuwe bron → eigen bron) en maak er daarna op de pagina van de bron onder API keys een sleutel voor. De sleutel begint met kbsrc_ en kan alleen documenten naar deze bron schrijven. Daardoor is het de juiste sleutel om op een platform van derden te bewaren.

De gebruikelijke opzet is “wanneer er in X een record wordt gemaakt of bijgewerkt, stuur het naar 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}}"
}

• Koppel een stabiele ID van het record aan external_id, nooit een tijdstip of een runnummer. Hetzelfde record opnieuw versturen werkt dan dezelfde kaart bij, en een stap die opnieuw wordt geprobeerd, kan geen kwaad: het antwoord is unchanged.
• Voeg voor een trigger “record verwijderd” een tweede workflow toe met de methode DELETE en de URL https://api.example.com/v1/push/sources/42/documents/{{record_id}}.
• Test de verbinding met GET https://api.example.com/v1/push/sources/42 en dezelfde header Authorization. Dat geeft de naam van de bron en het aantal documenten terug.

De velden van een document zijn dezelfde als in code.

Zapier

Gebruik Webhooks by Zapier → Custom Request:

• Method: POST.
• URL: https://api.example.com/v1/push/sources/42/documents.
• Data Pass-Through: uit. Data: de JSON hierboven, met velden die uit de trigger zijn ingevoegd.
• Headers: Authorization = Bearer kbsrc_…, Content-Type = application/json.

Make

Gebruik de module HTTP → Make a request:

• Method POST, URL zoals hierboven, Headers Authorization: Bearer kbsrc_….
• Body type Raw, Content type JSON (application/json), Request content: de JSON hierboven met gekoppelde waarden.
• Zet Parse response aan om result (created, updated, unchanged) in latere modules te gebruiken.
• Om een bestand te versturen, kies je Body type Multipart/form-data met een veld file (het bestand uit een eerdere module) en een tekstveld document met de JSON-velden zonder content.

n8n

Gebruik de node HTTP Request:

• Method POST, URL zoals hierboven.
• Authentication Generic Credential Type → Header Auth, met de naam Authorization en de waarde Bearer kbsrc_….
• Send Body aan, Body Content Type JSON, velden gekoppeld met expressies zoals {{ $json.id }}.

Voor een geplande volledige export schakel je drie HTTP Request-nodes achter elkaar: open een synchronisatie (POST …/syncs met de eerste keer {"type": "initial"} en daarna {"type": "incremental"}), verstuur de items en sluit de synchronisatie met {"status": "complete"}. n8n voert een node één keer per item uit; om minder requests te versturen, groepeer je de items met een node Aggregate en stuur je ze naar …/documents/batch als {"sync_number": …, "documents": [...]}.

Een vraag stellen in een workflow

Een workflow kan Sursa een vraag stellen en het antwoord gebruiken: een antwoord op een supportticket opstellen, een record in de CRM verrijken, een antwoord in een chatkanaal plaatsen. Gebruik een API-sleutel van de organisatie met de scope ask en een rol die de juiste collecties ziet.

De response bevat het antwoord in answer (Markdown) en de bronnen ervan in sources, elk met doc_name. Heeft de kennisbank niets over de vraag, dan is empty ingesteld (bijvoorbeeld no_hits): voeg een filterstap toe zodat de workflow geen leeg antwoord plaatst. Zie Een vraag-en-antwoordbot bouwen.

Antwoorden kunnen enkele seconden duren. Heeft de HTTP-stap van het platform standaard een korte time-out, verhoog die dan tot minstens 60 seconden.

Een workflow starten vanuit een event van Sursa

Elk platform kan webhooks ontvangen:

1. Maak de trigger en kopieer het HTTPS-adres dat je krijgt.
2. Registreer in Sursa een webhook met dat adres en de events die je wilt, onder Administration → Integrations → Webhooks and API (beheer → integraties → webhooks en API) of met POST /v1/webhooks.
3. Verstuur een testevent vanaf de pagina van de webhook en koppel in de volgende stappen de velden van het event (type, data.card.title, …).

Controleer de handtekening. Het adres van de trigger is openbaar: iedereen die het te weten komt, kan er requests naartoe sturen. Controleer de handtekening van elke levering voordat je erop reageert, vooral als de workflow gegevens wijzigt:

• Voeg in n8n na de Webhook-node een node Code toe met de controle voor Node.js uit Webhooks ontvangen, en zet de optie voor de ruwe body van de Webhook-node aan, zodat de exacte bytes beschikbaar zijn.
• In Zapier en Make, waar de ruwe body moeilijker bereikbaar is, houd je het adres in elk geval geheim, filter je op type en lees je het object opnieuw via de API voordat je erop reageert.

Nieuwe pogingen en duplicaten gelden voor platforms net als voor elke ontvanger: filter op de id van het event als een dubbele run schade kan doen.

Tips

• Laat bij 429 de automatische nieuwe poging van het platform het aantal seconden uit Retry-After afwachten. Gebruik bij grote exports bij voorkeur batches.
• Platforms loggen elk request en elke response. Zet nooit een sleutel in een URL, en gebruik bij voorkeur de kbsrc_-sleutel als de workflow alleen documenten schrijft.
• Mislukt een stap met 401 sources.push_key_invalid, controleer dan of de ID van de bron in de URL bij de sleutel hoort.