ম্যাস অর্ডার চালু করার আগে 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-এর প্রত্যাশিত পরিবর্তন প্রকৃত রেসপন্সের সাথে তুলনা করুন। এভাবে বোঝা যায়, সেবা কখন পরিমাণ রিজার্ভ করে আর কখন তা চূড়ান্তভাবে কেটে নেয়।

পরীক্ষামূলক প্যাকেট বড় লোডে একই আচরণের নিশ্চয়তা দেয় না: সীমা, সমান্তরাল প্রসেস বা নির্দিষ্ট সেবার বিধিনিষেধ কার্যকর হতে পারে। তাই ম্যাস কিউয়ে চালু করা প্যাকেটে ভাগ করা, তাদের মধ্যে উপলব্ধ ব্যালেন্স যাচাই এবং প্রতিটি প্রত্যাখ্যান আলাদাভাবে বিশ্লেষণ চালিয়ে যান।