मास कैंपेन लॉन्च से पहले API के ज़रिए बैलेंस की जाँच

क्यू लॉन्च करने से पहले बैलेंस क्यों पूछें

ताज़ा बैलेंस जाँच के बिना मास कैंपेन लॉन्च करने पर कुछ ऑर्डर फेल हो जाते हैं: शुरुआती ऑर्डर बन जाते हैं, लेकिन अगले ऑर्डर पैसे कम होने की गलती देते हैं। समानांतर भेजने, अलग-अलग सेवाओं और एक ही अकाउंट पर काम कर रहे कई प्रोसेस के साथ ऐसी स्थिति सँभालना सबसे मुश्किल होता है।

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

क्यू के बजट की तुलना अकाउंट की कुल राशि से नहीं, बल्कि उपलब्ध बैलेंस वाले फ़ील्ड से करें।

बैलेंस मेथड का रिस्पॉन्स कैसा दिखता है

फ़ील्ड के नाम किसी खास प्लेटफ़ॉर्म के डॉक्युमेंटेशन से तय होते हैं, लेकिन बैलेंस मेथड का सुविधाजनक कॉन्ट्रैक्ट आम तौर पर total, available, reserved, currency और updated_at लौटाता है। नीचे ढाँचे का एक उदाहरण है जिसे इंटीग्रेशन के दौरान मार्गदर्शक माना जा सकता है। यह हर सेवा के लिए एक जैसा रिस्पॉन्स नहीं, बल्कि डेटा के स्पष्ट ढाँचे का उदाहरण है।

अनुरोध ऐसा हो सकता है:

curl -X GET "https://api.example.com/v1/balance" \
-H "Authorization: Bearer API_TOKEN" \
-H "Accept: application/json"

रिस्पॉन्स:

{
"total": "125.80",
"available": "84.50",
"reserved": "41.30",
"currency": "USD",
"updated_at": "2025-01-15T10:42:18Z"
}

इस उदाहरण में total अकाउंट की सारी राशि है, available नए ऑर्डर के लिए पैसा है, reserved पहले बनाए गए ऑपरेशन के लिए राशि है। जाँच मिलती है: 125.80 में से 41.30 घटाने पर 84.50 बचता है। currency गणना की इकाई तय करता है, और updated_at यह समझने में मदद करता है कि डेटा कितना ताज़ा है।

available और reserved को कैसे समझें

available फ़ील्ड का इस्तेमाल लॉन्च का फ़ैसला लेने के लिए होता है। अगर क्यू की कीमत 80.00 है और available 84.50 है, तो पैसे सिर्फ़ तभी काफ़ी हैं जब API अलग कमीशन न जोड़े या ऑर्डर बनाते समय कीमत दोबारा न गिने। reserved को उपलब्ध बैलेंस में नहीं जोड़ा जाता: यह राशि पहले से ब्लॉक है।

reserved में processing, pending या review स्टेटस वाले ऑर्डर की कीमत शामिल हो सकती है — सटीक सेट प्लेटफ़ॉर्म के नियमों पर निर्भर करता है। कभी-कभी रिज़र्व रद्द होने, आंशिक पूरा होने या मैन्युअल जाँच के बाद खाली होता है। इसलिए ऑर्डर की सूची से इसे खुद निकालना सिर्फ़ अतिरिक्त मिलान के तौर पर ही करें।

• total टॉप-अप और कटौती की हिस्ट्री से मिलान के लिए ठीक है;
• available नई क्यू को लॉन्च की अनुमति देने के लिए ठीक है;
• reserved दिखाता है कि चालू ऑपरेशन के लिए कितनी राशि पहले से ब्लॉक है;
• currency को एक ही अकाउंट पर काम करते समय भी नज़रअंदाज़ नहीं करना चाहिए;
• updated_at लॉग और पुराने रिस्पॉन्स की पहचान के लिए उपयोगी है।

सिर्फ़ balance फ़ील्ड वाले रिस्पॉन्स को सँभालना आसान है, लेकिन उसमें कमी है: यह समझ नहीं आता कि ये पैसे तुरंत उपलब्ध हैं या राशि का कुछ हिस्सा दूसरे ऑर्डर के लिए पहले से रोका गया है।

API डॉक्युमेंटेशन में राशि का फ़ॉर्मैट जाँचें

उदाहरण में राशियाँ स्ट्रिंग के रूप में दी गई हैं: "84.50", संख्या 84.5 के रूप में नहीं। यह फ़ॉर्मैट सेवा से मिला सटीक मान बनाए रखता है। अगर API दशमलव बिंदु वाली स्ट्रिंग इस्तेमाल करता है, तो उन्हें तुरंत फ़्लोटिंग-पॉइंट संख्या में बदलकर float से तुलना न करें।

उदाहरण के लिए, आपकी गणना 84.50 की जगह 84.499999 दे सकती है। बजट की सीमा पर यह गलती से क्यू को पास कर सकता है या उलटे उसे रोक सकता है। स्ट्रिंग दशमलव मानों के साथ काम करने के लिए ऐसा दशमलव डेटा टाइप इस्तेमाल करें जो तय दशमलव स्थानों की सटीकता बनाए रखे।

एक और आम कॉन्ट्रैक्ट पूर्ण न्यूनतम इकाइयाँ हैं। तब रिस्पॉन्स में "available_minor": 8450 और "currency": "USD" हो सकता है, और ऑर्डर की कीमत "price_minor": 1250। ऐसे API में 8450 का मतलब 84.50 है, अगर मुद्रा के नियम दो दशमलव स्थान मानते हैं। मान को 100 से भाग दें सिर्फ़ तब जब डॉक्युमेंटेशन में साफ़ लिखा हो।

मुद्राएँ और कीमत के फ़ॉर्मैट न मिलाएँ

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

अपनी ओर से पहले से कन्वर्ज़न करना प्लानिंग के लिए सुविधाजनक है, लेकिन उसमें कमी है: कटौती के समय सेवा अलग दर, कमीशन या राउंडिंग का नियम लागू कर सकती है। ज़्यादा भरोसेमंद है ऑर्डर ऐसे पैरामीटर के साथ भेजना जिनके लिए API बैलेंस की मुद्रा में अंतिम कीमत लौटाता है, या ऑर्डर बनाने से ठीक पहले कीमत की गणना लेना।

अगर कीमत वाला मेथड "price": "12.345" लौटाता है और बैलेंस दो दशमलव स्थानों में मान रखता है, तो राउंडिंग का नियम साफ़ करें। अपने आप नीचे की ओर राउंड न करें: असल कटौती ज़्यादा हो सकती है। क्यू को अनुमति देने के लिए ठीक वही राशि इस्तेमाल करें जिसे API ऑर्डर की अंतिम कीमत कहता है।

पहले अनुरोध से पहले क्यू का बजट निकालें

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

मान लें क्यू में तीन ऑर्डर हैं। कीमत वाले API ने उनके लिए balance.currency में बताई गई उसी मुद्रा में 18.40, 27.15 और 31.60 लौटाए। बजट 77.15 है। अगर balance.available 84.50 है, तो नियोजित लॉन्च के बाद 7.35 बचते हैं। अगर available 76.90 है, तो पूरी क्यू लॉन्च नहीं की जा सकती।

1. हर ऑर्डर के असल पैरामीटर से कीमतें लें।
2. अंतिम कीमतें जोड़ें, उनका फ़ॉर्मैट और मुद्रा बदले बिना।
3. बजट की तुलना बैलेंस के ताज़ा रिस्पॉन्स के available से करें।
4. बैलेंस काफ़ी होने पर राशि को लोकल लॉन्च रिज़र्व के रूप में दर्ज करें।
5. हर ऑर्डर बनने के बाद लोकल रिज़र्व को पुष्ट कीमत के बराबर घटाएँ।

अतिरिक्त कटौती पर फेल होने का जोखिम बफ़र कम करता है, लेकिन उसमें कमी है: उपलब्ध राशि का कुछ हिस्सा बिना इस्तेमाल रह जाएगा, जबकि क्यू पूरी तरह पास हो सकती थी।

भेजने से ठीक पहले दूसरी जाँच करें

कैंपेन तैयार करते समय मिला बैलेंस जल्दी पुराना हो जाता है। गणना और लॉन्च के बीच के समय में दूसरा ऑपरेटर, ऑटोमेशन या चालू ऑर्डर available और reserved बदल सकते हैं। दोबारा अनुरोध क्यू बनने के बाद और पहले ऑर्डर से ठीक पहले ज़रूरी है।

काम करने वाली योजना दो चरणों की है: पहले कीमतें लें और बजट आँकें, फिर balance दोबारा पूछें। अगर available घटकर गणना की राशि से कम हो गया, तो क्यू पूरी नहीं भेजी जाती। अंतिम जाँच और लॉन्च के बीच उसी अकाउंट से दूसरी कटौतियाँ न करें।

पूरे लॉन्च के लिए एक अनुरोध API पर लोड कम करता है, लेकिन उसमें कमी यह है कि लंबी क्यू के अभी प्रोसेस होते समय उपलब्ध बैलेंस बदल सकता है।

पैसे कम होने पर क्यू कैसे लॉन्च करें

अगर available बजट से कम है, तो सारे अनुरोध इस उम्मीद में न भेजें कि कुछ तो पास हो जाएँगे। क्यू को ऐसे पैकेट में बाँटें जिनकी कीमत उपलब्ध सीमा में आ जाए। 76.90 बैलेंस वाले उदाहरण में पहले दो ऑर्डर 45.55 में भेजे जा सकते हैं, फिर रुकें: तीसरे ऑर्डर के 31.60 के लिए दोबारा जाँच ज़रूरी है।

बैचिंग में ऑर्डर का क्रम साफ़ तय करें। पहले प्राथमिक ऑर्डर भेजे जा सकते हैं, या कीमत में करीब वाले पैकेट बनाए जा सकते हैं। हर विकल्प में कमी है: प्राथमिक क्रम कम ज़रूरी ऑर्डर को पीछे डालेगा, और कीमत के हिसाब से छँटाई कैंपेन की मूल योजना बिगाड़ सकती है।

• मौजूदा available से ज़्यादा न होने वाली राशि का पैकेट बनाएँ।
• पैकेट के ऑर्डर बनाएँ और उनके आईडी सहेजें।
• रिस्पॉन्स का इंतज़ार करें या टाइम-आउट के बाद ऑपरेशन के स्टेटस जाँचें।
• अगर API की सीमाएँ या सेवा के नियम कहें, तो विराम लें।
• अगले पैकेट से पहले balance दोबारा पूछें।

हर पैकेट के बाद नए API रिस्पॉन्स को आधार बनाएँ, सिर्फ़ पुराने बैलेंस से लोकल घटाव को नहीं। लोकल गणना निगरानी के लिए उपयोगी है, लेकिन वह रिफ़ंड, बाहरी कटौतियाँ और रिज़र्व की दोबारा गणना नहीं देख पाती।

समानांतर भेजने पर बजट सुरक्षित रखें

एक के बाद एक प्रोसेसिंग में ऑर्डर की पुष्टि के बाद लोकल सीमा घटाना काफ़ी है। समानांतर मॉडल में दो वर्कर एक साथ available 84.50 देख सकते हैं और हर एक 60.00 का खर्च तय कर सकता है। अलग-अलग दोनों फ़ैसले सही लगते हैं, लेकिन मिलकर उपलब्ध बैलेंस से ज़्यादा हो जाते हैं।

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

• एक के बाद एक क्यू पर नियंत्रण आसान है, लेकिन लॉन्च धीमा होता है।
• समानांतर भेजना लॉन्च का समय घटाता है, लेकिन साझा बजट पर लॉक ज़रूरी है।
• लोकल रिज़र्वेशन टकराव कम करता है, लेकिन वर्कर फेल होने पर अटक सकता है।
• API की ओर से रिज़र्वेशन ज़्यादा भरोसेमंद है, लेकिन हर प्लेटफ़ॉर्म पर उपलब्ध नहीं।

अगर रिस्पॉन्स मिलने से पहले प्रोसेस खत्म हो गया, तो लोकल रिज़र्व को तुरंत खर्च या खाली न मानें। पहले जाँचें कि ऑर्डर बना या नहीं, उसके बाहरी आईडी से या ऑपरेशन खोजने वाले मेथड से।

अगर API रिज़र्व देता है तो उसका इस्तेमाल करें

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

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

API रिज़र्व सारी समस्याएँ नहीं सुलझाता: उसकी अवधि छोटी हो सकती है, वह कमीशन न कवर करे या पुष्टि में गलती के बाद खाली हो जाए। लोकल रिज़र्व लागू करना आसान है, लेकिन उसमें कमी यह है कि वह आपके ऐप के बाहर हुए खर्च से नहीं बचाता।

बैलेंस की गलती को शून्य बैलेंस से अलग रखें

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

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

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

टाइम-आउट के बाद डुप्लिकेट न बनाएँ

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

अगर API client_order_id, external_id या idempotency_key फ़ील्ड देता है, तो ऑर्डर की अनोखी बाहरी आईडी भेजें। अनुरोध भेजने से पहले उसे सहेजें। टाइम-आउट के बाद उस मान से ऑपरेशन खोजें या पहले मिली आईडी से स्टेटस पूछें।

बिना जाँच दोहराव तेज़ है, लेकिन उसकी कमी सीधी है: ऑर्डर डुप्लिकेट हो सकते हैं, दोहरा रिज़र्वेशन हो सकता है और आपके बजट की गणना और असल कटौतियों में फ़र्क आ सकता है।

लॉन्च लॉग में क्या सहेजें

लॉग मास ऑपरेशन का क्रम बहाल करने और यह समझाने में मदद करता है कि कोई खास पैकेट क्यों रुका। हर लॉन्च के लिए दोनों जाँचों का समय, total, available, reserved, currency, निकाला गया बजट, लोकल रिज़र्व का आकार और ऑर्डर की बाहरी आईडी की सूची सहेजें।

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

पूरा लॉगिंग डीबगिंग में सुविधाजनक है, लेकिन उसमें कमी है: बिना फ़िल्टर किए स्टोरेज में एक्सेस डेटा और ग्राहकों की जानकारी पहुँच सकती है।

छोटी क्यू पर योजना जाँचें

बड़े लॉन्च से पहले छोटा परिदृश्य चलाएँ: balance लें, अंतिम कीमतें पूछें, सीमित पैकेट बनाएँ, balance फिर पूछें और available तथा reserved में अपेक्षित बदलाव की तुलना असल रिस्पॉन्स से करें। इससे पता चलता है कि सेवा कब राशि रिज़र्व करती है और कब उसे पूरी तरह काटती है।

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