چگونه شارژ خودکار موجودی در پنل SMM را از طریق API تنظیم کنیم

چه چیزهایی را پیش از تنظیم شارژ خودکار آماده کنیم

شارژ خودکار موجودی پنل SMM را به سرویس پرداخت یا صورت‌حساب داخلی متصل می‌کند. سرویس موجودی را بررسی می‌کند، هنگام رسیدن به آستانه تعیین‌شده پرداخت ایجاد می‌کند و وجه را فقط پس از تأیید پرداخت واریز می‌کند. برای این کار به مستندات API پنل، دسترسی به API پرداخت، کلیدهای جداگانه برای محیط آزمایشی و عملیاتی و همچنین گزارش تمام عملیات نیاز است.

پیش از توسعه بررسی کنید که آیا API پنل توانایی برگرداندن موجودی، پذیرش درخواست واریز، نمایش تاریخچه شارژها و پذیرش شناسه خارجی عملیات را دارد یا خیر. اگر پنل از واریز از طریق API پشتیبانی نکند، خودکارسازی فقط می‌تواند درخواست ایجاد کند یا به اپراتور اطلاع دهد. عیب این گزینه این است که پول همچنان باید به‌صورت دستی واریز شود.

بررسی موجودی و تصمیم درباره پرداخت را از هم جدا کنید

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

پیش از پرداخت جدید، پردازشگر باید بررسی کند که آیا عملیاتی با وضعیت «ایجادشده»، «در انتظار پرداخت» یا «در حال تأیید» وجود دارد یا خیر. اگر چنین رکوردی وجود داشته باشد، تلاش جدید تا پایان تطبیق اجرا نمی‌شود. عیب پردازش ترتیبی این است که در صورت پاسخ کند API خارجی، شارژ ممکن است دیرتر از حالت چند درخواست موازی آغاز شود.

آستانه و منطق مبلغ شارژ را انتخاب کنید

آستانه موجودی را با حاشیه‌ای برای سفارش‌های فعال، صف تأمین‌کنندگان و تأخیرهای پرداخت انتخاب کنید. برای کانالی با فعالیت نامنظم، تکیه صرف بر میانگین هزینه پرخطر است: پس از استریم، شروع تبلیغات یا سفارش انبوه، برداشت‌ها ممکن است به‌شدت افزایش یابند. سطح بحرانی را جداگانه تعیین کنید؛ در این سطح اعلان ارسال می‌شود اما پرداخت لزوماً به‌صورت خودکار ایجاد نمی‌شود.

مبلغ شارژ می‌تواند ثابت باشد یا بر اساس هزینه در بازه انتخابی محاسبه شود. مبلغ ثابت برای کنترل و تطبیق ساده‌تر است. عیب آن این است که در دوره آرام ممکن است وجه اضافی در موجودی بماند و در صورت رشد ناگهانی سفارش‌ها یک شارژ کافی نباشد. مبلغ محاسبه‌شده انعطاف‌پذیرتر است اما نیاز به پاک‌سازی آمار از برداشت‌ها و بازگشت‌های غیرعادی دارد.

محدودیت‌های مالی را جدا از آستانه تنظیم کنید

آستانه فقط به این پرسش پاسخ می‌دهد که چه زمانی سیستم مجاز است فرایند شارژ را آغاز کند. محدودیت‌ها به پرسش دیگری پاسخ می‌دهند: سیستم چه مقدار وجه را مجاز است برداشت کند. حداکثر مبلغ یک عملیات، سقف کل برای یک دوره و موجودی مجاز پس از واریز را تعیین کنید. این قواعد پیش از ایجاد پرداخت بررسی می‌شوند، نه پس از پرداخت آن.

شارژ خودکار نباید بدون محدودیت برای عملیات و دوره، وجهی برداشت کند. اگر مبلغ محاسبه‌شده از مقدار مجاز بیشتر باشد، بهتر است عملیات به بررسی دستی منتقل شود و اعلان ارسال گردد. عیب محدودیت‌های سخت این است که در صورت رشد سریع هزینه‌ها، موجودی ممکن است پیش از تأیید افزایش سقف توسط کارمند مسئول تمام شود.

کلیدهای جداگانه ایجاد کنید و دسترسی را محافظت کنید

برای اسکریپت شارژ خودکار از کلیدهای API جداگانه با حداقل دسترسی استفاده کنید: خواندن موجودی، ایجاد پرداخت، بررسی وضعیت و واریز عملیات تأییدشده. دسترسی به کاربران، تنظیمات خدمات، سفارش‌ها و برداشت وجه برای چنین کلیدی لازم نیست. اگر سرویس محدودیت بر اساس آدرس IP را پشتیبانی می‌کند، فقط درخواست‌ها از سرور یکپارچه‌سازی را مجاز کنید.

کلیدها را در متغیرهای محیطی یا مخزن امن اسرار نگهداری کنید. آن‌ها را در کد مرورگر، لاگ‌ها، مخازن عمومی و پیام‌های خطا قرار ندهید. هر کلید باید مالک و رویه جایگزینی مشخصی داشته باشد. عیب چرخش مکرر کلیدها این است که اگر کلید جدید در تمام فرایندهای کاری به‌روزرسانی نشود، شارژ متوقف می‌شود.

پرداخت را با شناسه یکتا ایجاد کنید

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

در ادامه یک نمونه کلی از درخواست آمده است. نام فیلدها و آدرس‌ها را با مقادیر مستندات ارائه‌دهنده مشخص جایگزین کنید. در متغیر PAYMENT_ID شناسه یکتای از پیش ایجادشده نگهداری می‌شود و CALLBACK_URL به پردازشگر وب‌هوک اشاره می‌کند.

curl -X POST "$PAYMENT_API_URL/payments" \
-H "Authorization: Bearer $PAYMENT_API_KEY" \
-H "Idempotency-Key: $PAYMENT_ID" \
-H "Content-Type: application/json" \
-d '{"amount":"$TOPUP_AMOUNT","currency":"$CURRENCY","external_id":"$PAYMENT_ID","callback_url":"$CALLBACK_URL"}'

یکتایی پرداخت را فقط بر اساس مبلغ و زمان ایجاد تعیین نکنید. دو شارژ یکسان می‌توانند مشروع باشند، اما درخواست تکراری پس از خطا مشروع نیست. عیب شناسه خارجی در پایگاه داده خودتان این است که باید به‌طور مطمئن نگهداری شود و پس از لغو عملیات دوباره استفاده نشود.

موجودی را بررسی کنید و وضعیت عملیات را ذخیره کنید

درخواست موجودی باید پیش از تصمیم درباره شارژ جدید و پس از واریز موفق اجرا شود. یک درخواست کلی می‌تواند این‌گونه باشد: curl -X GET "$PANEL_API_URL/balance" -H "Authorization: Bearer $PANEL_API_KEY". در پاسخ نه‌تنها مبلغ، بلکه زمان بررسی را نیز ذخیره کنید تا تصمیم بر اساس داده‌های قدیمی گرفته نشود.

برای هر عملیات رکوردی با شناسه داخلی، شناسه پرداخت نزد ارائه‌دهنده، مبلغ، ارز، زمان ایجاد، وضعیت، پاسخ‌های API و علت خطا نگهداری کنید. زنجیره مناسب وضعیت‌ها: «ایجادشده»، «در انتظار پرداخت»، «پرداخت‌شده»، «در حال واریز»، «واریزشده»، «لغوشده»، «نیازمند بررسی».

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

وب‌هوک را دریافت کنید و وضعیت پرداخت را تطبیق دهید

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

پس از بررسی وب‌هوک، بهتر است وضعیت فعلی پرداخت را از ارائه‌دهنده درخواست کنید. برای مثال: curl -X GET "$PAYMENT_API_URL/payments/$PROVIDER_PAYMENT_ID" -H "Authorization: Bearer $PAYMENT_API_KEY". وضعیت را با داده‌های گزارش تطبیق دهید، سپس درخواست واریز به پنل SMM را با همان شناسه داخلی ارسال کنید.

وب‌هوک تکراری نباید واریز دوم ایجاد کند. پردازشگر عملیات را بر اساس شناسه خارجی پیدا می‌کند، وضعیت «واریزشده» را می‌بیند و بدون اقدام جدید پاسخ موفق برمی‌گرداند. عیب وب‌هوک‌ها این است که ممکن است تأخیر داشته باشند یا در صورت در دسترس نبودن پردازشگر نرسند.

وقفه‌ها، تلاش‌های مجدد و پرداخت‌های معلق را مدیریت کنید

در صورت وقفه پس از ایجاد پرداخت، درخواست جدید با شناسه دیگر ارسال نکنید. ابتدا عملیات را بر اساس شناسه داخلی پیدا کنید یا درخواست را با همان کلید یکتایی تکرار کنید. اگر ارائه‌دهنده درخواست اولیه را پذیرفته باشد، پرداخت موجود را برمی‌گرداند. این کار از برداشت دوباره در صورت قطع اتصال محافظت می‌کند.

اگر وب‌هوک در زمان تعیین‌شده نرسد، وظیفه پس‌زمینه وضعیت پرداخت را از طریق API درخواست می‌کند. بررسی‌های تکراری با فاصله افزایش‌یابنده و تعداد محدود تلاش انجام می‌شوند تا API و گزارش بیش از حد بارگذاری نشوند. عملیاتی که مدت طولانی در انتظار می‌ماند به بررسی دستی منتقل می‌شود و بدون تطبیق، لغوشده در نظر گرفته نمی‌شود.

در صورت پاسخ‌های مربوط به خطای موقت شبکه یا در دسترس نبودن API، تلاش مجدد مجاز است. در صورت رد پرداخت، مبلغ نادرست، امضای نامعتبر وب‌هوک یا عبور از محدودیت، تکرار خودکار درخواست توصیه نمی‌شود. عیب تلاش‌های مجدد این است که منطق وضعیت‌ها را پیچیده‌تر می‌کنند و در صورت خرابی انبوه نزد ارائه‌دهنده ممکن است بار اضافی ایجاد کنند.

پرداخت تأییدشده را به پنل SMM واریز کنید

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

نمای کلی درخواست: curl -X POST "$PANEL_API_URL/balance/topups" -H "Authorization: Bearer $PANEL_API_KEY" -H "Content-Type: application/json" -H "Idempotency-Key: $PAYMENT_ID" -d '{"amount":"$TOPUP_AMOUNT","currency":"$CURRENCY","external_id":"$PAYMENT_ID"}'

پس از پاسخ پنل، موجودی را دوباره درخواست کنید و نتیجه را در گزارش ذخیره کنید. اگر پول نزد سرویس پرداخت برداشت شده اما API پنل خطا برگردانده است، پرداخت جدید ایجاد نکنید. عملیات تا تلاش مجدد برای واریز یا تطبیق دستی در وضعیت «نیازمند بررسی» می‌ماند. عیب چنین طرح محتاطانه‌ای این است که موجودی ممکن است موقتاً به‌صورت خودکار شارژ نشود.

اعلان‌ها، کلید خاموش‌کن و بررسی راه‌اندازی را اضافه کنید

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

یک کلید خاموش‌کن جداگانه برای شارژ خودکار بدون حذف یکپارچه‌سازی باقی بگذارید. این کلید هنگام تغییر ارائه‌دهنده، کارهای فنی، احتمال خطا یا تغییر ناگهانی هزینه‌ها لازم است. عیب کلید خاموش‌کن واضح است: اگر پس از کارها دوباره روشن نشود، موجودی ممکن است در حین سفارش‌های فعال تمام شود.

چک‌لیست پیش از فعال‌سازی شارژ خودکار

• بررسی موجودی تا زمانی که عملیات ناتمام وجود دارد، پرداخت ایجاد نمی‌کند.
• برای هر پرداخت شناسه داخلی یکتا و کلید یکتایی ایجاد می‌شود.
• محدودیت‌ها برای یک عملیات و دوره انتخابی تنظیم شده‌اند.
• وب‌هوک‌ها بر اساس امضا، مبلغ، ارز و شناسه بررسی می‌شوند.
• در صورت نبود وب‌هوک، تطبیق مجدد وضعیت از طریق API اجرا می‌شود.
• وقفه منجر به ایجاد پرداخت دوم پیش از بررسی پرداخت اول نمی‌شود.
• واریز به پنل یک بار انجام می‌شود و در گزارش ثبت می‌گردد.
• حالت آزمایشی برای موفقیت، رد، وب‌هوک تکراری و در دسترس نبودن API بررسی شده است.