Zapier, Make і n8n

Платформи інтеграцій підключають Sursa до сотень інших інструментів без коду. Їм не потрібен окремий застосунок Sursa: їхні універсальні кроки HTTP-запиту й вебхуків працюють з API напряму. Цей посібник описує три найпоширеніші сценарії:

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

Надсилайте записи як картки

Створіть власне джерело в Sursa (Sources → New source → Custom source, тобто джерела → нове джерело → власне джерело), а потім ключ для нього на сторінці джерела в розділі API keys (ключі 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 зареєструйте вебхук із цією адресою та потрібними подіями в розділі Administration → Integrations → Webhooks and 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, перевірте, що ID джерела в URL відповідає ключу.