Zapier, Make y n8n

Las plataformas de integración conectan Sursa con cientos de herramientas más sin escribir código. No necesitan una aplicación específica de Sursa: sus pasos genéricos de solicitud HTTP y de webhook funcionan directamente con la API. Esta guía trata las tres recetas más habituales:

Use la plataforma que use, guarde la clave en su almacén de credenciales o de conexiones, no en el propio paso, para que no se copie en cada escenario ni en cada registro de ejecución.

Enviar registros como tarjetas

Cree una fuente personalizada en Sursa (Sources → New source → Custom source: fuentes, fuente nueva, fuente personalizada) y, después, una clave para ella en la página de la fuente, en API keys (claves de API de la fuente). La clave empieza por kbsrc_ y solo puede escribir documentos en esta fuente, lo que la convierte en la clave adecuada para guardar en una plataforma de terceros.

La configuración habitual es «cuando se cree o se actualice un registro en X, enviarlo 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}}"
}

• Asigne a external_id un ID estable del registro, nunca una hora ni un número de ejecución. Así, al volver a enviar el mismo registro se actualiza la misma tarjeta, y un paso reintentado no causa ningún problema: la respuesta es unchanged.
• Para un disparador de «registro eliminado», añada un segundo flujo de trabajo con el método DELETE y la URL https://api.example.com/v1/push/sources/42/documents/{{record_id}}.
• Pruebe la conexión con GET https://api.example.com/v1/push/sources/42 y el mismo encabezado Authorization. Devuelve el nombre de la fuente y su número de documentos.

Los campos del documento son los mismos que en el código.

Zapier

Elija el paso Webhooks by Zapier → Custom Request:

• Method: POST.
• URL: https://api.example.com/v1/push/sources/42/documents.
• Data Pass-Through: desactivado. Data: el JSON anterior, con los campos insertados a partir del disparador.
• Headers: Authorization = Bearer kbsrc_…, Content-Type = application/json.

Make

Use el módulo HTTP → Make a request:

• Method POST, URL como arriba, Headers Authorization: Bearer kbsrc_….
• Body type Raw, Content type JSON (application/json), Request content: el JSON anterior con los valores asignados.
• Active Parse response para usar result (created, updated, unchanged) en los módulos posteriores.
• Para enviar un archivo, elija Body type Multipart/form-data con un campo file (el archivo de un módulo anterior) y un campo de texto document que contenga los campos JSON sin content.

n8n

Use el nodo HTTP Request:

• Method POST, URL como arriba.
• Authentication Generic Credential Type → Header Auth, con el nombre Authorization y el valor Bearer kbsrc_….
• Send Body activado, Body Content Type JSON, con los campos asignados mediante expresiones como {{ $json.id }}.

Para una exportación completa programada, encadene tres nodos HTTP Request: abra una sincronización (POST …/syncs con {"type": "initial"} la primera vez y {"type": "incremental"} después), envíe los elementos y cierre la sincronización con {"status": "complete"}. n8n ejecuta un nodo una vez por elemento; para enviar menos solicitudes, agrupe los elementos con un nodo Aggregate y envíelos a …/documents/batch como {"sync_number": …, "documents": [...]}.

Hacer una pregunta en un flujo de trabajo

Un flujo de trabajo puede preguntar a Sursa y usar la respuesta: redactar un borrador de respuesta a un ticket de soporte, enriquecer un registro del CRM, publicar una respuesta en un canal de chat. Use una clave de API de la organización con el ámbito ask y un rol que vea las colecciones adecuadas.

La respuesta incluye la respuesta del asistente en answer (Markdown) y sus fuentes en sources, cada una con doc_name. Cuando la base de conocimiento no tiene nada sobre la pregunta, empty tiene valor (por ejemplo, no_hits): añada un paso de filtro para que el flujo de trabajo no publique una respuesta vacía. Consulte Crear un bot de preguntas y respuestas.

Las respuestas pueden tardar varios segundos. Si el paso HTTP de la plataforma tiene un tiempo de espera predeterminado corto, auméntelo al menos a 60 segundos.

Iniciar un flujo de trabajo a partir de un evento de Sursa

Todas las plataformas pueden recibir webhooks:

1. Cree el disparador y copie la dirección HTTPS que le da.
2. En Sursa, registre un webhook con esa dirección y los eventos que quiera, en Administration → Integrations → Webhooks and API (administración, integraciones, webhooks) o con POST /v1/webhooks.
3. Envíe un evento de prueba desde la página del webhook y asigne los campos del evento (type, data.card.title, …) en los pasos siguientes.

Compruebe la firma. La dirección del disparador es pública: cualquiera que la conozca puede enviarle solicitudes. Compruebe la firma de cada entrega antes de actuar, sobre todo si el flujo de trabajo cambia datos:

• En n8n, añada un nodo Code después del nodo Webhook con la verificación de firmas para Node.js de Recibir webhooks, y active la opción de cuerpo sin procesar del nodo Webhook para que estén disponibles los bytes exactos.
• En Zapier y Make, donde es más difícil acceder al cuerpo sin procesar, al menos mantenga en secreto la dirección, filtre por type y vuelva a leer el objeto desde la API antes de actuar.

Los reintentos y los duplicados se aplican a las plataformas como a cualquier receptor: filtre por el id del evento si una ejecución duplicada pudiera causar daños.

Consejos

• Ante un 429, deje que el reintento automático de la plataforma espere los segundos de Retry-After. Para las exportaciones grandes, prefiera los lotes.
• Las plataformas registran cada solicitud y cada respuesta. Nunca ponga una clave en una URL, y prefiera la clave kbsrc_ siempre que el flujo de trabajo solo escriba documentos.
• Si un paso falla con 401 sources.push_key_invalid, compruebe que el ID de la fuente de la URL corresponde a la clave.