آرڈرز کے بڑے پیمانے پر آغاز سے پہلے 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 نے ان کے لیے اسی کرنسی میں 18.40، 27.15 اور 31.60 واپس کیے جو balance.currency میں درج ہے۔ بجٹ 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 کی متوقع تبدیلی کا حقیقی جواب سے موازنہ کریں۔ اس طرح معلوم ہو سکتا ہے کہ سروس کب رقم ریزرو کرتی ہے اور کب اسے حتمی طور پر کاٹتی ہے۔

ٹیسٹ پیکٹ بھاری بوجھ کے تحت یکساں رویے کی ضمانت نہیں دیتا: حدود، متوازی عمل یا مخصوص سروس کی پابندیاں لاگو ہو سکتی ہیں۔ اس لیے بڑی قطار میں آغاز کو پیکٹوں میں تقسیم کرتے رہیں، ان کے درمیان دستیاب بیلنس جانچتے رہیں اور ہر انکار کو الگ سے سلجھائیں۔