بررسی موجودی از طریق 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 را با پاسخ واقعی مقایسه کنید. این‌گونه می‌توانید متوجه شوید سرویس چه زمانی مبلغ را رزرو می‌کند و چه زمانی آن را نهایی کسر می‌کند.

بسته آزمایشی رفتار یکسان تحت بار سنگین را تضمین نمی‌کند: ممکن است محدودیت‌ها، فرایندهای موازی یا محدودیت‌های خدمت خاص اعمال شوند. بنابراین در صف انبوه، اجرا را به بسته‌ها تقسیم کنید، موجودی قابل‌استفاده را بین آن‌ها بررسی کنید و هر رد شدن را جداگانه بررسی کنید.