روش استفاده

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

مرحله اول: دریافت توکن از پنل کاربری

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

مرحله دوم: ایجاد پروژه جاوا

یک پروژه جدید در محیط توسعه دلخواه خود (مثل IntelliJ IDEA، Eclipse یا NetBeans) ایجاد کنید. اطمینان حاصل کنید که از جاوا ۱۱ یا بالاتر استفاده می‌کنید تا از کتابخانه java.net.http که در این سرویس استفاده می‌شود، پشتیبانی شود. اگر از نسخه‌های قدیمی‌تر استفاده می‌کنید، می‌توانید از کتابخانه‌های محبوبی مانند Apache HttpClient یا OkHttp استفاده کنید.

مرحله سوم: ایجاد کلاس سرویس پیامک

یک کلاس جدید در پروژه خود ایجاد کنید (نام کلاس می‌تواند SmsService باشد). این کلاس شامل بخش‌های زیر خواهد بود:

• سازنده (Constructor): که توکن را دریافت کرده و آدرس پایه API را تنظیم می‌کند.

• متد ارسال پیامک: که پارامترهای شماره فرستنده، لیست گیرندگان، متن پیام و نوع پیام را دریافت کرده، درخواست را به سرور ارسال کرده و پاسخ را پردازش می‌کند.

• کلاس‌های کمکی: برای ساختاردهی درخواست (شامل from، recipients، message، type) و پاسخ (شامل status و result.id) به فرمت JSON.

مرحله چهارم: تنظیم توکن و پارامترهای پیامک

در متد main یا در بخشی که قصد اجرای برنامه را دارید، توکن دریافتی را به سازنده کلاس پاس دهید. همچنین شماره خط اختصاصی خود (فرستنده)، لیست شماره موبایل گیرندگان و متن پیام را مشخص کنید. در صورت نیاز، نوع پیام را نیز تنظیم کنید (۰ برای معمولی و ۱ برای فلش).

مرحله پنجم: ارسال درخواست به وب‌سرویس

با استفاده از کتابخانه java.net.http.HttpClient، یک درخواست از نوع POST به آدرس API سرویس ارسال می‌کنید. توکن دریافتی را در هدر درخواست با کلید token قرار می‌دهید. بدنه درخواست شامل شماره فرستنده، لیست گیرندگان، متن پیام و نوع پیام است که به فرمت JSON تبدیل شده و ارسال می‌شود. تایم‌اوت درخواست را روی ۳۰ ثانیه تنظیم کنید تا از قطعی ارتباط جلوگیری شود.

مرحله ششم: دریافت پاسخ و تفسیر نتیجه

پس از ارسال درخواست، سرور پاسخ را به صورت یک شیء JSON بازمی‌گرداند. با استفاده از کتابخانه‌های تبدیل JSON مانند Jackson یا Gson، پاسخ را تجزیه کرده و وضعیت آن را بررسی می‌کنید. اگر کلید status برابر با ۲۰۰ باشد و در بخش result یک id عددی بزرگتر از صفر وجود داشته باشد، عملیات با موفقیت انجام شده است و آن عدد، کد پیگیری شما خواهد بود. در غیر این صورت، کلید status مقدار خطا را نشان می‌دهد که می‌توانید بر اساس آن مشکل را شناسایی کنید.

مرحله هفتم: تست و عیب‌یابی

پیش از استفاده گسترده، حتماً سرویس را با یک یا دو شماره تست کنید. برنامه خود را اجرا کرده و خروجی را مشاهده کنید. اگر خطایی رخ داد، موارد زیر را به ترتیب بررسی کنید:

• صحت توکن

• معتبر بودن شماره فرستنده (خط اختصاصی ثبت‌شده در پنل)

• فرمت صحیح شماره‌های گیرندگان

• وجود اعتبار کافی در حساب کاربری برای ارسال پیامک

• اتصال اینترنت و عدم محدودیت دسترسی به آدرس API

۱. نکات فنی و بهینه‌سازی

• مدیریت تایم‌اوت: تایم‌اوت پیش‌فرض ۳۰ ثانیه برای اکثر موارد کافی است. در صورت نیاز به تغییر، مقدار تایم‌اوت را در کد تنظیم کنید.

• نوع پیام: پارامتر type با مقدار ۰ برای پیامک معمولی و ۱ برای پیامک فلش (نمایشی) استفاده می‌شود.

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

• پردازش پاسخ‌های JSON: ساختار پاسخ سرور را به دقت در کد تعریف کنید. اگر پاسخ‌ها با ساختار متفاوتی بازگردانده شدند، می‌توانید ساختار را مطابق با مستندات سرویس به‌روزرسانی کنید.

• وابستگی به کتابخانه: برای تبدیل JSON به شیء جاوا، می‌توانید از کتابخانه‌های Jackson یا Gson استفاده کنید. این کتابخانه‌ها را باید به پروژه اضافه کنید.

۲. نکات امنیتی حیاتی

• ذخیره‌سازی امن توکن: هرگز توکن را به صورت مستقیم و آشکار در کدهای منبع قرار ندهید. از متغیرهای محیطی (System.getenv()) یا فایل‌های پیکربندی خارج از دایرکتوری پروژه استفاده کنید.

• استفاده از HTTPS: همیشه از پروتکل HTTPS برای ارتباط با سرور استفاده کنید تا اطلاعات در حین انتقال رمزگذاری شوند.

• تمدید دوره‌ای توکن: توکن‌ها معمولاً دارای تاریخ انقضا هستند. به صورت دوره‌ای توکن خود را بررسی کرده و در صورت نیاز آن را تمدید کنید.

• باطل‌سازی توکن: در صورت پایان پروژه یا تغییر کلیدها، توکن را از پنل کاربری باطل کنید تا از سوءاستفاده احتمالی جلوگیری شود.

• ثبت خطاها: تمام خطاها و پاسخ‌های دریافتی از سرور را در لاگ‌های برنامه ثبت کنید تا در صورت بروز مشکل، بتوانید به سرعت عیب‌یابی کنید.

۳. مزایای استفاده از روش توکن نسبت به روش نام کاربری و رمز عبور

• امنیت بالاتر: توکن به جای ارسال مستقیم نام کاربری و رمز عبور در هر درخواست، یک کلید موقت و قابل ابطال است.

• مدیریت دسترسی: می‌توانید برای توکن‌ها سطح دسترسی، تاریخ انقضا و محدودیت تعداد درخواست تعیین کنید.

• کاهش ترافیک: ارسال یک توکن در هدر به جای دو پارامتر نام کاربری و رمز عبور، حجم درخواست را کاهش می‌دهد.

• سازگاری با معماری‌های مدرن: روش توکن با معماری‌های مبتنی بر JWT و OAuth سازگاری کامل دارد و برای پروژه‌های توزیع‌شده و میکروسرویس‌ها ایده‌آل است.

۴. نام فایل در پروژه جاوا

در پروژه جاوا، نام فایل سورس باید با نام کلاس عمومی (public class) داخل آن یکی باشد. بنابراین اگر کلاس شما با نام SmsService تعریف شده است، فایل باید دقیقاً SmsService.java نامگذاری شود. حروف بزرگ و کوچک مهم هستند، پس حتماً با S بزرگ شروع شود.