Zapier, Make और n8n

इंटीग्रेशन प्लैटफ़ॉर्म Sursa को बिना कोड के सैकड़ों दूसरे टूल से जोड़ते हैं। उन्हें Sursa के लिए अलग ऐप की ज़रूरत नहीं है: उनके सामान्य HTTP रिक्वेस्ट और वेबहुक स्टेप सीधे API के साथ काम करते हैं। यह गाइड तीन सबसे आम तरीक़े बताती है:

तरीक़ा	दिशा	क्या चाहिए
किसी दूसरे टूल से रिकॉर्ड Sursa में कार्ड के रूप में भेजना	Sursa में	एक कस्टम स्रोत और उसकी `kbsrc_` कुंजी
वर्कफ़्लो में Sursa से सवाल पूछना	Sursa में और वापस	`ask` स्कोप वाली API कुंजी
Sursa में कुछ होने पर वर्कफ़्लो शुरू करना	Sursa से बाहर	प्लैटफ़ॉर्म की ओर इशारा करता वेबहुक

आप कोई भी प्लैटफ़ॉर्म इस्तेमाल करें, कुंजी उसके क्रेडेंशियल या कनेक्शन स्टोर में रखें, स्टेप में नहीं, ताकि वह हर सिनेरियो और रन लॉग में कॉपी न हो।

रिकॉर्ड को कार्ड के रूप में भेजें

Sursa में कस्टम स्रोत बनाएँ (Sources → New source → Custom source (स्रोत → नया स्रोत → कस्टम स्रोत)), फिर स्रोत के पेज पर API keys (स्रोत की API कुंजियाँ) में उसके लिए कुंजी बनाएँ। कुंजी kbsrc_ से शुरू होती है और सिर्फ़ इसी स्रोत में दस्तावेज़ लिख सकती है, इसलिए तीसरे पक्ष के प्लैटफ़ॉर्म पर रखने के लिए यही सही कुंजी है।

आम सेटअप है “जब X में कोई रिकॉर्ड बने या अपडेट हो, तो उसे Sursa में भेजें”:

सेटिंग	मान
Method	`POST`
URL	`https://api.example.com/v1/push/sources/42/documents`
हेडर `Authorization`	`Bearer kbsrc_…`
हेडर `Content-Type`	`application/json`
बॉडी	नीचे दिया JSON, जिसमें फ़ील्ड ट्रिगर से मैप किए गए हों

{
  "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 में रिकॉर्ड की स्थिर ID मैप करें, समय या रन नंबर कभी नहीं। तब वही रिकॉर्ड फिर से भेजने पर वही कार्ड अपडेट होता है, और दोबारा चला स्टेप नुक़सान नहीं करता: जवाब unchanged होता है।
“रिकॉर्ड हटाया गया” ट्रिगर के लिए दूसरा वर्कफ़्लो जोड़ें, Method 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।
आगे के मॉड्यूल में result (created, updated, unchanged) इस्तेमाल करने के लिए Parse response चालू करें।
फ़ाइल भेजने के लिए Body type Multipart/form-data चुनें, file फ़ील्ड (पिछले मॉड्यूल की फ़ाइल) और document टेक्स्ट फ़ील्ड के साथ, जिसमें content के बिना JSON फ़ील्ड हों।

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 नोड एक के बाद एक जोड़ें: सिंक खोलें (पहली बार {"type": "initial"} के साथ POST …/syncs, बाद में {"type": "incremental"}), आइटम भेजें, और {"status": "complete"} के साथ सिंक बंद करें। n8n हर आइटम के लिए नोड एक बार चलाता है; कम रिक्वेस्ट भेजने के लिए आइटम को Aggregate नोड से ग्रुप करें और उन्हें {"sync_number": …, "documents": [...]} के रूप में …/documents/batch पर भेजें।

वर्कफ़्लो में सवाल पूछें

वर्कफ़्लो Sursa से पूछकर जवाब इस्तेमाल कर सकता है: सपोर्ट टिकट के जवाब का ड्राफ़्ट बनाना, CRM रिकॉर्ड में जानकारी जोड़ना, चैट चैनल में जवाब पोस्ट करना। ask स्कोप वाली संगठन की API कुंजी इस्तेमाल करें, ऐसे रोल के साथ जो सही कलेक्शन देखता हो।

सेटिंग	मान
Method	`POST`
URL	`https://api.example.com/v1/ask`
हेडर `Authorization`	`Bearer kb_…`
बॉडी	`{"query": "{{ticket_subject}}: {{ticket_body}}", "collection": "support"}`

रिस्पॉन्स में जवाब answer (Markdown) में होता है और उसके स्रोत sources में, हर एक doc_name के साथ। जब नॉलेज बेस में सवाल के बारे में कुछ नहीं होता, तो empty सेट होता है (उदाहरण के लिए, no_hits): फ़िल्टर स्टेप जोड़ें, ताकि वर्कफ़्लो ख़ाली जवाब पोस्ट न करे। देखें सवाल-जवाब बॉट बनाना।

जवाब में कई सेकंड लग सकते हैं। अगर प्लैटफ़ॉर्म के HTTP स्टेप का डिफ़ॉल्ट टाइमआउट छोटा है, तो उसे कम से कम 60 सेकंड करें।

Sursa के इवेंट से वर्कफ़्लो शुरू करें

हर प्लैटफ़ॉर्म वेबहुक पा सकता है:

प्लैटफ़ॉर्म	ट्रिगर
Zapier	Webhooks by Zapier → Catch Raw Hook (raw, ताकि बॉडी वैसी ही रहे जैसी भेजी गई थी)
Make	Webhooks → Custom webhook
n8n	Webhook नोड, मेथड `POST`

ट्रिगर बनाएँ और उसका दिया HTTPS पता कॉपी करें।
Sursa में Administration → Integrations → Webhooks and API (एडमिनिस्ट्रेशन → इंटीग्रेशन → वेबहुक और API) में या POST /v1/webhooks से उस पते और अपने चाहे इवेंट के साथ वेबहुक रजिस्टर करें।
वेबहुक के पेज से टेस्ट इवेंट भेजें, और अगले स्टेप में इवेंट के फ़ील्ड (type, data.card.title, …) मैप करें।

सिग्नेचर जाँचें। ट्रिगर का पता पब्लिक है: जिसे भी यह पता चल जाए, वह इस पर रिक्वेस्ट भेज सकता है। हर डिलीवरी पर कार्रवाई करने से पहले उसका सिग्नेचर जाँचें, ख़ास तौर पर तब, जब वर्कफ़्लो डेटा बदलता हो:

n8n में Webhook नोड के बाद Code नोड जोड़ें, जिसमें वेबहुक पाना का Node.js वाला जाँच कोड हो, और Webhook नोड में raw body का विकल्प चालू करें, ताकि हूबहू बाइट उपलब्ध हों।
Zapier और Make में, जहाँ raw body तक पहुँचना मुश्किल है, कम से कम पता गोपनीय रखें, type पर फ़िल्टर करें, और कार्रवाई करने से पहले ऑब्जेक्ट को API से फिर से पढ़ें।

रीट्राई और डुप्लिकेट प्लैटफ़ॉर्म पर भी किसी भी प्राप्तकर्ता की तरह लागू होते हैं: अगर दोहराया गया रन नुक़सान कर सकता है, तो इवेंट के id पर फ़िल्टर करें।

सुझाव

429 पर प्लैटफ़ॉर्म के ऑटोमैटिक रीट्राई को Retry-After के सेकंड तक इंतज़ार करने दें। बड़े एक्सपोर्ट के लिए बैच इस्तेमाल करें।
प्लैटफ़ॉर्म हर रिक्वेस्ट और रिस्पॉन्स लॉग करते हैं। कुंजी कभी URL में न डालें, और जहाँ वर्कफ़्लो सिर्फ़ दस्तावेज़ लिखता है, वहाँ kbsrc_ कुंजी इस्तेमाल करें।
अगर कोई स्टेप 401 sources.push_key_invalid के साथ असफल होता है, तो जाँचें कि URL में स्रोत की ID कुंजी से मेल खाती है।