Zapier, Make и n8n

Платформы интеграций без кода связывают Sursa с сотнями других сервисов. Отдельное приложение Sursa им не нужно: их универсальные шаги HTTP-запроса и вебхука работают с API напрямую. В этом руководстве — три самых частых рецепта:

Какой бы платформой вы ни пользовались, храните ключ в её хранилище учётных данных или подключений, а не в самом шаге, чтобы он не копировался в каждый сценарий и журнал запусков.

Отправка записей как карточек

Создайте в Sursa свой источник (Источники → Новый источник → Свой источник), затем ключ для него на странице источника в разделе Ключи API. Ключ начинается с kbsrc_ и может только записывать документы в этот источник, поэтому именно его и стоит хранить на сторонней платформе.

Обычная настройка — «когда запись в X создана или изменена, отправить её в 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}}"
}

• Сопоставляйте с external_id постоянный идентификатор записи, а не время и не номер запуска. Тогда повторная отправка той же записи обновит ту же карточку, а повтор шага ничему не повредит: ответ будет unchanged.
• Для триггера «запись удалена» добавьте второй сценарий с методом DELETE и URL https://api.example.com/v1/push/sources/42/documents/{{record_id}}.
• Проверьте подключение запросом GET https://api.example.com/v1/push/sources/42 с тем же заголовком Authorization. Он возвращает имя источника и число документов в нём.

Поля документа те же, что и при работе из кода.

Zapier

Используйте Webhooks by Zapier → Custom Request:

• Method: POST.
• URL: https://api.example.com/v1/push/sources/42/documents.
• Data Pass-Through: выключено. Data: JSON выше с полями, подставленными из триггера.
• Headers: Authorization = Bearer kbsrc_…, Content-Type = application/json.

Make

Используйте модуль HTTP → Make a request:

• Method POST, URL как выше, Headers Authorization: Bearer kbsrc_….
• Body type Raw, Content type JSON (application/json), Request content: JSON выше с сопоставленными значениями.
• Включите Parse response, чтобы использовать result (created, updated, unchanged) в следующих модулях.
• Чтобы отправить файл, выберите Body type Multipart/form-data с полем file (файл из предыдущего модуля) и текстовым полем document, в котором лежат поля JSON без content.

n8n

Используйте узел HTTP Request:

• Method POST, URL как выше.
• Authentication Generic Credential Type → Header Auth с именем Authorization и значением Bearer kbsrc_….
• Send Body включено, Body Content Type JSON, поля сопоставлены выражениями вроде {{ $json.id }}.

Для полной выгрузки по расписанию соедините цепочкой три узла HTTP Request: откройте синхронизацию (POST …/syncs с {"type": "initial"} в первый раз и {"type": "incremental"} в последующие), отправьте элементы и закройте синхронизацию с {"status": "complete"}. n8n запускает узел по одному разу на каждый элемент; чтобы отправлять меньше запросов, сгруппируйте элементы узлом Aggregate и отправьте их в …/documents/batch в виде {"sync_number": …, "documents": [...]}.

Вопрос внутри сценария

Сценарий может спросить Sursa и использовать ответ: подготовить черновик ответа на обращение в поддержку, дополнить запись в CRM, опубликовать ответ в канале чата. Используйте ключ API организации с областью ask и ролью, которая видит нужные коллекции.

В ответе текст ответа лежит в answer (Markdown), а его источники — в sources, у каждого есть doc_name. Если в базе знаний нет ничего по вопросу, задано empty (например, no_hits): добавьте шаг-фильтр, чтобы сценарий не публиковал пустой ответ. См. Бот вопросов и ответов.

Ответ может готовиться несколько секунд. Если у HTTP-шага платформы короткий тайм-аут по умолчанию, увеличьте его хотя бы до 60 секунд.

Запуск сценария по событию Sursa

Каждая платформа умеет принимать вебхуки:

1. Создайте триггер и скопируйте HTTPS-адрес, который он выдаст.
2. Зарегистрируйте в Sursa вебхук с этим адресом и нужными событиями в разделе Администрирование → Интеграции → Вебхуки и API или через POST /v1/webhooks.
3. Отправьте проверочное событие со страницы вебхука и сопоставьте поля события (type, data.card.title, …) в следующих шагах.

Проверяйте подпись. Адрес триггера публичный: любой, кто его узнает, может отправлять на него запросы. Проверяйте подпись каждой доставки, прежде чем на неё реагировать, особенно если сценарий меняет данные:

• В n8n добавьте после узла Webhook узел Code с проверкой на Node.js из руководства Приём вебхуков и включите у узла Webhook параметр сырого тела, чтобы были доступны точные байты.
• В Zapier и Make, где до сырого тела добраться сложнее, хотя бы держите адрес в секрете, фильтруйте по type и перечитывайте объект через API, прежде чем на него реагировать.

Повторы и дубли касаются платформ так же, как любого получателя: если повторный запуск может навредить, фильтруйте по id события.

Советы

• При 429 дайте автоматическому повтору платформы подождать столько секунд, сколько указано в Retry-After. Для больших выгрузок предпочитайте пакеты.
• Платформы записывают в журнал каждый запрос и ответ. Никогда не помещайте ключ в URL и используйте ключ kbsrc_ везде, где сценарий только записывает документы.
• Если шаг завершается ошибкой 401 sources.push_key_invalid, проверьте, что идентификатор источника в URL соответствует ключу.