Shifton कार्य आपको प्लेटफ़ॉर्म के साथ काम को स्वचालित करने और खुले API के ज़रिए उसे बाहरी सेवाओं से जोड़ने की सुविधा देता है। API के ज़रिए सभी मुख्य इकाइयाँ उपलब्ध हैं — कार्य, ग्राहक, कर्मचारी, चेकलिस्ट्स, इन्वेंटरी, सेवा क्षेत्र, इनवॉइसिंग के दस्तावेज़ और रिपोर्ट्स — इसलिए Shifton को आपके HR, वेतन गणना और विश्लेषण सिस्टम्स के साथ, और साथ ही कंपनी की आंतरिक सेवाओं के साथ भी जोड़ा जा सकता है।
API दस्तावेज़ीकरण
दस्तावेज़ीकरण दो संस्करणों में प्रकाशित है:
- 🚀 नई दस्तावेज़ीकरण — अद्यतन संरचना और नवीनतम मेथड्स वाला संदर्भ-गाइड का वर्तमान संस्करण: 👉 https://api2.shifton.com/openapi/
- 📄 पुराने दस्तावेज़ — पिछला संस्करण (मौजूदा इंटीग्रेशनों के लिए अब भी समर्थित): 👉 https://api2.shifton.com/docs/
दोनों संस्करण सीधे ऐप्लिकेशन से खोले जा सकते हैं — Developer अनुभाग में, अवलोकन टैब पर, “नई दस्तावेज़ीकरण” और “पुराने दस्तावेज़” बटनों से।
दस्तावेज़ीकरण दो भाषाओं में उपलब्ध है। नई दस्तावेज़ीकरण के पेज के ऊपरी दाएँ कोने में EN / RU स्विच है — चुनी गई भाषा याद रखी जाती है।
API कुंजी कैसे प्राप्त करें
API कुंजी ऐप्लिकेशन में ही बनाई जाती है:
- Developer अनुभाग खोलें।
- API कुंजियाँ टैब पर जाएँ (“API कुंजियाँ”)।
- “API कुंजी बनाएं” पर क्लिक करें।
कुंजी बनाते समय क्या भरना है
API कुंजी बनाएं नाम की साइड पैनल खुलेगी, जिसमें ये फ़ील्ड होंगे:
- शीर्षक — कुंजी का नाम, अनिवार्य फ़ील्ड। उद्देश्य के अनुसार नाम दें, ताकि बाद में समझ आए कि क्या बंद करना है: “1C में निर्यात”, “विश्लेषण के लिए रिपोर्ट्स”।
- समाप्त होता है — वह तिथि, जिसके बाद कुंजी काम करना बंद कर देगी। फ़ील्ड खाली छोड़ दें, तो वैधता की कोई सीमा नहीं होगी।
- पहुंच — कुंजी के अधिकारों का दायरा:
- Full access (act as me) — कुंजी आपके नाम से और आपके अधिकारों के साथ काम करती है।
- प्रतिबंधित अनुमतियाँ — अनुमतियों का सीमित सेट, जिसे आप स्वयं चुनते हैं।
कुंजी बनाने के लिए जोड़ें पर क्लिक करें, या पैनल बंद करने के लिए रद्द करें पर क्लिक करें।
📷 *कुंजी बनाने वाले पैनल का स्क्रीनशॉट — प्रोड पर लेना है*
कुंजी किसी एक विशिष्ट कंपनी के लिए बनाई जाती है और केवल उसी के डेटा के साथ काम करती है। कुंजी को किसी भी समय रद्द किया जा सकता है — रद्द करना तुरंत लागू होता है, और इस कुंजी के साथ आने वाले सभी अनुरोध 401 त्रुटि लौटाएँगे।
महत्वपूर्ण: बनाई गई कुंजी केवल एक बार दिखाई जाती है। उसे तुरंत कॉपी करें और सुरक्षित जगह पर रखें — दोबारा उसे पाना संभव नहीं है। कुंजी खो जाए, तो नई बनाएँ और पुरानी को रद्द कर दें।
प्राधिकरण
API के सभी अनुरोध हेडर में कुंजी से हस्ताक्षरित होते हैं:
Authorization: Bearer {your_API_key}API का बेस पता:
https://api2.shifton.com/work/1.0.0वैध कुंजी के बिना भेजा गया अनुरोध 401 और बॉडी {"message":"Unauthenticated."} लौटाता है।
पहला अनुरोध
उदाहरण के लिए, कंपनी के कर्मचारियों की सूची पाने के लिए ({companyId} की जगह अपनी कंपनी का ID रखें):
GET https://api2.shifton.com/work/1.0.0/companies/{companyId}/employees
Authorization: Bearer {your_API_key}
Accept: application/jsonवही काम curl के ज़रिए:
curl -H "Authorization: Bearer {your_API_key}" \
-H "Accept: application/json" \
https://api2.shifton.com/work/1.0.0/companies/{companyId}/employeesकंपनी का ID ऐप्लिकेशन के अड्रेस बार में दिखता है: app.shifton.com/c/8397/... — /c/ के बाद की संख्या।
API के ज़रिए क्या-क्या उपलब्ध है
संदर्भ-गाइड में 360 से अधिक मेथड शामिल हैं। विज़िट वाली सेवा के लिए मुख्य अनुभाग:
- कार्य —
/companies/{companyId}/tasks: बनाना, बदलना, स्थितियाँ, कार्यों की फ़ाइलें। - कामों की सूची (To Do) —
/companies/{companyId}/todo। - ग्राहक —
/companies/{companyId}/clients, और साथ ही ग्राहकों के पते और कस्टम फ़ील्ड। - चेकलिस्ट्स —
/companies/{companyId}/checklists। - सेवा क्षेत्र —
/companies/{companyId}/tasks/service-areas। - कौशल —
/companies/{companyId}/skills। - कर्मचारी —
/companies/{companyId}/employees: जोड़ना, संपादित करना, बर्खास्त करना और पुनर्स्थापित करना। - इन्वेंटरी — वस्तुएँ, श्रेणियाँ, सेट और गोदामों में शेष।
- इनवॉइसिंग — अनुमान, कार्य आदेश, चालान, रसीदें, दस्तावेज़ों के काउंटर और लोगो।
- रिपोर्ट्स — काम और उपस्थिति के डेटा का निर्यात।
इसके अलावा, शेड्यूल और शिफ्ट, छुट्टियाँ और अवकाश के अनुरोध, उपस्थिति, बिलिंग और SMS बिलिंग, सूचनाएँ और मॉड्यूल भी उपलब्ध हैं।
वेबहुक्स
यदि API को नियमित अनुरोध भेजने के बजाय आपको घटनाएँ उनके होते ही प्राप्त करनी हैं, तो वेबहुक्स का उपयोग करें — Developer अनुभाग में Webhooks टैब। ज़रूरी घटना होने पर Shifton स्वयं आपके पते पर अनुरोध भेज देगा; समर्थित घटनाओं की सूची एक अलग मेथड लौटाता है।
त्रुटि कोड
Shifton का API मानक HTTP स्थिति कोड का उपयोग करता है:
- 200 — अनुरोध सफलतापूर्वक पूरा हुआ।
- 201 — ऑब्जेक्ट सफलतापूर्वक बनाया गया।
- 400 — अनुरोध के पैरामीटर गलत हैं।
- 401 — प्राधिकरण की त्रुटि: कुंजी भेजी नहीं गई, अवैध है या रद्द कर दी गई है।
- 403 — पहुँच निषिद्ध है।
- 404 — संसाधन नहीं मिला (आमतौर पर मेथड के पते में टाइपो)।
- 500 — सर्वर की त्रुटि।
उपयोग के सुझाव
- नई इंटीग्रेशनों के लिए नई दस्तावेज़ीकरण का उपयोग करें — पुरानी उन इंटीग्रेशनों के लिए छोड़ी गई है, जो पहले से काम कर रही हैं।
- अनुरोधों की जाँच के लिए Postman या curl सुविधाजनक हैं — वे कोड की एक भी पंक्ति लिखे बिना जवाब देखने देते हैं।
- कुंजी को कोड में खुले रूप में न रखें और उसे तीसरे पक्ष को न दें: कुंजी कंपनी के डेटा तक पहुँच देती है।
- अनुरोधों की आवृत्ति की सीमाओं (rate limits) का पालन करें — उन्हें पार करने पर API तक पहुँच अस्थायी रूप से अवरुद्ध हो सकती है।
अक्सर पूछे जाने वाले प्रश्न
प्रश्न: API कुंजी कहाँ से लें? उत्तर: ऐप्लिकेशन में: Developer अनुभाग → API कुंजियाँ टैब → “API कुंजी बनाएं” बटन। कुंजी वर्तमान कंपनी के लिए जारी की जाती है।
प्रश्न: मैंने विंडो बंद कर दी और कुंजी कॉपी नहीं की। उसे कहाँ देखूँ? उत्तर: कहीं नहीं — कुंजी केवल एक बार दिखाई जाती है और दोबारा जारी नहीं होती। नई कुंजी बनाएँ और पुरानी को रद्द कर दें।
प्रश्न: कुंजी गलत हाथों में पड़ जाए, तो उसे कैसे रद्द करें? उत्तर: उसे API कुंजियाँ टैब पर हटा दें। रद्द करना तुरंत लागू होता है: इस कुंजी के साथ आने वाले सभी अनुरोध तुरंत 401 लौटाने लगेंगे।
प्रश्न: “Full access” और “Restricted permissions” में क्या अंतर है? उत्तर: Full access (act as me) कुंजी को वही अधिकार देता है, जो आपके पास हैं। प्रतिबंधित अनुमतियाँ आपको कुंजी को केवल चुनी हुई अनुमतियों का सेट देने की सुविधा देता है — जिस इंटीग्रेशन को डेटा के केवल एक हिस्से तक पहुँच चाहिए, उसके लिए यह अधिक सुरक्षित है।
प्रश्न: क्या कुंजी की वैधता अवधि सीमित की जा सकती है? उत्तर: हाँ, बनाते समय समाप्त होता है फ़ील्ड। उसे न भरें, तो कुंजी असीमित अवधि के लिए रहेगी।
प्रश्न: क्या एक ही कुंजी कई कंपनियों के लिए काम करती है? उत्तर: नहीं। कुंजी उस कंपनी से जुड़ी होती है, जिसमें वह बनाई गई है, और केवल उसी के डेटा के साथ काम करती है। दूसरी कंपनी के लिए अलग कुंजी बनाएँ।
प्रश्न: API का बेस पता क्या है? उत्तर: https://api2.shifton.com/work/1.0.0। इसके बाद मेथड का पथ आता है, उदाहरण के लिए /companies/{companyId}/tasks।
प्रश्न: अनुरोधों के लिए कंपनी का ID कहाँ से लें? उत्तर: वह ऐप्लिकेशन के अड्रेस बार में /c/ के तुरंत बाद है — उदाहरण के लिए, app.shifton.com/c/8397/tasks में कंपनी का पहचानकर्ता 8397 है।
प्रश्न: दस्तावेज़ीकरण के किस संस्करण का उपयोग करें? उत्तर: नई इंटीग्रेशनों के लिए — नई (api2.shifton.com/openapi)। पुरानी (api2.shifton.com/docs) मौजूदा इंटीग्रेशनों के लिए समर्थित है।
प्रश्न: क्या रूसी भाषा में दस्तावेज़ीकरण है? उत्तर: हाँ। नई दस्तावेज़ीकरण के पेज पर ऊपरी दाएँ कोने में EN / RU स्विच है।
प्रश्न: API के अनुरोधों की जाँच किससे करें? उत्तर: सबसे सुविधाजनक हैं Postman या curl — वे कोड लिखे बिना अनुरोध भेजने और जवाब देखने देते हैं।
प्रश्न: कुंजी कॉपी करने के बावजूद 401 क्यों आता है? उत्तर: जाँचें कि कुंजी Authorization हेडर में उसके पहले Bearer शब्द के साथ भेजी जा रही है, कुंजी रद्द नहीं हुई है और उसकी वैधता अवधि समाप्त नहीं हुई है।
प्रश्न: 404 क्यों आता है? उत्तर: आमतौर पर पता गड़बड़ होता है: बेस हिस्सा https://api2.shifton.com/work/1.0.0 होना चाहिए, और मेथड के पथ में — सही {companyId}।
प्रश्न: API के ज़रिए क्या-क्या स्वचालित किया जा सकता है? उत्तर: कार्य बनाना और बदलना, ग्राहकों और उनके पतों के साथ काम, चेकलिस्ट्स, सेवा क्षेत्र, कौशल, कर्मचारी, इन्वेंटरी, इनवॉइसिंग के दस्तावेज़ और रिपोर्ट्स का निर्यात, और साथ ही शेड्यूल, शिफ्ट और छुट्टियाँ।
प्रश्न: क्या API को बार-बार पूछने के बजाय Shifton से घटनाएँ प्राप्त की जा सकती हैं? उत्तर: हाँ, इसके लिए वेबहुक्स हैं — Developer अनुभाग में Webhooks टैब।
प्रश्न: क्या पासवर्ड बदलने से इंटीग्रेशन के काम पर असर पड़ता है? उत्तर: नहीं। इंटीग्रेशन API कुंजी से काम करते हैं, अकाउंट के पासवर्ड से नहीं।