Zapier, Make și n8n

Platformele de integrare conectează Sursa la sute de alte instrumente fără cod. Nu au nevoie de o aplicație Sursa dedicată: pașii lor generici de cereri HTTP și de webhookuri lucrează direct cu API-ul. Acest ghid prezintă cele trei rețete cele mai frecvente:

Indiferent de platformă, păstrați cheia în spațiul ei pentru date de autentificare sau conexiuni, nu în pasul propriu-zis, ca să nu fie copiată în fiecare scenariu și în fiecare jurnal de rulare.

Trimiterea înregistrărilor ca fișe

Creați o sursă personalizată în Sursa (Sources → New source → Custom source, adică surse → sursă nouă → sursă personalizată), apoi o cheie pentru ea pe pagina sursei, în API keys. Cheia începe cu kbsrc_ și poate doar să scrie documente în această sursă, de aceea este cheia potrivită pentru a fi stocată pe o platformă terță.

Configurarea obișnuită este „când o înregistrare este creată sau actualizată în X, trimite-o în 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}}"
}

• Puneți în external_id un identificator stabil al înregistrării, niciodată un moment de timp sau un număr de rulare. Astfel, trimiterea din nou a aceleiași înregistrări actualizează aceeași fișă, iar un pas reîncercat nu face rău: răspunsul este unchanged.
• Pentru un declanșator „înregistrare ștearsă”, adăugați un al doilea workflow cu metoda DELETE și URL-ul https://api.example.com/v1/push/sources/42/documents/{{record_id}}.
• Testați conexiunea cu GET https://api.example.com/v1/push/sources/42 și același antet Authorization. Cererea returnează numele sursei și numărul ei de documente.

Câmpurile documentului sunt aceleași ca în cod.

Zapier

Folosiți Webhooks by Zapier → Custom Request:

• Method: POST.
• URL: https://api.example.com/v1/push/sources/42/documents.
• Data Pass-Through: dezactivat. Data: JSON-ul de mai sus, cu câmpurile inserate din declanșator.
• Headers: Authorization = Bearer kbsrc_…, Content-Type = application/json.

Make

Folosiți modulul HTTP → Make a request:

• Method POST, URL ca mai sus, Headers Authorization: Bearer kbsrc_….
• Body type Raw, Content type JSON (application/json), Request content: JSON-ul de mai sus, cu valorile preluate.
• Activați Parse response pentru a folosi result (created, updated, unchanged) în modulele următoare.
• Pentru a trimite un fișier, alegeți Body type Multipart/form-data, cu un câmp file (fișierul dintr-un modul anterior) și un câmp text document care conține câmpurile JSON fără content.

n8n

Folosiți nodul HTTP Request:

• Method POST, URL ca mai sus.
• Authentication Generic Credential Type → Header Auth, cu numele Authorization și valoarea Bearer kbsrc_….
• Send Body activat, Body Content Type JSON, câmpuri preluate cu expresii precum {{ $json.id }}.

Pentru un export complet programat, înlănțuiți trei noduri HTTP Request: deschideți o sincronizare (POST …/syncs cu {"type": "initial"} prima dată și {"type": "incremental"} după aceea), trimiteți elementele și închideți sincronizarea cu {"status": "complete"}. n8n rulează un nod o dată pentru fiecare element; pentru a trimite mai puține cereri, grupați elementele cu un nod Aggregate și trimiteți-le la …/documents/batch ca {"sync_number": …, "documents": [...]}.

O întrebare într-un workflow

Un workflow poate întreba Sursa și poate folosi răspunsul: schițează un răspuns la un tichet de asistență, completează o înregistrare din CRM, publică un răspuns într-un canal de chat. Folosiți o cheie API a organizației cu domeniul ask și un rol care vede colecțiile potrivite.

Răspunsul conține textul răspunsului în answer (Markdown) și sursele lui în sources, fiecare cu doc_name. Când baza de cunoștințe nu are nimic despre întrebare, este setat empty (de exemplu no_hits): adăugați un pas de filtrare, ca workflow-ul să nu publice un răspuns gol. Vedeți Construiți un bot de întrebări și răspunsuri.

Răspunsurile pot dura câteva secunde. Dacă pasul HTTP al platformei are implicit un timp de expirare scurt, măriți-l la cel puțin 60 de secunde.

Pornirea unui workflow dintr-un eveniment Sursa

Fiecare platformă poate primi webhookuri:

1. Creați declanșatorul și copiați adresa HTTPS pe care v-o dă.
2. În Sursa, înregistrați un webhook cu acea adresă și cu evenimentele dorite, în Administration → Integrations → Webhooks and API (administrare → integrări → webhookuri și API) sau cu POST /v1/webhooks.
3. Trimiteți un eveniment de test de pe pagina webhookului și preluați câmpurile evenimentului (type, data.card.title, …) în pașii următori.

Verificați semnătura. Adresa declanșatorului este publică: oricine o află îi poate trimite cereri. Verificați semnătura fiecărei livrări înainte de a acționa pe baza ei, mai ales dacă workflow-ul modifică date:

• În n8n, adăugați după nodul Webhook un nod Code cu funcția de verificare Node.js din Primiți webhookuri și activați opțiunea pentru corpul brut a nodului Webhook, ca octeții exacți să fie disponibili.
• În Zapier și Make, unde corpul brut este mai greu de obținut, cel puțin păstrați adresa secretă, filtrați după type și citiți din nou obiectul din API înainte de a acționa pe baza lui.

Reîncercările și dublurile se aplică platformelor ca oricărui receptor: filtrați după id-ul evenimentului dacă o rulare dublă ar face rău.

Sfaturi

• La 429, lăsați reîncercarea automată a platformei să aștepte secundele din Retry-After. Pentru exporturile mari preferați loturile.
• Platformele înregistrează în jurnal fiecare cerere și fiecare răspuns. Nu puneți niciodată o cheie într-un URL și preferați cheia kbsrc_ oriunde workflow-ul doar scrie documente.
• Dacă un pas eșuează cu 401 sources.push_key_invalid, verificați că identificatorul sursei din URL corespunde cheii.