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}}"
}

• Стабилан ID записа мапирајте у 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 адреси одговара кључу.