API और वेबहुक से अपना सॉफ़्टवेयर जोड़ें

सिर्फ़ उन्हीं अनुमतियों वाली कुंजी बनाएँ जो उस टूल को चाहिए

सेटिंग्स → API और वेबहुक → कुंजी बनाएँ। इसका नाम व्यक्ति के बजाय टूल के नाम पर रखें — महीनों बाद इस सूची और सुरक्षा लॉग में आपको यही नाम दिखेगा। फिर अनुमतियों पर टिक करें, और सिर्फ़ उन्हीं पर जो ज़रूरी हैं: जो कुंजी सिर्फ़ पढ़ सकती है, उससे कुछ भी लिखवाया नहीं जा सकता।

• leads:read — लीड, चरण और परिणाम पढ़ना
• leads:write — लीड बनाना, अपडेट करना और हटाना, नोट जोड़ना
• calls:read — कॉल हिस्ट्री पढ़ना
• users:read — इस वर्कस्पेस के लोगों को पढ़ना
• webhooks:manage — वेबहुक बनाना और हटाना

इसे अभी कॉपी करें — यह एक ही बार दिखती है

कुंजी lk_live_ से शुरू होती है और ठीक एक बार दिखती है, बनाते ही खुलने वाले डायलॉग में। इसका सिर्फ़ हैश सहेजा जाता है, इसलिए बाद में कोई इसे वापस नहीं पढ़ सकता; सूची में शुरू के कुछ अक्षर दिखते हैं ताकि आप अपनी कुंजियों में फ़र्क कर सकें। खो जाए तो उपाय यही है कि उस कुंजी को रद्द करें और नई जारी करें। कुंजी किसी एक एजेंट की नहीं, वर्कस्पेस की होती है — जो इंटीग्रेशन आपकी लीड का सिर्फ़ एक हिस्सा देखे, वह आधा डेटा सिंक करेगा और टूटा हुआ लगेगा — और वह जो कुछ भी लिखती है, सुरक्षा लॉग में उसी के नाम दर्ज होता है।

बेस URL और पहली कॉल

सेटिंग्स → API और वेबहुक में आपका बेस URL दिखता है — आज https://api.lumakol.com/api/v1 — और कुंजी हर रिक्वेस्ट पर bearer टोकन के रूप में जाती है। सबसे पहले GET /ping कॉल करें: यह बताती है कि कुंजी किस वर्कस्पेस की है और उसमें कौन-सी अनुमतियाँ हैं, जिससे कोई असली कोड लिखने से पहले ही साबित हो जाता है कि कुंजी, हेडर और पता सब सही हैं। हर एंडपॉइंट, फ़ील्ड और एरर कोड API संदर्भ में दिया गया है: सेटिंग्स → API और वेबहुक → API संदर्भ (आपको साइन इन होना चाहिए)।

• curl https://api.lumakol.com/api/v1/ping -H "Authorization: Bearer lk_live_…"

अपनी लीड पढ़ें

GET /leads लीड का एक पेज लौटाता है, और वे फ़िल्टर देता है जिनकी आप उम्मीद करेंगे: stage, owner, source, tag, टेक्स्ट खोज के लिए q, और एक बार में 200 तक limit। जवाब एक ऑब्जेक्ट होता है, सीधी सूची नहीं — लीड data में होती हैं, और उनके साथ next_cursor और has_more होते हैं।

• curl "https://api.lumakol.com/api/v1/leads?limit=100" -H "Authorization: Bearer lk_live_…"
• GET /leads/find फ़ोन, ईमेल या आपके ख़ुद सेट किए external_id से एक लीड ढूँढता है
• GET /stages और GET /dispositions आपकी अपनी पाइपलाइन और परिणाम सूचियों के पीछे के id देते हैं

पेजिंग, और एक कॉपी को बराबर अपडेट रखना

किसी पेज का next_cursor अगली बार cursor के रूप में भेजें और तब तक दोहराएँ जब तक has_more false न हो जाए; cursor स्थिर रहता है, इसलिए पेजिंग के दौरान बदलने वाली लीड की वजह से कोई पंक्ति छूटती नहीं। लगातार चलने वाले सिंक के लिए याद रखें कि पिछली बार कब चलाया था और अगली बार उसे updated_since के रूप में भेजें — आपको सिर्फ़ उसके बाद का बदलाव मिलता है, और उसमें भी आप इसी तरह पेजिंग करते हैं। हर कुंजी एक मिनट में 60 रिक्वेस्ट कर सकती है, और एक वर्कस्पेस अपनी सभी कुंजियों को मिलाकर एक मिनट में 120 और एक दिन में 10,000। API कुंजियाँ पेड प्लान पर मिलती हैं, मुफ़्त ट्रायल के दौरान नहीं। जवाबों में RateLimit-Limit, RateLimit-Remaining और RateLimit-Reset हेडर होते हैं, और 429 के साथ Retry-After आता है; जब Remaining शून्य हो जाए, तो लूप में बार-बार कोशिश करने के बजाय रीसेट का इंतज़ार करें।

वेबहुक जोड़ें

सेटिंग्स → API और वेबहुक → वेबहुक जोड़ें। URL https होना चाहिए और इंटरनेट से पहुँच में होना चाहिए — निजी या आंतरिक पता सहेजते समय ही अस्वीकार हो जाता है और हर डिलीवरी से पहले फिर जाँचा जाता है, इसलिए बाद में DNS बदलकर भी इससे बचा नहीं जा सकता। जो इवेंट चाहिए उन पर टिक करें, फिर टेस्ट से एक सैंपल डिलीवरी कतार में डालें और भरोसा करने से पहले साबित करें कि आपका रिसीवर काम करता है। डिलीवरी एक कतार से भेजी जाती हैं जिसे हर दस सेकंड में जाँचा जाता है, इसलिए उन्हें तुरंत नहीं, कुछ सेकंड में आने की उम्मीद रखें।

• lead.created — कोई लीड हाथ से, API से, फ़ॉर्म से, लीड स्रोत से, वेबसाइट चैट से या मिस्ड कॉल से जोड़ी जाती है (फ़ाइल आयात से नहीं)
• lead.updated — कोई लीड ऐप में, API से या किसी ऑटोमेशन नियम से एडिट होती है (कॉल का परिणाम दर्ज करने पर इसकी जगह call.logged भेजा जाता है)
• lead.stage_changed — कोई लीड पाइपलाइन के दूसरे चरण में जाती है
• lead.assigned — लीड किसी को दी जाती है, या वापस ली जाती है
• call.logged — किसी कॉल पर परिणाम दर्ज होता है
• follow_up.due — जिस लीड का कोई मालिक है, उसका फ़ॉलो-अप 15 मिनट के भीतर देय है

सिग्नेचर की जाँच करें

हर रिक्वेस्ट में चार हेडर होते हैं: X-LumaKol-Event, X-LumaKol-Delivery, X-LumaKol-Timestamp और X-LumaKol-Signature। सिग्नेचर sha256= के बाद timestamp, एक पूर्ण विराम (.) और raw body का HMAC-SHA256 होता है, जिसकी कुंजी वह साइनिंग सीक्रेट है जो वेबहुक बनाते समय दिखा था — वह whsec_ से शुरू होता है। इसे अपने दोबारा serialise किए JSON पर नहीं, बल्कि वाकई मिले बाइट्स पर फिर से गणना करें, दोनों की तुलना constant-time comparison से करें, और जिसका timestamp हाल का न हो उसे अस्वीकार करें। जो रिक्वेस्ट मेल नहीं खाती, वह हमारी ओर से नहीं आई।

• जिस स्ट्रिंग पर साइन होता है, वह है timestamp, एक पूर्ण विराम, फिर body — इसी क्रम में
• X-LumaKol-Delivery दोबारा कोशिशों में नहीं बदलता: इसे सहेजें और दोहराव को अनदेखा करें, क्योंकि जो डिलीवरी हमारी तरफ़ टाइम आउट हुई, उसे दोबारा भेजा जाता है, भले आपके सर्वर ने उसे पूरा कर लिया हो
• “नया सीक्रेट” कुंजी बदल देता है और पुरानी तुरंत काम करना बंद कर देती है, इसलिए पहले अपना रिसीवर अपडेट करें

डिलीवरी लॉग और दोबारा कोशिशें

किसी वेबहुक के नीचे “हाल की डिलीवरी” खोलें और पिछली डिलीवरी देखें: इवेंट, वे पहुँचीं या नहीं, आपके सर्वर का लौटाया स्टेटस कोड या हमें मिली एरर, और कब। जो भी 2xx नहीं है — रीडायरेक्ट को भी विफलता माना जाता है — उसे पाँच मिनट, पंद्रह मिनट, एक घंटे, तीन घंटे, छह घंटे और फिर छह घंटे बाद दोबारा भेजा जाता है: लगभग सोलह घंटों में सात कोशिशें, ताकि कुछ देर बंद रहे रिसीवर का कुछ न खोए और दिन भर बंद रहने वाले को आख़िरकार छोड़ दिया जाए। सिर्फ़ स्टेटस कोड या एरर रखा जाता है, आपके जवाब की body नहीं। वेबहुक अपनी आख़िरी विफलता तब तक दिखाता रहता है जब तक वह सफल न हो जाए या आप उसे बंद करके फिर चालू न करें।

• स्विच वेबहुक को हटाए बिना रोक देता है — दोबारा डिप्लॉय करते समय आपको यही चाहिए
• डिलीवरी की पंक्तियाँ डीबगिंग में मदद के लिए हैं, रिकॉर्ड के लिए नहीं — लगभग दो हफ़्ते बाद वे साफ़ हो जाती हैं
• वेबहुक हटाने पर उसके लिए कतार में बचा सब कुछ हट जाता है

काम ख़त्म होने पर कुंजी रद्द करें

रद्द करें उस कुंजी का इस्तेमाल करने वाली हर चीज़ को तुरंत रोक देता है, और इसे वापस नहीं लिया जा सकता — जानबूझकर कोई पॉज़ नहीं रखा गया है। जब कोई टूल बंद हो, जब उसे सेट करने वाला व्यक्ति चला जाए, या जैसे ही आपको लगे कि कुंजी लीक हुई है, रद्द करें, फिर नई जारी करें और उसे टूल में पेस्ट करें। सूची में दिखता है कि हर कुंजी आख़िरी बार कब इस्तेमाल हुई — ऐसी कुंजी पहचानने का यही सबसे तेज़ तरीका है जिसकी अब किसी को ज़रूरत नहीं।