Zapier, Make et n8n

Les plateformes d’intégration connectent Sursa à des centaines d’autres outils sans code. Elles n’ont pas besoin d’une application Sursa dédiée : leurs étapes génériques de requête HTTP et de webhook fonctionnent directement avec l’API. Ce guide présente les trois recettes les plus courantes :

Quelle que soit la plateforme, conservez la clé dans son coffre d’identifiants ou de connexions, et non dans l’étape elle-même, pour qu’elle ne soit pas copiée dans chaque scénario et chaque journal d’exécution.

Envoyer des enregistrements sous forme de fiches

Créez une source personnalisée dans Sursa (Sources → New source → Custom source), puis une clé pour elle sur la page de la source, sous API keys. La clé commence par kbsrc_ et ne peut qu’écrire des documents dans cette source : c’est donc la bonne clé à conserver sur une plateforme tierce.

La configuration courante est « quand un enregistrement est créé ou modifié dans X, l’envoyer à 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}}"
}

• Associez à external_id un identifiant stable de l’enregistrement, jamais une heure ni un numéro d’exécution. Renvoyer le même enregistrement met alors à jour la même fiche, et une étape relancée est sans conséquence : la réponse est unchanged.
• Pour un déclencheur « enregistrement supprimé », ajoutez un second workflow avec la méthode DELETE et l’URL https://api.example.com/v1/push/sources/42/documents/{{record_id}}.
• Testez la connexion avec GET https://api.example.com/v1/push/sources/42 et le même en-tête Authorization. La réponse indique le nom de la source et son nombre de documents.

Les champs du document sont les mêmes que dans le code.

Zapier

Utilisez Webhooks by Zapier → Custom Request :

• Method: POST.
• URL: https://api.example.com/v1/push/sources/42/documents.
• Data Pass-Through: désactivé. Data: le JSON ci-dessus, avec les champs insérés depuis le déclencheur.
• Headers: Authorization = Bearer kbsrc_…, Content-Type = application/json.

Make

Utilisez le module HTTP → Make a request :

• Method POST, URL comme ci-dessus, Headers Authorization: Bearer kbsrc_….
• Body type Raw, Content type JSON (application/json), Request content : le JSON ci-dessus avec les valeurs associées.
• Activez Parse response pour utiliser result (created, updated, unchanged) dans les modules suivants.
• Pour envoyer un fichier, choisissez Body type Multipart/form-data avec un champ file (le fichier d’un module précédent) et un champ texte document qui contient les champs JSON sans content.

n8n

Utilisez le node HTTP Request :

• Method POST, URL comme ci-dessus.
• Authentication Generic Credential Type → Header Auth, avec le nom Authorization et la valeur Bearer kbsrc_….
• Send Body activé, Body Content Type JSON, champs associés avec des expressions comme {{ $json.id }}.

Pour un export complet planifié, enchaînez trois nodes HTTP Request : ouvrez une synchronisation (POST …/syncs avec {"type": "initial"} la première fois, {"type": "incremental"} ensuite), envoyez les éléments, puis fermez la synchronisation avec {"status": "complete"}. n8n exécute un node une fois par élément ; pour envoyer moins de requêtes, regroupez les éléments avec un node Aggregate et envoyez-les à …/documents/batch sous la forme {"sync_number": …, "documents": [...]}.

Poser une question dans un workflow

Un workflow peut interroger Sursa et utiliser la réponse : rédiger un brouillon de réponse à un ticket de support, enrichir un enregistrement du CRM, publier une réponse dans un canal de discussion. Utilisez une clé API de l’organisation dotée de la portée ask et d’un rôle qui voit les bonnes collections.

La réponse contient la réponse dans answer (en Markdown) et ses sources dans sources, chacune avec doc_name. Quand la base de connaissances ne contient rien sur la question, empty est renseigné (par exemple no_hits) : ajoutez une étape de filtre pour que le workflow ne publie pas une réponse vide. Voir Créer un bot de questions-réponses.

Les réponses peuvent prendre plusieurs secondes. Si l’étape HTTP de la plateforme a un délai par défaut court, portez-le à au moins 60 secondes.

Lancer un workflow à partir d’un événement de Sursa

Toutes les plateformes peuvent recevoir des webhooks :

1. Créez le déclencheur et copiez l’adresse HTTPS qu’il vous donne.
2. Dans Sursa, enregistrez un webhook avec cette adresse et les événements voulus, sous Administration → Integrations → Webhooks and API ou avec POST /v1/webhooks.
3. Envoyez un événement de test depuis la page du webhook, puis associez les champs de l’événement (type, data.card.title, …) dans les étapes suivantes.

Vérifiez la signature. L’adresse du déclencheur est publique : toute personne qui la découvre peut y envoyer des requêtes. Vérifiez la signature de chaque livraison avant d’agir, surtout si le workflow modifie des données :

• Dans n8n, ajoutez un node Code après le node Webhook avec la vérification en Node.js de Recevoir des webhooks, et activez l’option de corps brut du node Webhook pour disposer des octets exacts.
• Dans Zapier et Make, où le corps brut est plus difficile à obtenir, gardez au moins l’adresse secrète, filtrez sur type et relisez l’objet par l’API avant d’agir.

Les nouvelles tentatives et les doublons concernent les plateformes comme tout autre récepteur : filtrez sur l'id de l’événement si une exécution en double pose problème.

Conseils

• Sur 429, laissez la relance automatique de la plateforme attendre le nombre de secondes de Retry-After. Préférez les lots pour les exports volumineux.
• Les plateformes journalisent chaque requête et chaque réponse. Ne placez jamais une clé dans une URL, et préférez la clé kbsrc_ partout où le workflow se contente d’écrire des documents.
• Si une étape échoue avec 401 sources.push_key_invalid, vérifiez que l’identifiant de la source dans l’URL correspond à la clé.