Zapier, Make i n8n

Les plataformes d’integració connecten Sursa amb centenars d’altres eines sense codi. No necessiten cap aplicació de Sursa dedicada: els seus passos genèrics de sol·licitud HTTP i de webhook funcionen directament amb l’API. Aquesta guia tracta les tres receptes més habituals:

Sigui quina sigui la plataforma, deseu la clau al seu magatzem de credencials o de connexions, no al pas mateix, perquè no es copiï a cada escenari ni a cada registre d’execució.

Enviar elements com a entrades

Creeu una font personalitzada a Sursa a Sources → New source → Custom source (fonts, font nova, font personalitzada) i, després, una clau per a aquesta font a la pàgina de la font, a API keys (claus d’API de la font). La clau comença per kbsrc_ i només pot escriure documents en aquesta font, cosa que la converteix en la clau adequada per desar en una plataforma de tercers.

La configuració habitual és «quan es crea o s’actualitza un element a X, envia’l 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}}"
}

• Assigneu a external_id un ID estable de l’element, mai una hora ni un número d’execució. Així, si torneu a enviar el mateix element, s’actualitza la mateixa entrada, i un pas reintentat no fa cap mal: la resposta és unchanged.
• Per a un activador d’«element eliminat», afegiu un segon flux de treball amb el mètode DELETE i la URL https://api.example.com/v1/push/sources/42/documents/{{record_id}}.
• Proveu la connexió amb GET https://api.example.com/v1/push/sources/42 i la mateixa capçalera Authorization. Retorna el nom de la font i el seu nombre de documents.

Els camps del document són els mateixos que amb codi.

Zapier

Feu servir Webhooks by Zapier → Custom Request:

• Method: POST.
• URL: https://api.example.com/v1/push/sources/42/documents.
• Data Pass-Through: desactivat. Data: el JSON anterior, amb els camps inserits des de l’activador.
• Headers: Authorization = Bearer kbsrc_…, Content-Type = application/json.

Make

Feu servir el mòdul HTTP → Make a request:

• Method POST, URL com abans, Headers Authorization: Bearer kbsrc_….
• Body type Raw, Content type JSON (application/json), Request content: el JSON anterior amb els valors assignats.
• Activeu Parse response per fer servir result (created, updated, unchanged) als mòduls posteriors.
• Per enviar un fitxer, trieu Body type Multipart/form-data amb un camp file (el fitxer d’un mòdul anterior) i un camp de text document que contingui els camps JSON sense content.

n8n

Feu servir el node HTTP Request:

• Method POST, URL com abans.
• Authentication Generic Credential Type → Header Auth, amb el nom Authorization i el valor Bearer kbsrc_….
• Send Body activat, Body Content Type JSON, amb els camps assignats amb expressions com ara {{ $json.id }}.

Per a una exportació completa programada, encadeneu tres nodes HTTP Request: obriu una sincronització (POST …/syncs amb {"type": "initial"} la primera vegada i {"type": "incremental"} després), envieu els elements i tanqueu la sincronització amb {"status": "complete"}. n8n executa un node una vegada per element; per enviar menys sol·licituds, agrupeu els elements amb un node Aggregate i envieu-los a …/documents/batch com a {"sync_number": …, "documents": [...]}.

Fer una pregunta en un flux de treball

Un flux de treball pot fer una pregunta a Sursa i fer servir la resposta: redactar una resposta a un tiquet d’assistència, enriquir un element del CRM, publicar una resposta en un canal de xat. Feu servir una clau d’API de l’organització amb l’àmbit ask i un rol que vegi les col·leccions adequades.

La resposta té el text de la resposta a answer (Markdown) i les seves fonts a sources, cadascuna amb doc_name. Quan la base de coneixement no té res sobre la pregunta, empty té valor (per exemple, no_hits): afegiu un pas de filtre perquè el flux de treball no publiqui una resposta buida. Vegeu Crear un bot de preguntes i respostes.

Les respostes poden trigar uns quants segons. Si el pas HTTP de la plataforma té un temps d’espera per defecte curt, augmenteu-lo a 60 segons com a mínim.

Iniciar un flux de treball a partir d’un esdeveniment de Sursa

Totes les plataformes poden rebre webhooks:

1. Creeu l’activador i copieu l’adreça HTTPS que us dona.
2. A Sursa, registreu un webhook amb aquesta adreça i els esdeveniments que vulgueu, a Administration → Integrations → Webhooks and API (administració, integracions, webhooks) o amb POST /v1/webhooks.
3. Envieu un esdeveniment de prova des de la pàgina del webhook i assigneu els camps de l’esdeveniment (type, data.card.title, …) als passos següents.

Comproveu la signatura. L’adreça de l’activador és pública: qualsevol que la conegui hi pot enviar sol·licituds. Verifiqueu la signatura de cada lliurament abans d’actuar-hi, sobretot si el flux de treball canvia dades:

• A n8n, afegiu un node Code després del node Webhook amb la verificació de signatures en Node.js de Rebre webhooks, i activeu l’opció de cos en brut del node Webhook perquè els bytes exactes estiguin disponibles.
• A Zapier i a Make, on és més difícil accedir al cos en brut, com a mínim mantingueu l’adreça en secret, filtreu per type i torneu a llegir l’objecte a l’API abans d’actuar-hi.

Els reintents i els duplicats s’apliquen a les plataformes com a qualsevol altre receptor: filtreu per l’id de l’esdeveniment si una execució duplicada pogués causar problemes.

Consells

• Amb un 429, deixeu que el reintent automàtic de la plataforma esperi els segons de Retry-After. Feu servir preferentment lots per a les exportacions grans.
• Les plataformes registren cada sol·licitud i cada resposta. No poseu mai una clau en una URL, i feu servir preferentment la clau kbsrc_ sempre que el flux de treball només escrigui documents.
• Si un pas falla amb 401 sources.push_key_invalid, comproveu que l’ID de la font de la URL correspon a la clau.