बाहरी सेवाओं के साथ एकीकरण करते समय त्रुटियों को कैसे कम करें: एक ऑनलाइन ब्रोकर का अनुभव

डेढ़ साल के लिए, हमने बीस बाहरी सेवाओं के साथ एपीआई को एकीकृत किया। पहले पांच एकीकरण दर्द और आँसू से गुजरे - हमने सभी संभव गलतियाँ कीं। उन्होंने कई बार कोड को फिर से लिखा, रिलीज से ठीक पहले भागीदारों के साथ साझेदारी की, क्योंकि वे सुधारों पर सहमत नहीं हो सकते थे। समय और पैसा खोया।

लेकिन प्रत्येक नए एकीकरण के साथ, हम आवर्ती समस्याओं के समाधान के साथ आए। परिणामस्वरूप, हमने पिछले एकीकरण को पहले की तुलना में चार गुना तेज कर दिया। अब हम अलग क्या करते हैं - लेख पढ़ें।

हमारे एकीकरण की बारीकियों को बेहतर ढंग से समझने के लिए, हम संक्षेप में बताएंगे कि हम क्या करते हैं। हम एक ऑनलाइन ब्रोकर विकसित कर रहे हैं। कार्य का सिद्धांत: उपयोगकर्ता साइट पर आता है, प्रश्नावली भरता है, हम इसे माइक्रोफाइनांस संगठनों (एमएफआई) में स्थानांतरित करते हैं और ऋण के लिए उनसे अनुमोदन या इनकार प्राप्त करते हैं। उपयोगकर्ता एक उपयुक्त प्रस्ताव का चयन करता है और धन प्राप्त करता है। इस काम को ऑनलाइन करने के लिए, हम एपीआई के माध्यम से एमएफआई के साथ एकीकृत करते हैं।

एक चेकलिस्ट और विनिर्देशन का उपयोग करके एकीकरण के लिए साथी की तत्परता का आकलन करें

हम दो परिदृश्यों का विश्लेषण करेंगे: जब एक संभावित साझेदार के पास पहले से ही आवेदनों को स्वीकार करने के लिए एपीआई है, और जब नहीं। दोनों परिदृश्यों से पता चलता है कि भागीदार हमारे साथ एकीकृत करना चाहता है और इस पर समय बिताने के लिए तैयार है।

भागीदार के पास कोई API नहीं है - हम विनिर्देश भेजते हैं

पहले, हमने साझेदार को मौखिक रूप से या पत्राचार में समझाया, कि हमें एकीकरण के लिए क्या चाहिए, और इन स्पष्टीकरणों के आधार पर साथी ने फिन्सपिन के साथ आवेदन स्वीकार करने के लिए एपीआई बनाया। हम मॉडल, ऑब्जेक्ट, प्रश्नावली के क्षेत्र और उनकी मान्यता के नियमों की आवश्यकताओं पर सहमत नहीं थे। जल्दी से तरीकों और संभव जवाब के उद्देश्य का वर्णन किया। परिणाम उम्मीद से बहुत कम निकला, क्योंकि एपीआई के बारे में हमारी समझ साझेदारी से बहुत अलग थी। मुझे सब कुछ फिर से करना पड़ा।

अब । हमने अपने विनिर्देश लिखे - एक YAML फ़ाइल जिसे स्वैगर में खोला जा सकता है। विनिर्देश में, हमने एमएफआई के साथ फिन्सपिन को एकीकृत करने के लिए सबसे उपयुक्त एपीआई का वर्णन किया: जवाब, विधि के नाम, संभावित त्रुटियों और स्थितियों के साथ उनके सत्यापन, स्वरूपों और अनुरोधों के प्रकारों के लिए प्रश्नावली क्षेत्र और नियम। हमने उस एप्लिकेशन की स्थिति की स्थिति दर्ज की जिसे हम प्राप्त करने की योजना बनाते हैं, उदाहरण के लिए: "प्रसंस्करण के लिए स्वीकार किया गया", "प्रगति में स्कोरिंग", "अस्वीकृत ऋण", "अनुमोदन", आदि।

हम साथी को विनिर्देश भेजते हैं, और वह तय करता है कि क्या वह इस तरह की एपीआई प्रदान कर सकता है। यदि यह नहीं कर सकता है, तो विनिर्देश में समस्याग्रस्त बिंदुओं को नोट करता है, उदाहरण के लिए, सभी अनुप्रयोग राज्य एपीआई में स्थानांतरित होने के लिए तैयार नहीं हैं या प्रश्नावली में पर्याप्त क्षेत्र नहीं हैं। और हम पहले से ही विशिष्ट बिंदुओं पर चर्चा कर रहे हैं, अमूर्त संस्थाओं से नहीं। साथी अपना दस्तावेज लिखने में समय बर्बाद नहीं करता है, लेकिन हमारा समायोजन करता है।

हमने विनिर्देशन बनाने में दो दिन बिताए, लेकिन अब हम एपीआई पर अनुमोदन और सुधार पर दसियों घंटे बचा रहे हैं। इसके अलावा, विनिर्देशों की मदद से, हम उन भागीदारों को जल्दी से फ़िल्टर करते हैं जो एकीकरण के लिए तैयार नहीं हैं। शुरुआती चरणों में, यह स्पष्ट हो जाता है कि हमारी ऑनलाइन आवेदन प्रसंस्करण प्रक्रियाएं बहुत अलग हैं: यह एकीकृत करने के लिए लाभहीन है।

भागीदार के पास एक एपीआई है - चेकलिस्ट के माध्यम से चलाएं

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

अब । हमने एपीआई और इसके द्वारा कार्य करने वाली प्रक्रियाओं का मूल्यांकन करने के लिए एक चेकलिस्ट लिखी है। चेकलिस्ट ने उन सवालों को एकत्र किया जिनका उत्तर दिया जाना चाहिए। सबसे पहले, हमारे प्रबंधक विनिर्देश में उत्तरों की तलाश करते हैं। यदि नहीं मिला है, तो भागीदार को प्रश्न संबोधित करता है।

चेकलिस्ट आपको विकास शुरू करने से पहले अड़चनें खोजने में मदद करती है, और इसके बाद नहीं - जब आपको कोड को संपादित करना होगा और ग्राहक खराब सेवा से पीड़ित होंगे।

जब हम नई स्थितियों का सामना कर रहे होते हैं तो हम लगातार चेक लिस्ट को बदलते रहते हैं। चेकलिस्ट जितना विस्तृत होगा, विकास में त्रुटियों को कम करने का जोखिम कम होगा।


एपीआई चेकलिस्ट टुकड़ा

शब्दों की शब्दावली

पहले, यह हमें लगता था कि ऑनलाइन ऋण देने के क्षेत्र में हर कोई पेशेवर शब्दों को उसी तरह से समझता है, इसमें कोई विसंगतियां नहीं हो सकती हैं। अभ्यास से पता चला है कि हम गलत थे।

उदाहरण के लिए, एक एमएफआई के साथ, हमने प्राथमिक और दोहराने वाले ग्राहकों की अलग-अलग व्याख्या की। हमारे लिए, प्राथमिक ग्राहक वह ग्राहक होता है, जिसकी प्रोफ़ाइल पहले FFI के माध्यम से MFI डेटाबेस में प्रवेश करती थी, और दोहराने वाला ग्राहक पहले से ही डेटाबेस में था। जारी किए गए ऋणों की संख्या से भागीदार ने ग्राहकों को दोहराए जाने पर विचार किया: दोहराने से दो ऋण प्राप्त हुए और तीसरे के लिए आए। इस तरह के पारिभाषिक भ्रम से वित्तीय सुलह में विसंगतियां हो सकती हैं।

अब हम शर्तों की एक छोटी शब्दावली का उपयोग करते हैं जिसके द्वारा हम भागीदारों के साथ जाँच करते हैं। एक नियम के रूप में, यह एकीकरण के बारे में विचारों को सिंक्रनाइज़ करने और सहयोग के लिए संभावनाओं का आकलन करने के लिए पांच या छह बुनियादी शर्तों को स्पष्ट करने के लिए पर्याप्त है।

एक बार शब्दावली में मदद करने के बाद हमें प्रतिकूल एकीकरण से बचने में मदद मिली है। "अनुमोदन" की हमारी व्याख्या संबद्ध से बहुत अलग थी। भागीदार के "अनुमोदन" में कई अलग-अलग पहलू शामिल थे जिन्हें मैनुअल प्रसंस्करण की आवश्यकता थी। हम अधिकतम स्वचालन के लिए प्रयास करते हैं, इसलिए हमने तुरंत सहयोग करने से इनकार कर दिया।


"स्वीकृति" शब्द को स्पष्ट करें

पहले व्यवसाय, फिर विकास

ऐसे मामले होते थे जब हम एक संभावित साझेदार के साथ विनिर्देशन के साथ काम करना शुरू करते थे। हमारे प्रबंधक ने विनिर्देश प्राप्त किया, इसे ध्यान से अध्ययन किया, साथी के साथ एकीकरण के लिए निर्दिष्ट विवरण, डेवलपर्स के साथ विवादित मुद्दों पर चर्चा की। और फिर नेतृत्व से एक संदेश आया: "अंत, एकीकरण रद्द हो गया है, हम शर्तों पर सहमत नहीं हुए।" कर्मचारियों का समय बर्बाद हुआ।


जब आप अपना दिमाग बदलते हैं, और काम पूरा हो जाता है

अब लोहे का नियम प्रभाव में है: प्रबंधक विनिर्देश का अध्ययन करना शुरू करता है जब उसे प्रबंधन से एकीकरण के बारे में स्पष्ट निर्णय प्राप्त होता है।

एकीकरण के लिए तत्परता: यूआरएल, विवरण, पर्यावरण

इससे पहले, पार्टनर API की पहली कॉल हमारे एप्लिकेशन के परीक्षण के दौरान देव सर्वर से हुई थी। अक्सर पहले अनुरोधों को कनेक्शन सेटअप चरण में त्रुटियां मिलीं: सर्वर से कनेक्ट नहीं हो सकता है या केवल एक टाइमआउट हो सकता है। सबसे लोकप्रिय कारण:

• गलत विधि नाम (सील या भ्रमित)
• अमान्य डोमेन
• गलत कनेक्शन विवरण,
• हमने अपने सर्वर के IP को श्वेत सूची में नहीं जोड़ा।

ऐसी छोटी त्रुटियों को ठीक करने में घंटों लग गए, क्योंकि वे एक के बाद एक चले गए: जब तक आप एक को ठीक नहीं करते, तब तक आप अगले नहीं देखेंगे।

अब , विकास योजना में कार्य करने से पहले, हम एक छोटी सी चेकलिस्ट के साथ एपीआई तक पहुँचने की सभी विशेषताओं को स्पष्ट करते हैं। चेकलिस्ट उन बिंदुओं को सूचीबद्ध करती है जिन्हें स्पष्ट करने की आवश्यकता है, उदाहरण के लिए:

• सेवा पर लोड पर प्रतिबंध,
• प्रति यूनिट समय अनुरोधों की संख्या
• कनेक्शन विवरण
• श्वेत सूची आईपी पते से,
• एसएसएल प्रमाणपत्र सत्यापन
• यातायात एन्क्रिप्शन आवश्यकताओं,
• अनुरोधों में विशेष हेडर
• एपीआई के साथ एक परीक्षण सर्वर की उपस्थिति या मुकाबला सर्वर को परीक्षण अनुरोध भेजने की क्षमता

यदि कोई परीक्षण एपीआई है, तो हम निश्चित रूप से पता लगाएंगे कि युद्ध सर्वर और परीक्षण एक को एक्सेस करते समय क्या अंतर है। जब हम अपने आवेदन से भागीदारों के लिए देव और उत्पादों के वातावरण में अनुरोधों को ध्यान में रखते हैं। इस तरह के उपाय हमें यह समझने में मदद करते हैं कि क्या सिस्टम हमारी जरूरतों के लिए तैयार है या अतिरिक्त समायोजन की आवश्यकता है या नहीं।

एपीआई के लिए मैन्युअल रूप से अनुरोध भेज रहा है

इससे पहले, हमने तुरंत भागीदार के विनिर्देश के अनुसार कोड लिखा, विनिर्देशों को संशोधित किया, संशोधित किया, परीक्षण किया। और एकीकरण परीक्षणों के चरण में, यह पता चला कि विनिर्देश में लिखी गई सब कुछ वास्तविकता से मेल नहीं खाती है - अनुरोधों के प्रारूप से शुरू होकर, आवेदन पारित करने की प्रक्रिया के साथ समाप्त होता है।

उदाहरण के लिए, कल्पना के अनुसार, जब एक निश्चित विधि तक पहुंच होती है, तो हम प्रतिक्रिया में एक निश्चित प्रारूप में प्रतिक्रिया की अपेक्षा करते हैं, प्राप्त प्रतिक्रिया की वैधता के लिए प्रसंस्करण को लटकाते हैं, परीक्षणों में जाते हैं, और अचानक हमें प्रतिक्रिया में एक सरणी मिलती है। हम साथी के डेवलपर्स से कारणों का पता लगाते हैं। वे पुराने प्रलेखन का उल्लेख करते हैं। फिर से, सुधारों, समीक्षाओं और परीक्षणों का एक चक्र।

अब , जैसे ही हम प्रलेखन और कनेक्शन विवरण प्राप्त करते हैं, हम एपीआई क्लाइंट के माध्यम से प्रक्रिया चलाते हैं। आमतौर पर, परीक्षक पोस्टमैन को विनिर्देश अपलोड करता है और ऋण आवेदन भेजने की पूरी व्यावसायिक प्रक्रिया का अनुकरण करता है, अनुरोध के लिए अलग-अलग डेटा सेट के साथ सबसे लोकप्रिय मामलों की जांच करता है। यही है, मैन्युअल रूप से करता है कि फिर आवेदन क्या करेगा।

मैनुअल रन के चरण में, प्रलेखन में 80% अशुद्धियां सामने आती हैं। हम त्रुटियों का वर्णन करते हैं और साथी को देते हैं। पार्टनर या तो घर में गलतियां निकालता है, या स्पेसिफिकेशन को अंतिम रूप देता है। नतीजतन, जब तक कोड पर काम शुरू होता है, तब तक डेवलपर्स काम के दस्तावेज प्राप्त करते हैं।

सबसे लोकप्रिय विसंगतियां:

• गलत अनुरोध प्रारूप, json को स्वीकार करने का वादा, यह फ़ॉर्म-डेटा की आवश्यकता के लिए निकला;
• अनुरोध में प्रेषित किए जाने वाले क्षेत्रों के नाम में त्रुटियां;
• क्षेत्र प्रारूपों में त्रुटियां;
• फ़ील्ड सत्यापन नियम निर्दिष्ट नहीं हैं या गलत तरीके से इंगित किए गए हैं;
• कुछ क्षेत्रों को पूरी तरह से भुलाया जा सकता है;
• विधि के प्रतिक्रिया प्रारूप के वास्तविक विवरण से गायब या अलग;
• अनिवार्य फ़ील्ड के बारे में गलत निशान - "तारांकन" दिखाई दे सकता है जहाँ फ़ील्ड वास्तव में अनिवार्य नहीं है, और इसके विपरीत;
• अक्सर सभी राज्यों और स्थितियों का दस्तावेजीकरण नहीं किया जाता है जिसमें वस्तु हो सकती है;
• वस्तुओं की अपेक्षित और प्राप्त स्थितियों के बीच विसंगतियां। उदाहरण के लिए, किसी बिंदु पर, हम उम्मीद करते हैं कि आवेदन राज्य में होना चाहिए - और एपीआई द्वारा, वास्तव में, हमें वाई मिलता है।

खुशी के लिए नुस्खा: एपीआई एकीकरण गलतियों से बचना

अपनी सेवा के साथ एकीकरण के लिए एक विनिर्देश लिखें। हमने YAML में विनिर्देशन को विकसित करने में दो दिन बिताए, लेकिन अब हम सुधार और अनुमोदन पर दसियों घंटे बचा रहे हैं।

यदि भागीदार अपने विनिर्देश भेजता है, तो इसे चेक सूची पर जांचें। चेकलिस्ट में, उन प्रश्नों को एकत्र करें, जिनके उत्तर आपको प्राप्त करने होंगे। अनुभव और स्मृति पर भरोसा मत करो, अभी भी कुछ याद आती है।

अपने साथी के साथ मनमुटाव से बचने के लिए शब्दावली का प्रयोग करें। हमारे अनुभव से पता चला है कि अंतर स्पष्ट शब्दों में भी हो सकता है।

जब तक आप भागीदार के साथ एकीकरण के प्रबंधन से राजसी अनुमोदन प्राप्त नहीं करते तब तक कार्य को विकास में न लें। विचार स्पष्ट है, लेकिन यह हमें अनावश्यक काम से बचने में मदद करता है।

भागीदार के एपीआई तक पहुंचने की बारीकियों को स्पष्ट करने के लिए एक चेकलिस्ट खोलें: कनेक्शन विवरण, श्वेत सूची, एसएसएल प्रमाणपत्र सत्यापन, ट्रैफिक एन्क्रिप्शन आवश्यकताओं आदि। अंतिम चरणों में फिसलन से बचने के लिए जितनी जल्दी हो सके चेकलिस्ट की जांच करें।

एक विनिर्देश मिला - तुरंत कोड लिखने के लिए जल्दी मत करो। सबसे पहले, मैन्युअल रूप से एक एपीआई क्लाइंट के माध्यम से प्रक्रिया चलाते हैं, उदाहरण के लिए, पोस्टमैन के माध्यम से। इसलिए आपको प्रारंभिक अवस्था में और छोटे संसाधनों के साथ विनिर्देशन में त्रुटियाँ मिलेंगी। और वे होंगे।