Zapier, Make i n8n

Platformy integracyjne łączą Sursę z setkami innych narzędzi bez pisania kodu. Nie potrzebują osobnej aplikacji Sursy: ich uniwersalne kroki żądań HTTP i webhooków współpracują bezpośrednio z API. Ten przewodnik omawia trzy najczęstsze scenariusze:

Niezależnie od platformy przechowuj klucz w jej magazynie danych uwierzytelniających lub połączeń, a nie w samym kroku, aby nie był kopiowany do każdego scenariusza i każdego dziennika uruchomień.

Wysyłaj rekordy jako karty

Utwórz w Sursie własne źródło (Sources → New source → Custom source (źródła → nowe źródło → własne źródło)), a następnie klucz dla niego na stronie źródła w sekcji API keys. Klucz zaczyna się od kbsrc_ i może tylko zapisywać dokumenty w tym źródle, dlatego właśnie taki klucz należy przechowywać na platformie zewnętrznej.

Typowa konfiguracja to „gdy rekord zostanie utworzony lub zaktualizowany w X, wyślij go do Sursy”:

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

• Mapuj na external_id stały identyfikator rekordu, nigdy czas ani numer uruchomienia. Wtedy ponowne wysłanie tego samego rekordu aktualizuje tę samą kartę, a ponowiony krok jest nieszkodliwy: odpowiedź to unchanged.
• Dla wyzwalacza „rekord usunięty” dodaj drugi przepływ pracy z metodą DELETE i adresem URL https://api.example.com/v1/push/sources/42/documents/{{record_id}}.
• Sprawdź połączenie za pomocą GET https://api.example.com/v1/push/sources/42 z tym samym nagłówkiem Authorization. Zwraca ono nazwę źródła i liczbę jego dokumentów.

Pola dokumentu są takie same jak w kodzie.

Zapier

Użyj Webhooks by Zapier → Custom Request:

• Method: POST.
• URL: https://api.example.com/v1/push/sources/42/documents.
• Data Pass-Through: wyłączone. Data: powyższy JSON z polami wstawionymi z wyzwalacza.
• Headers: Authorization = Bearer kbsrc_…, Content-Type = application/json.

Make

Użyj modułu HTTP → Make a request:

• Method POST, URL jak powyżej, Headers Authorization: Bearer kbsrc_….
• Body type Raw, Content type JSON (application/json), Request content: powyższy JSON ze zmapowanymi wartościami.
• Włącz Parse response, aby używać result (created, updated, unchanged) w kolejnych modułach.
• Aby wysłać plik, wybierz Body type Multipart/form-data z polem file (plik z wcześniejszego modułu) i polem tekstowym document, które zawiera pola JSON bez content.

n8n

Użyj węzła HTTP Request:

• Method POST, URL jak powyżej.
• Authentication Generic Credential Type → Header Auth, z nazwą Authorization i wartością Bearer kbsrc_….
• Send Body włączone, Body Content Type JSON, pola zmapowane wyrażeniami, np. {{ $json.id }}.

Na potrzeby pełnego eksportu według harmonogramu połącz trzy węzły HTTP Request: otwórz synchronizację (POST …/syncs z {"type": "initial"} za pierwszym razem, a z {"type": "incremental"} później), wyślij elementy i zamknij synchronizację z {"status": "complete"}. n8n uruchamia węzeł raz dla każdego elementu; aby wysyłać mniej żądań, zgrupuj elementy węzłem Aggregate i wyślij je do …/documents/batch jako {"sync_number": …, "documents": [...]}.

Zadaj pytanie w przepływie pracy

Przepływ pracy może zadać pytanie Sursie i użyć odpowiedzi: przygotować szkic odpowiedzi na zgłoszenie do pomocy technicznej, wzbogacić rekord w CRM, opublikować odpowiedź na kanale czatu. Użyj klucza API organizacji z zakresem ask i rolą, która widzi właściwe kolekcje.

Odpowiedź zawiera tekst odpowiedzi w answer (Markdown) i jej źródła w sources, każde z doc_name. Gdy baza wiedzy nie ma nic na temat pytania, ustawiane jest pole empty (np. no_hits): dodaj krok filtra, aby przepływ pracy nie publikował pustej odpowiedzi. Zob. Zbuduj bota odpowiadającego na pytania.

Przygotowanie odpowiedzi może zająć kilka sekund. Jeśli krok HTTP platformy ma krótki domyślny limit czasu, zwiększ go do co najmniej 60 sekund.

Uruchom przepływ pracy po zdarzeniu Sursy

Każda platforma może odbierać webhooki:

1. Utwórz wyzwalacz i skopiuj adres HTTPS, który otrzymasz.
2. W Sursie zarejestruj webhook z tym adresem i wybranymi zdarzeniami w sekcji Administration → Integrations → Webhooks and API (administracja → integracje → webhooki) lub za pomocą POST /v1/webhooks.
3. Wyślij zdarzenie testowe ze strony webhooka i zmapuj pola zdarzenia (type, data.card.title, …) w kolejnych krokach.

Sprawdzaj podpis. Adres wyzwalacza jest publiczny: każdy, kto go pozna, może wysyłać na niego żądania. Zweryfikuj podpis każdego dostarczenia, zanim na nie zareagujesz, zwłaszcza jeśli przepływ pracy zmienia dane:

• W n8n dodaj węzeł Code po węźle Webhook z weryfikatorem Node.js z przewodnika Odbieraj webhooki i włącz w węźle Webhook opcję surowej treści (raw body), aby dostępne były dokładne bajty.
• W Zapier i Make, gdzie trudniej dostać się do surowej treści, przynajmniej trzymaj adres w tajemnicy, filtruj według type i przed podjęciem działania ponownie odczytaj obiekt z API.

Ponowienia i duplikaty dotyczą platform tak samo jak każdego odbiorcy: filtruj według id zdarzenia, jeśli podwójne uruchomienie byłoby szkodliwe.

Wskazówki

• Przy 429 pozwól, aby automatyczne ponawianie platformy odczekało liczbę sekund z Retry-After. Przy dużych eksportach preferuj pakiety.
• Platformy zapisują w dziennikach każde żądanie i odpowiedź. Nigdy nie umieszczaj klucza w adresie URL i używaj klucza kbsrc_ wszędzie tam, gdzie przepływ pracy tylko zapisuje dokumenty.
• Jeśli krok kończy się błędem 401 sources.push_key_invalid, sprawdź, czy ID źródła w adresie URL odpowiada kluczowi.