सपोर्ट API, घटनाएँ और थोक निर्यात
सपोर्ट मॉड्यूल से किसी इंटीग्रेशन को जो कुछ चाहिए, सब यहाँ है: केस, थ्रेड, SLA, कतार, सेवा सूची, हक़ और सर्वेक्षण के एंडपॉइंट; हस्ताक्षरित घटना सदस्यताएँ, पुनःप्रयास और दोबारा भेजने के साथ; कर्सर से आगे बढ़ने वाली फ़ीड; केस और संदेशों का थोक निर्यात; और किसी दूसरे हेल्प डेस्क से पुराने केसों का idempotent आयात। हर एंडपॉइंट के लिए MCP सर्वर पर एक मेल खाता टूल है।
सपोर्ट तक सामान्य रिकॉर्ड API से हमेशा पहुँचा जा सकता था: केस एक रिकॉर्ड है, इसलिए उसकी सूची बनाना और उसे बनाना पहले से चलता था। जो नहीं चलता था वह यह सब था जो केस के साथ रहता है और रिकॉर्ड नहीं है। संदेश थ्रेड, SLA घड़ी, कतारें, सेवा सूची, हक़ का शेष और सर्वेक्षण, इनका कोई एंडपॉइंट ही नहीं था, इसलिए कोई इंटीग्रेशन केस खोल तो सकता था पर उसका जवाब नहीं दे सकता था।
यह लेख सपोर्ट एंडपॉइंट, MCP सर्वर पर वही टूल, पुनःप्रयास और दोबारा भेजने वाली घटना सदस्यताएँ, जहाँ से छूटा वहीं से चलने वाली घटना फ़ीड, और किसी दूसरे हेल्प डेस्क से केसों का इतिहास लाने का तरीका, इन सबको कवर करता है।
शुरुआत कहाँ से करें - सेटिंग्स में, API और डेवलपर के नीचे एक API कुंजी बनाइए। कुंजी आपका खाता तय करती है और सब कुछ उसी तक सीमित रखती है। - हर कॉल का प्रमाणीकरण बाकी API जैसा ही है: Authorization: Bearer और उसके बाद आपकी कुंजी। - इस लेख की हर चीज़ /api/v1/service के नीचे रहती है और ticket वस्तु तक सीमित है। दूसरी वस्तुओं तक सीमित कुंजी यहाँ नहीं पहुँचती। - हर एंडपॉइंट के लिए MCP सर्वर पर एक मेल खाता टूल है, इसलिए SellioCRM से जुड़ा कोई AI एजेंट बिल्कुल यही काम कर सकता है।
केस - GET /api/v1/service/tickets केस को सपाट पंक्तियों में सूचीबद्ध करता है, स्थिति, प्राथमिकता, कतार, मालिक या मुक्त पाठ से छाना हुआ। पिछली सिंक के बाद जो बदला सिर्फ़ वही लाने के लिए updated_since में समयमुद्रा दीजिए, और पन्ने बदलने के लिए limit और offset। - GET /api/v1/service/tickets/{id} एक केस SLA घड़ी के साथ लौटाता है: नियत तिथि, वह रुकी हुई है या नहीं, पहले जवाब का लक्ष्य और अगले जवाब का लक्ष्य। यही घड़ी इस एंडपॉइंट के होने की वजह है; सामान्य रिकॉर्ड एंडपॉइंट फ़ील्ड लौटाता है, समयसीमाएँ नहीं। - POST /api/v1/service/tickets उसी रास्ते से केस खोलता है जिससे कंसोल खोलता है, इसलिए प्रोटोकॉल नंबर, SLA लक्ष्य, रूटिंग नियम और बाहर जाने वाले वेबहुक, सब होते हैं। - PATCH /api/v1/service/tickets/{id} स्थिति, प्राथमिकता, श्रेणी, कतार और ज़िम्मेदार बदलता है। सौंपना भी वही क्रिया है जो स्थिति बदलना, इसलिए उसके लिए अलग एंडपॉइंट नहीं है। - GET और POST /api/v1/service/tickets/{id}/messages थ्रेड पढ़ते और लिखते हैं। kind public ग्राहक को जवाब देता है और ईमेल भेजता है; kind internal ऐसा नोट छोड़ता है जो सिर्फ़ एजेंट देखते हैं। - POST /api/v1/service/tickets/merge दो केस मिलाता है: गौण केस मुख्य में समा जाता है और उसके संदेश वहाँ चले जाते हैं।
केस के आस-पास - GET /api/v1/service/queues कतारों की सूची देता है, हर एजेंट की क्षमता, कार्यसमय और डिफ़ॉल्ट प्राथमिकता के साथ। रूटिंग से पहले इसे पढ़िए: बनाने वाली कॉल कतार का नाम ही माँगती है। - GET और POST /api/v1/service/catalog सेवा सूची की वितरिका पढ़ते हैं और कोई वस्तु माँगते हैं। अनुरोध से एक असली केस खुलता है, वस्तु की कतार और प्राथमिकता के साथ; अपनी idempotencyKey भेजिए ताकि दोबारा कोशिश पर दूसरा केस खुलने के बजाय मौजूदा अनुरोध ही लौटे। - GET /api/v1/service/entitlements हर खाते या अनुबंध के सपोर्ट हक़ लौटाता है, बचे हुए शेष के साथ। - GET /api/v1/service/surveys संतुष्टि सर्वेक्षण के निमंत्रण उनकी स्थिति और जवाब की तारीख के साथ लौटाता है। गुमनाम सर्वेक्षण उत्तरदाता का नाम कभी नहीं लौटाते।
घटनाएँ, वास्तविक समय में और कर्सर से किसी इंटीग्रेशन को वास्तविक समय के दोनों हिस्से चाहिए: जिस क्षण कुछ होता है उसी क्षण खबर मिलना, और जब वह बंद पड़ा था तब जो छूट गया उसे बाद में पकड़ लेना। पहला सदस्यता से मिलता है और दूसरा फ़ीड से।
- POST /api/v1/service/subscriptions एक URL और आपकी मनचाही घटनाएँ दर्ज करता है। events में सटीक प्रकार लिए जाते हैं या ticket.* जैसा कोई परिवार वाइल्डकार्ड। अनजानी घटना नाम से ही अस्वीकार कर दी जाती है, क्योंकि ऐसी सदस्यता जो कभी चलती ही नहीं, त्रुटि से बुरी है। गुप्त कुंजी एक ही बार लौटती है; उसे कॉपी कर लीजिए।
- हर डिलीवरी एक POST के रूप में तीन हेडर के साथ आती है: x-sellio-event में घटना का नाम, x-sellio-delivery में उस प्रयास की आईडी, और x-sellio-signature में sha256 और उसके बाद वह कोड जो आपकी गुप्त कुंजी से ठीक उसी मूल पाठ पर निकाला गया है। अपनी तरफ़ उसे दोबारा निकालिए और मिलाइए; मेल न खाए तो कॉल छोड़ दीजिए।
- विफल डिलीवरी बढ़ते अंतराल पर दोहराई जाती है, लगभग एक मिनट, पाँच, तीस, दो घंटे और छह घंटे बाद। उसके बाद उसे मृत चिह्नित कर दिया जाता है और वह लॉग में बनी रहती है।
- GET /api/v1/service/deliveries इस सवाल का जाँचा जा सकने वाला जवाब है कि क्या यह घटना पहुँची। हर पंक्ति में प्रयास, आखिरी स्थिति कोड, त्रुटि और अगला निर्धारित पुनःप्रयास होता है।
- POST /api/v1/service/deliveries/{id}/replay एक डिलीवरी दोबारा भेजता है। यह संग्रहित मूल पाठ ही भेजता है, बाइट दर बाइट वही जो पहली बार गया था। अभी दोबारा पेलोड बनाने का मतलब होता आज की स्थिति को कल की समयमुद्रा के साथ भेजना।
- GET /api/v1/service/events फ़ीड है। पिछले जवाब का कर्सर भेजिए और आपको सिर्फ़ उसके बाद हुआ हिस्सा मिलेगा। nextCursor खाली पन्ने पर भी लौटता है, और वही आपको सहेजना है। कर्सर को अपारदर्शी मानिए: उससे गणित करना ही वह तरीका है जिससे इंटीग्रेशन आगे चलकर चुपचाप टूटता है।
- GET /api/v1/service/event-types हर उस घटना की सूची देता है जो उत्पाद भेज सकता है, यह भी कि तीन वेबहुक रजिस्ट्रियों में से कौन सी उसकी सदस्यता ले सकती है, और यह कि किसी सेवा सदस्यता तक पहुँचने के लिए आपके खाते में इवेंट बस चालू होना ज़रूरी है या नहीं। सदस्यता बनाने से पहले इसे पढ़िए।
केस और संदेशों का निर्यात GET /api/v1/service/export में entity के रूप में tickets या messages और format के रूप में json या csv लिया जाता है। संदेशों का निर्यात ही इस एंडपॉइंट के होने की वजह है: थ्रेड रिकॉर्ड नहीं है, इसलिए कोई दूसरी सतह उसे थोक में नहीं देती थी। since, status, queue, ticketId या kind से छानिए, और limit (अधिकतम 500) तथा offset से पन्ने बदलिए। json जवाब में hasMore आता है, जिससे आपको पता चलता है कि अभी एक और पन्ना बाकी है।
किसी दूसरे हेल्प डेस्क से इतिहास लाना POST /api/v1/service/import एक कॉल में अधिकतम 500 पंक्तियाँ लेता है। हर पंक्ति में externalKey चाहिए, यानी उस टूल में केस का नंबर जिसे आप छोड़ रहे हैं, और एक विषय। इसके साथ body, अनुरोधकर्ता का ईमेल, नाम और फ़ोन, प्राथमिकता, श्रेणी, कतार, चैनल, स्थिति और createdAt भी भेजे जा सकते हैं।
- आयात externalKey के हिसाब से idempotent है। वही फ़ाइल दो बार आयात करने पर पंक्तियाँ दोहराई नहीं जातीं, उन्हें पहले से मौजूद बताया जाता है, इसलिए आप विफल बैच बेझिझक दोबारा चला सकते हैं।
- केस स्रोत की तारीख और स्थिति के साथ जन्म लेता है। इसके बिना पंद्रह हज़ार बंद केस आज की तारीख पर नए बनकर आते, अभी काम कर रहे लोगों की कतार भर देते और अवधि के हर विश्लेषण में झूठ बोलते।
- बिना कुछ लिखे यह देखने के लिए कि क्या होता, dryRun true भेजिए।
- जो पंक्ति जाँच में विफल होती है वह बैच में अपनी जगह के साथ problems में एक प्रविष्टि बन जाती है, और बाकी बैच अंदर चला जाता है। तीन पंक्तियों में गलत तारीख होने से आपको सब कुछ फिर से शुरू नहीं करना पड़ता।