लेखा-कर API के लिए प्री-प्रोडक्शन टेस्ट प्लान

लेखा-कर (accounting) API से मिलने वाला 201 Created रिस्पॉन्स आपको लगभग कुछ नहीं बताता। यह केवल यह पुष्टि करता है कि सर्वर ने जवाब दिया है। यह इस बात की पुष्टि नहीं करता कि ठीक एक चालान (invoice) मौजूद है, डेबिट क्रेडिट के बराबर हैं, डॉक्यूमेंट नंबर केवल एक बार आवंटित किया गया था, या कनेक्शन टूटने के बाद किया गया रीट्राय (retry) दूसरी प्रति बुक नहीं करेगा। उत्पादन (production) में होने वाली अधिकांश लेखा-कर डुप्लीकेशन इसी अंतराल से आती हैं: एक म्यूटेशन (mutation) जो सर्वर पर कमिट हो गया, जबकि क्लाइंट को परिणाम का पता नहीं था और उसने चुपचाप एक नई कुंजी (key) के साथ रीट्राय कर दिया।

यह प्लान उन टीमों के लिए है जो किसी लेखा-कर API को वास्तविक बही-खातों (books) से जोड़ने से पहले उसका मूल्यांकन कर रही हैं। यह सुखद परिदृश्यों (happy paths) के बजाय विफलता के व्यवहार पर केंद्रित है। नीचे दिया गया प्रत्येक क्षेत्र बताता है कि क्या टेस्ट करना है, क्या एज़र्ट (assert) करना है, और क्या पास माना जाएगा। यहाँ कार्यान्वयन संदर्भ Nordlet है, जिसकी API में स्कोप्ड बीयरर कुंजियों, डेसिमल-स्ट्रिंग राशियों, आइडपोटेंसी कुंजियों (idempotency keys) और हस्ताक्षरित वेबहुक (signed webhooks) का उपयोग किया जाता है। सटीक एंडपॉइंट सिंटैक्स और रिस्पॉन्स कॉन्ट्रैक्ट के लिए, मान्यताओं पर भरोसा करने के बजाय API conventions और Getting started पृष्ठों को पढ़ें।

"पास होने" का वास्तविक अर्थ क्या है

एक टेस्ट यह साबित तभी करता है कि लेखा-कर एकीकरण (integration) सुरक्षित है, जब वह स्टेटस कोड के बजाय सिमेंटिक्स (semantics) का सत्यापन करता है। प्रत्येक परिदृश्य के लिए, सुइट को यह पुष्टि करनी चाहिए:

• व्यापारिक दुष्प्रभाव (business side effect): ठीक एक ग्राहक, चालान, जर्नल प्रविष्टि, नंबर आवंटन, या भुगतान संक्रमण मौजूद है।
• लेखा-कर अखंडता (accounting integrity): डेबिट क्रेडिट के बराबर हैं, और मौद्रिक सटीकता (monetary precision) सीरियलाइजेशन के बाद भी बनी रहती है।
• रीप्ले व्यवहार (replay behavior): रीट्राय करने पर नए रिकॉर्ड के बजाय मूल परिणाम ही वापस मिलता है।
• स्थायित्व (durability): ऑपरेशन कमिट होने के बाद ऑडिट रिकॉर्ड और वेबहुक इवेंट मौजूद होते हैं।
• बिना दुष्प्रभाव वाली विफलताएँ: अस्वीकृत अनुरोध कोई डॉक्यूमेंट नंबर नहीं लेते और कोई आंशिक लेज़र लाइन नहीं लिखते।
• रिकवरी (recovery): बिना डुप्लीकेशन या स्थायी नुकसान के किसी क्षणिक त्रुटि (transient error) को रीट्राय किया जा सकता है।

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

एक डिस्पोजेबल और ऑब्ज़र्वेबल वातावरण सेट अप करें

प्रोडक्शन की किताबों का नहीं, बल्कि एक सैंडबॉक्स कंपनी का उपयोग करें। Nordlet सैंडबॉक्स कंपनी वास्तविक कंपनी की तरह ही मॉड्यूल और API व्यवहार का उपयोग करती है और इसे टेस्ट डेटा के रूप में चिह्नित किया जाता है, जो इसे उच्च-मात्रा वाले डुप्लीकेट और विफलता परीक्षणों के लिए सुरक्षित बनाता है। निर्माण के बाद यह फ्लैग इम्यूटेबल (immutable) होता है, इसलिए वास्तविक बही-खातों को बाद में टेस्ट डेटा के रूप में पुनर्वर्गीकृत नहीं किया जा सकता है। ध्यान दें कि सैंडबॉक्स का उपयोग किसी वास्तविक कंपनी के उपयोग की तरह ही मापा (metered) और बिल किया जाता है, इसलिए अपने वॉल्यूम टेस्ट को अपनी मूल्य निर्धारण (pricing) योजना के अनुसार मापें।

कोई भी टेस्ट लिखने से पहले, निम्नलिखित तैयार करें:

• isSandbox: true के साथ एक समर्पित सैंडबॉक्स कंपनी।
• केवल परीक्षण किए जा रहे मॉड्यूल तक सीमित एक टेस्ट API कुंजी।
• एक वेबहुक एंडपॉइंट या लोकल टनल जो रॉ अनुरोध बॉडी को सुरक्षित रखता है।
• सीड किए गए ग्राहक, आपूर्तिकर्ता (suppliers), और खातों का एक ज्ञात चार्ट (chart of accounts)।
• कम से कम दो लेखा-कर अवधि (accounting periods): एक खुली, एक बंद (locked)।
• यदि कार्यान्वयन समर्थन करता है तो एक टेस्ट क्लॉक या डेट फिक्स्चर।
• एक स्थानीय स्टोर जो हर अनुरोध के प्रयास, आइडपोटेंसी कुंजी, रिस्पॉन्स हैश, वेबहुक डिलीवरी और रिकंसीडिएशन परिणाम को रिकॉर्ड करता है।

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

म्यूटेशन के लिए आपका फिक्स्चर मेथड, एंडपॉइंट, पूर्ण बॉडी, आइडपोटेंसी कुंजी, कुंजी स्कोप, क्लाइंट सहसंबंध आईडी (correlation ID), प्रारंभ और समाप्ति टाइमस्टैम्प, रिस्पॉन्स स्टेटस, हेडर, बॉडी, अनुरोध आईडी को कैप्चर करना चाहिए, और यह भी कि रिस्पॉन्स आने से पहले कनेक्शन गिरा था या नहीं। पैसों के लिए "75.0000" जैसी निश्चित दशमलव स्ट्रिंग्स का उपयोग करें। Nordlet मौद्रिक मूल्यों को अधिकतम चार दशमलव स्थानों के साथ दशमलव स्ट्रिंग्स के रूप में प्रदर्शित करता है, और इसका उदाहरण चालान इसी रूप का उपयोग करता है।

सेटअप का दूसरा हिस्सा फेल्योर इंजेक्शन है। आपके हार्नेस में किसी रिस्पॉन्स में देरी करने, सर्वर द्वारा अनुरोध प्राप्त करने के बाद TCP कनेक्शन गिराने, सिंथेटिक 429/500/502/503/504 रिस्पॉन्स लौटाने, वेबहुक रिसीवर से नॉन-2xx लौटाने, एक ही वेबहुक को दो बार डिलीवर करने, इवेंट्स को रीऑर्डर करने, वेबहुक बॉडी के एक बाइट को भ्रष्ट करने, कुंजी को रखते हुए आइडपोटेंसी-कुंजी पेलोड को बदलने, दो समान अनुरोधों को समवर्ती (concurrently) रूप से चलाने, और सेटअप तथा पोस्टिंग के बीच एक अवधि को लॉक करने की क्षमता होनी चाहिए। ये परिदृश्य सौ सुखद-परिदृश्य (happy-path) उदाहरणों से अधिक मूल्यवान हैं।

रीट्राय लॉजिक लिखने से पहले कॉन्ट्रैक्ट को लॉक करें

OpenAPI स्कीमा को जनरेट या फ़ेच करें और अपने क्लाइंट के मुकाबले इसकी तुलना करें। Nordlet अपने OpenAPI स्पेक को API reference में प्रकाशित करता है और उसी स्पेक से अपने टाइप किए गए SDK जनरेट करता है, इसलिए स्कीमा-संचालित टेस्ट हाथ से लिखे गए अनुमानों से बेहतर होते हैं।

आवश्यक फ़ील्ड और प्रकार, दशमलव-स्ट्रिंग फ़ील्ड, दिनांक और टाइमस्टैम्प प्रारूप, स्वीकृत क्रियाएं और स्कोप, त्रुटि लिफाफे का आकार, वेबहुक इवेंट स्कीमा, कौन से म्यूटेशन आइडपोटेंसी कुंजी स्वीकार करते हैं, और कौन से रिस्पॉन्स फ़ील्ड बनाए गए ऑब्जेक्ट की पहचान करते हैं, इनका सत्यापन करें।

पास मानदंड (Pass criteria)। क्लाइंट स्थानीय स्तर पर अमान्य पेलोड को अस्वीकार करता है जहाँ स्कीमा अनुमति देता है। सर्वर के रिस्पॉन्स प्रलेखित स्कीमा से मेल खाते हैं। अमान्य दशमलव, खराब तारीखें और गायब आवश्यक फ़ील्ड संरचित सत्यापन त्रुटियाँ उत्पन्न करते हैं। किसी नियतकालिक सत्यापन विफलता के लिए कोई रीट्राय का प्रयास नहीं किया जाता है।

पकड़ने योग्य विफलता मोड। कोई क्लाइंट "121.0000" को बाइनरी फ़्लोट में पार्स करता है और बाद में थोड़ा अलग राशि सीरियलाइज़ करता है। पूर्ण संख्याएँ पास हो जाती हैं; VAT लाइनें और आंशिक मात्राएँ विफल हो जाती हैं। अंत से अंत तक पैसों (money) का परीक्षण स्ट्रिंग के रूप में करें।

प्राधिकरण और टेनेंट आइसोलेशन

पढ़ने (read) और लिखने (write) के लिए अलग-अलग कुंजियों का उपयोग करें। फिर पूर्ण ग्रिड का परीक्षण करें: गायब कुंजी, अमान्य कुंजी, अपर्याप्त मॉड्यूल स्कोप के साथ वैध कुंजी, सही स्कोप के साथ वैध कुंजी, किसी अन्य कंपनी से संबंधित कुंजी, और किसी भिन्न कंपनी से किसी ऑब्जेक्ट को पढ़ने का प्रयास।

एज़र्शन:

• गायब या अमान्य क्रेडेंशियल 401 लौटाते हैं।
• आवश्यक अनुमति के बिना एक वैध कुंजी 403 लौटाती है।
• किसी भी विफलता के लिए कोई लेखा-कर दुष्प्रभाव नहीं बनाया जाता है।
• एक सफल अनुरोध किसी अन्य कंपनी के रिकॉर्ड को पढ़ या म्यूटेट नहीं कर सकता है।
• सुरक्षा विफलताओं को कभी भी स्वचालित रूप से रीट्राय नहीं किया जाता है।

पास मानदंड। आप टेस्ट के बाद के रीड्स के साथ प्राधिकरण शुद्धता और टेनेंट आइसोलेशन दोनों को साबित कर सकते हैं, न कि केवल स्टेटस कोड के साथ।

एक स्वच्छ ट्रांजेक्शन साबित करें

एक छोटा, नियतकालिक (deterministic) प्रवाह चलाएं: एक टेस्ट ग्राहक बनाएं या खोजें, दशमलव-स्ट्रिंग राशियों के साथ एक चालान बनाएं, इसे जारी करें, चालान और उसके लेखा-कर प्रभाव को पढ़ें, ऑडिट रिकॉर्ड पढ़ें, और वेबहुक प्राप्त करें। Nordlet का गेटिंग स्टार्टेड उदाहरण चालान जारी करने को अंतराल-मुक्त (gapless) संख्या आवंटित करते हुए, यह जांचते हुए दिखाता है कि अवधि खुली है, और एक ही ट्रांजेक्शन में संतुलित जर्नल प्रविष्टि पोस्ट करता है।

एज़र्ट करें कि चालान अपेक्षित स्थिति तक पहुँचता है, डॉक्यूमेंट नंबर ठीक एक बार आवंटित किया जाता है, डेबिट क्रेडिट के बराबर होते हैं, VAT और लाइन टोटल अपेक्षित हाफ़-अप गणना से मेल खाते हैं, ऑडिट रिकॉर्ड अभिनेता और परिवर्तन का नाम देता है, वेबहुक अंततः डिलीवर हो जाता है, और API रिस्पॉन्स तथा अनुवर्ती रीड चालान ID और स्थिति पर सहमत होते हैं।

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

आइडपोटेंसी: समान कुंजी, समान बॉडी

प्रत्येक तार्किक व्यावसायिक ऑपरेशन के लिए एक कुंजी जनरेट करें, न कि प्रति नेटवर्क प्रयास एक कुंजी। कुंजी K और बॉडी B के साथ म्यूटेशन भेजें, बनाई गई ID सहेजें, फिर से वही सटीक अनुरोध दोबारा भेजें।

एज़र्ट करें कि दूसरा रिस्पॉन्स उसी ऑपरेशन का प्रतिनिधित्व करता है, ऑब्जेक्ट ID समान है, और एक व्यावसायिक ऑब्जेक्ट, एक पोस्टिंग, एक डॉक्यूमेंट नंबर, एक वित्तीय प्रभाव मौजूद है। रीप्ले किए गए रिस्पॉन्स में प्रलेखित रीप्ले हेडर होना चाहिए - Nordlet के मामले में x-idempotent-replay: true - और ऑडिट ट्रेल में कोई दूसरा म्यूटेशन नहीं दिखना चाहिए।

दो स्टोरेज नियम बदलते हैं कि आपके रीट्राय लूप को क्या अपेक्षा रखनी चाहिए, इसलिए उनका सीधे परीक्षण करें: एक सहेजे गए 4xx को किसी अन्य रिस्पॉन्स की तरह ही रीप्ले किया जाता है, जबकि 5xx को बिल्कुल भी सहेजा नहीं जाता है, इसलिए सर्वर त्रुटि के बाद रीट्राय ऑपरेशन को रीप्ले करने के बजाय पुन: निष्पादित करता है। कुंजियाँ समाप्त भी हो जाती हैं, Nordlet में 24 घंटों के बाद, जो यह सीमित करता है कि रीप्ले कितने समय तक उपलब्ध है।

Nordlet का दस्तावेजीकरण वादा करता है कि Idempotency-Key हेडर जोड़ने से रीट्राय किया गया अनुरोध डुप्लीकेट बनाने से रोकता है, और इसके API कन्वेंशंस सटीक रीप्ले हेडर और बाइट-दर-बाइट रिस्पॉन्स आवश्यकता को परिभाषित करते हैं। सिद्धांत Stripe के प्रकाशित मॉडल से मेल खाता है: एक कुंजी तार्किक ऑपरेशन की पहचान करती है, पुनरावृत्ति सहेजा गया परिणाम लौटाती है, और विभिन्न मापदंडों के साथ पुन: उपयोग की जाने वाली कुंजी को चुपचाप बदलने के बजाय अस्वीकार कर दिया जाता है।

पास मानदंड। क्लाइंट रीप्ले विंडो के भीतर जितनी बार चाहें उतनी बार समान अनुरोध भेजे, कोई फर्क नहीं पड़ता, ठीक एक वित्तीय स्थिति संक्रमण मौजूद है।

आइडपोटेंसी: समान कुंजी, बदला हुआ बॉडी

कुंजी K और बॉडी B1 के साथ मूल अनुरोध भेजें, फिर कुंजी K और बॉडी B2 के साथ दूसरा अनुरोध भेजें जहाँ कम से कम एक राशि, ग्राहक, दिनांक या लाइन भिन्न हो।

अपेक्षित परिणाम: अनुरोध को प्रलेखित कुंजी-पुनः उपयोग त्रुटि के साथ अस्वीकार कर दिया जाता है - Nordlet 422 idempotency_key_reuse लौटाता है - मूल रिकॉर्ड अछूता रहता है, कोई दूसरा रिकॉर्ड या नंबर या ऑडिट म्यूटेशन प्रकट नहीं होता है, और क्लाइंट एक नई कुंजी जनरेट करके इसे "ठीक" नहीं करता है। B2 को चुपचाप स्वीकार करना रीट्राय कुंजियों को असुरक्षित बना देगा।

समवर्ती डुप्लीकेट अनुरोध (Concurrent duplicate requests)

एक ही समय में एक ही कुंजी के साथ दो समान अनुरोध फायर करें। प्रलेखित व्यवहार के आधार पर, एक निष्पादित होता है जबकि दूसरा प्रगति पर संघर्ष (in-progress conflict) प्राप्त करता है - Nordlet 409 idempotency_in_progress लौटाता है - या दोनों अंततः समान परिणाम देखते हैं।

एज़र्ट करें कि दोनों कॉल स्वतंत्र वित्तीय प्रभाव नहीं बना सकते हैं, अधिकतम एक डॉक्यूमेंट नंबर आवंटित किया जाता है, एक अस्थायी संघर्ष को नए के बजाय समान कुंजी के साथ रीट्राय किया जाता है, अंतिम संसाधन पूर्ण और पठनीय है, और आइडपोटेंसी रिकॉर्ड स्थायी रूप से अटका नहीं रहता है।

विफलता मोड (Failure mode)। एक रीट्राय लाइब्रेरी जो प्रत्येक प्रयास के लिए एक नया UUID बनाती है, वह एक तार्किक ऑपरेशन को कई स्वतंत्र राइट्स में बदल देती है और आइडपोटेंसी को पूरी तरह से विफल कर देती है।

कनेक्शन टूटने के बाद अनिश्चित परिणाम

यह एकल सबसे महत्वपूर्ण प्रोडक्शन सिमुलेशन है। कुंजी K के साथ एक म्यूटेशन भेजें, सर्वर को इसे कमिट करने दें, रिस्पॉन्स आने से पहले कनेक्शन गिरा दें, परिणाम को अज्ञात के रूप में रिकॉर्ड करें, फिर समान कुंजी K के साथ रीट्राय करें और संसाधन तथा ऑडिट डेटा को पढ़कर मिलान (reconcile) करें।

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

एक रूढ़िवादी रीट्राय नीति (Conservative retry policy)

रीट्राय के निर्णय त्रुटि और इस बात पर निर्भर करते हैं कि ऑपरेशन आइडपोटेंट है या नहीं, अकेले HTTP मेथड पर नहीं।

आमतौर पर रीट्राय करने योग्य, समान कुंजी बनाए रखी गई: आइडपोटेंट म्यूटेशन के बाद कनेक्शन रीसेट या टाइमआउट, 408, retry-after का सम्मान करने के बाद 429, और 502/503/504। एक प्रलेखित प्रगति पर आइडपोटेंसी रिस्पॉन्स को थोड़ी देरी के बाद रीट्राय किया जा सकता है।

रिकंसीडिएशन के बिना रीट्राय करने योग्य नहीं: 400/422 सत्यापन त्रुटियाँ, 401/403 प्रमाणीकरण विफलताएँ, गायब संसाधन के लिए 404, इन-फ्लाइट कुंजी से संबंधित नहीं होने वाले व्यावसायिक 409 संघर्ष, मौजूदा कुंजी पर बदला हुआ पेलोड, और पीरियड-लॉक अस्वीकृति।

जिटर के साथ सीमित घातीय बैकऑफ़ (bounded exponential backoff), स्पष्ट अधिकतम प्रयास और बीता हुआ समय, दर सीमाओं के लिए सम्मानित retry-after, एक ऑपरेशन के रीट्राय में रखी गई समान कुंजी, प्रत्येक नए ऑपरेशन के लिए एक नई कुंजी, और लॉग जो मूल प्रयास को रीट्राय से अलग करते हैं, इन्हें एज़र्ट करें।

दर सीमित करने (rate limiting) का अपने आप परीक्षण करें। प्रलेखित सीमा को पार करें - Nordlet डिफ़ॉल्ट रूप से प्रति API कुंजी प्रति मिनट 300 अनुरोधों की अनुमति देता है, और कुछ अप्रमाणित एंडपॉइंट अपनी स्वयं की निचली प्रति-पता सीमाएं रखते हैं - फिर पुष्टि करें कि सर्वर दर-सीमा रिस्पॉन्स लौटाता है, क्लाइंट त्रुटि के बजाय देरी के रूप में retry-after को पार्स करता है, यह हथौड़ा चलाने के बजाय रुक जाता है, और थ्रॉटल्ड म्यूटेशन रीट्राय मूल कुंजी का पुन: उपयोग करता है। x-ratelimit-* हेडर शेष बजट की रिपोर्ट करते हैं, जो एक अच्छा पूर्व-एज़र्शन (pre-assertion) बनाता है। दर-सीमा परीक्षणों को वित्तीय एज़र्शन से दूर रखें जब तक कि आपका फिक्स्चर थ्रॉटल्ड प्रयास को कमिट किए गए प्रयास से अलग न बता सके।

वेबहुक हस्ताक्षर सत्यापन (Webhook signature verification)

एक रिसीवर बनाएँ जो रॉ बाइट्स को सुरक्षित रखता है। प्रत्येक इवेंट के लिए: रॉ बॉडी को कैप्चर करें, x-nordlet-signature हेडर को पढ़ें, सब्सक्रिप्शन सीक्रेट के साथ अपेक्षित HMAC-SHA256 की गणना करें, कॉन्सटेंट-टाइम फ़ंक्शन का उपयोग करके तुलना करें, सत्यापन के बाद ही JSON को पार्स करें, डिलीवरी को रिकॉर्ड करें, और टिकाऊ स्वीकृति के बाद एक तेज़ 2xx लौटाएं। Nordlet रॉ बॉडी पर एक HMAC पर हस्ताक्षर करता है, इसे sha256=<hex> के रूप में भेजता है, और घातीय बैकऑफ़ के साथ डिलीवरी को रीट्राय करता है। Stripe का वेबहुक मार्गदर्शन निरंतर-समय की तुलना के साथ अपरिष्कृत रॉ बॉडी को सत्यापित करने पर जोर देता है।

नकारात्मक परीक्षण चलाएं: सही बॉडी और सीक्रेट, गलत सीक्रेट के साथ सही बॉडी, एक बाइट का बॉडी परिवर्तन, बदले हुए व्हाइटस्पेस के साथ पुन:-सीरियलाइज़्ड JSON, गायब हेडर, एक विकृत हस्ताक्षर (malformed signature), यदि योजना में टाइमस्टैम्प शामिल है तो एक रीप्ले किया गया पुराना डिलीवरी, और गलत सब्सक्रिप्शन पर वितरित एक वैध हस्ताक्षर।

पास मानदंड। केवल सही रॉ बॉडी और सीक्रेट स्वीकार किए जाते हैं। अमान्य हस्ताक्षरों को नॉन-2xx मिलता है। अमान्य पेलोड कभी भी लेखा-कर कतार में प्रवेश नहीं करते हैं। सीक्रेट साधारण लॉग से बाहर रहते हैं। हैंडलर केवल तभी स्वीकार करता है जब इवेंट को स्थायी रूप से रिकॉर्ड किया जाता है।

डुप्लीकेट और आउट-ऑफ-ऑर्डर वेबहुक

डिलीवरी की विश्वसनीयता API आइडपोटेंसी से एक अलग समस्या है, और रिसीवर को भी आइडपोटेंट होना चाहिए। एक ही इवेंट को दो बार डिलीवर करें, sale_invoice.issued इवेंट से पहले sale_invoice.paid इवेंट डिलीवर करें, बनाए रखने के बाद लेकिन रिस्पॉन्स देने से पहले 500 लौटाएं, और उपभोक्ता द्वारा पहले ही प्रोसेस किए गए इवेंट को रीप्ले करें।

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

एंडपॉइंट को पतला रखें: आकार को सत्यापित करें, हस्ताक्षर को सत्यापित करें, बनाए रखें या कतार में लगाएं, स्वीकार करें, 2xx लौटाएं। रिकंसीडिएशन और सूचनाएं एसिंक्रोनस प्रोसेसिंग से संबंधित हैं। डाउनस्ट्रीम कार्य को डिलीवरी टाइमआउट से आगे सुलाकर इसका परीक्षण करें; एक सही रिसीवर अभी भी टिकाऊ कतारबद्ध करने के बाद स्वीकार करता है।

खुली और बंद लेखा-कर अवधियाँ (Open and locked accounting periods)

Nordlet मैनुअल जर्नल्स, डॉक्यूमेंट प्रवाह और इम्पोर्ट्स में पोस्टिंग के समय पीरियड लॉक लागू करता है, इसलिए एक से अधिक स्थानों पर नियंत्रण का परीक्षण करें। खुली अवधि में, बंद अवधि में, लॉक से ठीक पहले की सीमा पर, अगली खुली अवधि के पहले दिन, और एक वैध डॉक्यूमेंट दिनांक लेकिन अमान्य पोस्टिंग दिनांक के साथ समतुल्य दस्तावेज़ बनाएं यदि API दोनों को अलग करता है।

बंद-अवधि के मामले के लिए, एज़र्ट करें कि अनुरोध को प्रलेखित पीरियड-लॉक त्रुटि - Nordlet में 409 conflict - के साथ अस्वीकार कर दिया जाता है और कोई जर्नल लाइनें नहीं लिखी जाती हैं, कोई डॉक्यूमेंट नंबर खपत नहीं होता है, कोई डॉक्यूमेंट पोस्टेड में परिवर्तित नहीं होता है, और कोई सफलता वेबहुक फायर नहीं होता है। खुले-अवधि का संस्करण समान वित्तीय मूल्यों के साथ सफल होना चाहिए।

रेस टेस्ट (Race test)। एक खुली अवधि के खिलाफ पोस्टिंग शुरू करें, अनुरोध के बीच में अवधि को लॉक करें, और पुष्टि करें कि कमिट लॉक को बायपास नहीं कर सकता है। महत्वपूर्ण पास स्थिति: एक कमिट किया गया पोस्टिंग कभी भी ऐसी अवधि में नहीं उतरता है जो ट्रांजेक्शन कमिट होने से पहले लॉक थी।

ऑडिटेबिलिटी और रिकंसीडिएशन

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

प्रत्येक अस्वीकृत म्यूटेशन के लिए, पुष्टि करें कि कोई आंशिक दस्तावेज़ मौजूद नहीं है, अनुबंध आरक्षण की अनुमति देने तक कोई नंबर उपभोग नहीं किया गया था, कोई लेज़र प्रविष्टि मौजूद नहीं है, कोई सफलता वेबहुक मौजूद नहीं है, और त्रुटि में निदान के लिए एक अनुरोध ID है। Nordlet के सम्मेलन म्यूटेशन ऑडिटेबिलिटी और संतुलित पोस्टिंग को प्लेटफ़ॉर्म गारंटी के रूप में वर्णित करते हैं, जिसमें एप्लिकेशन कोड के बजाय अकेले कमिट समय पर एक टालए गए डेटाबेस ट्रिगर द्वारा संतुलन लागू किया जाता है। HTTP रिस्पॉन्स पर भरोसा करने के बजाय उन गारंटियों को पोस्ट-टेस्ट रिकंसीडिएशन क्वेरी में बदलें।

कोर टेस्ट मैट्रिक्स

क्षेत्र	टेस्ट एक्शन	अपेक्षित एज़र्शन	पास मानदंड
प्रमाणीकरण (Authentication)	कोई कुंजी नहीं, अमान्य कुंजी, अपर्याप्त स्कोप	संरचित 401/403; कोई दुष्प्रभाव नहीं	सभी अस्वीकृत प्रयास कोई लेखा-कर रिकॉर्ड नहीं बनाते हैं
स्कीमा और पैसा	अमान्य दशमलव, दिनांक, आवश्यक फ़ील्ड	फ़ील्ड-स्तरीय सत्यापन त्रुटि	कोई रीट्राय या आंशिक राइट नहीं होता है
सामान्य पोस्टिंग	खुली अवधि में चालान बनाएं और जारी करें	एक दस्तावेज़, एक संतुलित जर्नल, एक ऑडिट रिकॉर्ड	रीड-बैक स्थिति और लेज़र सहमत हैं
समान-कुंजी रीप्ले	समान म्यूटेशन, समान कुंजी और बॉडी दोहराएं	मूल परिणाम रीप्ले किया गया; कोई डुप्लीकेट नहीं	ऑब्जेक्ट ID, नंबर, जर्नल प्रभाव, ऑडिट एकल रहते हैं
बदला हुआ बॉडी, समान कुंजी	अलग राशि के साथ कुंजी का पुन: उपयोग करें	प्रलेखित कुंजी-पुनः उपयोग अस्वीकृति	मूल रिकॉर्ड अछूता; कुछ भी नया नहीं लिखा गया
गिरा हुआ कनेक्शन	कमिट करें, गिराएं, समान कुंजी के साथ रीट्राय करें	रीप्ले किया गया परिणाम	ठीक एक वित्तीय दुष्प्रभाव
बंद अवधि (Locked period)	बंद अवधि में दिनांकित दस्तावेज़ पोस्ट करें	पीरियड-लॉक अस्वीकृति	कोई जर्नल, कोई नंबर, कोई सफलता वेबहुक नहीं
वेबहुक हस्ताक्षर	गलत सीक्रेट, बदला हुआ बॉडी	रिसीवर से नॉन-2xx	केवल सही रॉ बॉडी और सीक्रेट स्वीकार किए गए

मैं पहले क्या करूँगा

यदि समय कम है, तो उन परीक्षणों को उस क्रम में चलाएं जो सबसे महंगे बग को पकड़ते हैं। गिराए गए-कनेक्शन रीट्राय से शुरू करें, क्योंकि वह अकेला परिदृश्य अधिकांश वास्तविक डुप्लीकेट उत्पन्न करता है। फिर समान-कुंजी और बदले हुए-बॉडी आइडपोटेंसी जोड़े। फिर बंद अवधियाँ, क्योंकि बंद महीने में पोस्टिंग एक ऑडिट समस्या है जो देर से सामने आती है। हस्ताक्षर सत्यापन और आउट-ऑफ-ऑर्डर वेबहुक इसके बाद आते हैं, और क्लाइंट के स्थिर होने के बाद पूर्ण स्कीमा और प्राधिकरण ग्रिड CI में लगातार चल सकते हैं।

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

FAQ

क्या लेखा-कर राइट सफल होने की पुष्टि करने के लिए 2xx रिस्पॉन्स पर्याप्त है?

नहीं। एक स्टेटस कोड पुष्टि करता है कि सर्वर ने उत्तर दिया, यह नहीं कि ठीक एक दस्तावेज़, एक नंबर आवंटन और एक संतुलित जर्नल प्रविष्टि मौजूद है। प्रत्येक म्यूटेशन टेस्ट को ऑब्जेक्ट, उसके लेखा-कर प्रभाव और उसके ऑडिट रिकॉर्ड के रीड-बैक के साथ रिस्पॉन्स का पालन करना चाहिए। खतरनाक मामला विपरीत दिशा है: एक ऑपरेशन जो कमिट हो गया जबकि क्लाइंट को कभी भी रिस्पॉन्स मिला ही नहीं।

क्या अनुरोध का समय समाप्त होने पर मुझे एक नई आइडपोटेंसी कुंजी जनरेट करनी चाहिए?

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

यदि मैं किसी भिन्न पेलोड के साथ आइडपोटेंसी कुंजी का पुन: उपयोग करता हूँ तो क्या होता है?

एक सही API नए बॉडी को चुपचाप लागू करने के बजाय इसे अस्वीकार कर देता है। Nordlet 422 idempotency_key_reuse लौटाता है और मूल रिकॉर्ड को अछूता छोड़ देता है। आपके क्लाइंट को इसे ठीक करने के लिए एक प्रोग्रामिंग त्रुटि के रूप में मानना चाहिए, न कि एक नई कुंजी जनरेट करके काम करने की स्थिति के रूप में।

क्या वेबहुक बनाए गए ऑब्जेक्ट को वापस पढ़ने का विकल्प हैं?

नहीं। वेबहुक डिलीवरी डाउनस्ट्रीम सूचना साबित करती है, यह नहीं कि ट्रांजेक्शन उस तरह से कमिट हुआ जैसी आपको उम्मीद है, और डिलीवरी ऑर्डर की गारंटी नहीं है। रॉ बॉडी पर हस्ताक्षर को सत्यापित करें, डिलीवरी या इवेंट ID पर डिडुप्लीकेट करें, और जब भी केवल इवेंट ऑर्डर यह तय करने के लिए पर्याप्त न हो कि क्या बदला है, तो API से वर्तमान स्थिति प्राप्त करें।

मैं बंद लेखा-कर अवधि में पोस्टिंग का परीक्षण कैसे करूँ?

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

क्या मैं सैंडबॉक्स कंपनी में उच्च-वॉल्यूम डुप्लीकेट टेस्ट चला सकता हूँ?

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