Zapier, Make e n8n

Le piattaforme di integrazione collegano Sursa a centinaia di altri strumenti senza codice. Non serve un’app dedicata di Sursa: i loro passaggi generici per richieste HTTP e webhook funzionano direttamente con l’API. Questa guida tratta le tre ricette più comuni:

Qualunque piattaforma usi, conserva la chiave nel suo archivio di credenziali o di connessioni, non nel passaggio stesso, così non viene copiata in ogni scenario e in ogni log di esecuzione.

Inviare record come schede

Crea una fonte personalizzata in Sursa (Sources → New source → Custom source: fonti, nuova fonte, fonte personalizzata), poi una chiave per la fonte nella sua pagina, in API keys (chiavi API della fonte). La chiave inizia con kbsrc_ e può solo scrivere documenti in questa fonte, quindi è la chiave giusta da conservare su una piattaforma di terzi.

La configurazione più comune è “quando un record viene creato o aggiornato in X, invialo a 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 su external_id un ID stabile del record, mai un orario o un numero di esecuzione. Così inviare di nuovo lo stesso record aggiorna la stessa scheda, e un passaggio ritentato non ha conseguenze: la risposta è unchanged.
• Per un trigger “record eliminato”, aggiungi un secondo flusso di lavoro con metodo DELETE e URL https://api.example.com/v1/push/sources/42/documents/{{record_id}}.
• Verifica la connessione con GET https://api.example.com/v1/push/sources/42 e la stessa intestazione Authorization. Restituisce il nome della fonte e il suo numero di documenti.

I campi del documento sono gli stessi che si usano nel codice.

Zapier

Usa Webhooks by Zapier → Custom Request:

• Method: POST.
• URL: https://api.example.com/v1/push/sources/42/documents.
• Data Pass-Through: disattivato. Data: il JSON precedente, con i campi inseriti dal trigger.
• Headers: Authorization = Bearer kbsrc_…, Content-Type = application/json.

Make

Usa il modulo HTTP → Make a request:

• Method POST, URL come sopra, Headers Authorization: Bearer kbsrc_….
• Body type Raw, Content type JSON (application/json), Request content: il JSON precedente con i valori mappati.
• Attiva Parse response per usare result (created, updated, unchanged) nei moduli successivi.
• Per inviare un file, scegli Body type Multipart/form-data con un campo file (il file di un modulo precedente) e un campo di testo document che contiene i campi JSON senza content.

n8n

Usa il nodo HTTP Request:

• Method POST, URL come sopra.
• Authentication Generic Credential Type → Header Auth, con nome Authorization e valore Bearer kbsrc_….
• Send Body attivo, Body Content Type JSON, campi mappati con espressioni come {{ $json.id }}.

Per un’esportazione completa pianificata, concatena tre nodi HTTP Request: apri una sincronizzazione (POST …/syncs con {"type": "initial"} la prima volta, {"type": "incremental"} le volte successive), invia gli elementi e chiudi la sincronizzazione con {"status": "complete"}. n8n esegue un nodo una volta per elemento; per inviare meno richieste, raggruppa gli elementi con un nodo Aggregate e inviali a …/documents/batch come {"sync_number": …, "documents": [...]}.

Fare una domanda in un flusso di lavoro

Un flusso di lavoro può interrogare Sursa e usare la risposta: preparare una bozza di risposta a un ticket di assistenza, arricchire un record del CRM, pubblicare una risposta in un canale di chat. Usa una chiave API dell’organizzazione con l’ambito ask e un ruolo che veda le raccolte giuste.

La risposta contiene il testo in answer (Markdown) e le fonti in sources, ciascuna con doc_name. Quando la knowledge base non ha nulla sulla domanda, empty è impostato (per esempio no_hits): aggiungi un passaggio di filtro perché il flusso di lavoro non pubblichi una risposta vuota. Vedi Creare un bot di domande e risposte.

Le risposte possono richiedere diversi secondi. Se il passaggio HTTP della piattaforma ha un timeout predefinito breve, aumentalo ad almeno 60 secondi.

Avviare un flusso di lavoro da un evento di Sursa

Tutte le piattaforme possono ricevere webhook:

1. Crea il trigger e copia l’indirizzo HTTPS che ti fornisce.
2. In Sursa, registra un webhook con quell’indirizzo e gli eventi che ti interessano, in Administration → Integrations → Webhooks and API (amministrazione, integrazioni, webhook) oppure con POST /v1/webhooks.
3. Invia un evento di test dalla pagina del webhook e mappa i campi dell’evento (type, data.card.title, …) nei passaggi successivi.

Verifica la firma. L’indirizzo del trigger è pubblico: chiunque lo conosca può inviargli richieste. Verifica la firma di ogni consegna prima di basarti su di essa, soprattutto se il flusso di lavoro modifica dati:

• In n8n, aggiungi dopo il nodo Webhook un nodo Code con la verifica delle firme in Node.js di Ricevere i webhook, e attiva l’opzione del corpo grezzo del nodo Webhook così sono disponibili i byte esatti.
• In Zapier e Make, dove è più difficile accedere al corpo grezzo, mantieni almeno segreto l’indirizzo, filtra su type e rileggi l’oggetto dall’API prima di basarti su di esso.

Nuovi tentativi e duplicati valgono per le piattaforme come per qualsiasi ricevitore: filtra sull’id dell’evento se un’esecuzione duplicata potrebbe causare danni.

Suggerimenti

• Con un 429, lascia che il nuovo tentativo automatico della piattaforma attenda i secondi indicati da Retry-After. Per le esportazioni grandi preferisci i batch.
• Le piattaforme registrano ogni richiesta e risposta. Non mettere mai una chiave in un URL e preferisci la chiave kbsrc_ ovunque il flusso di lavoro si limiti a scrivere documenti.
• Se un passaggio non riesce con 401 sources.push_key_invalid, controlla che l’ID della fonte nell’URL corrisponda alla chiave.