Zapier, Make и n8n

Платформите за интеграции свързват Sursa със стотици други инструменти без код. Не им е нужно отделно приложение на Sursa: стандартните им стъпки за HTTP заявки и уебхукове работят директно с API. Това ръководство описва трите най-често срещани рецепти:

Каквато и платформа да използвате, пазете ключа в хранилището ѝ за идентификационни данни или за връзки, а не в самата стъпка, за да не се копира във всеки сценарий и във всеки дневник на изпълненията.

Изпращане на записи като карти

Създайте собствен източник в Sursa (Sources → New source → Custom source – източници, нов източник, собствен източник), а след това ключ за него на страницата на източника в раздела API keys. Ключът започва с 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 (администриране, интеграции, уебхукове и API) или с POST /v1/webhooks.
3. Изпратете тестово събитие от страницата на уебхука и съпоставете полетата на събитието (type, data.card.title, …) в следващите стъпки.

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

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

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

Съвети

• При 429 оставете автоматичния повторен опит на платформата да изчака секундите от Retry-After. За големи експорти предпочитайте пакети.
• Платформите записват в дневник всяка заявка и всеки отговор. Никога не поставяйте ключ в URL адрес и предпочитайте ключа kbsrc_ навсякъде, където работният процес само записва документи.
• Ако стъпка се провали с 401 sources.push_key_invalid, проверете дали ID на източника в URL адреса съответства на ключа.