روش استفاده

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

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

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

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

یک پوشه جدید برای پروژه خود ایجاد کنید. سپس با استفاده از ترمینال یا خط فرمان، وارد پوشه شوید و دستور زیر را اجرا کنید تا یک پروژه Node.js جدید ایجاد شود:

npm init -y

این دستور یک فایل package.json ایجاد می‌کند.

مرحله سوم: نصب کتابخانه axios

برای ارسال درخواست‌های HTTP به سرور، نیاز به یک کتابخانه دارید. کتابخانه axios یکی از محبوب‌ترین گزینه‌ها در Node.js است. برای نصب آن، دستور زیر را اجرا کنید:

npm install axios

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

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

• کلاس SmsService: که شامل سازنده (constructor) برای دریافت توکن و تنظیم آدرس پایه API است.

• متد sendSms: که به صورت غیرهمزمان (async) کار ارسال پیامک را انجام می‌دهد. این متد پارامترهای شماره فرستنده، لیست گیرندگان، متن پیام و نوع پیام را دریافت کرده، درخواست را به سرور ارسال کرده و پاسخ را پردازش می‌کند.

• مدیریت خطا: خطاهای شبکه، خطاهای HTTP و خطاهای مربوط به JSON را به درستی مدیریت می‌کند.

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

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

مرحله ششم: ارسال درخواست به وب‌سرویس

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

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

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

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

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

node smsService.js

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

• صحت توکن و عدم انقضای آن.

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

• فرمت صحیح شماره‌های گیرندگان (با کد ۰۹۱۲...).

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

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

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

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

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

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

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

• استفاده از async/await: متد ارسال پیامک به صورت غیرهمزمان (Async) طراحی شده است تا از بلاک‌شدن حلقه رویداد (Event Loop) در Node.js جلوگیری کند. این روش برای اپلیکیشن‌های وب و سرور بسیار کارآمد است.

• مدیریت خطاهای HTTP: خطاهای HTTP مانند ۴۰۱، ۴۰۳، ۴۰۰ و ... به درستی شناسایی و خطای مناسب بازگردانده می‌شود.

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

• ذخیره‌سازی امن توکن: هرگز توکن را به صورت مستقیم و آشکار در کدهای منبع قرار ندهید. از متغیرهای محیطی (process.env.TOKEN) یا فایل‌های پیکربندی مانند .env استفاده کنید. برای این کار، کتابخانه dotenv را نصب کنید.

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

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

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

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

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

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

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

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

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

۷. نام فایل در پروژه Node.js

در پروژه Node.js، نام فایل می‌تواند دلخواه باشد، اما بهترین روش این است که نام فایل با نام کلاس یا محتوای آن مطابقت داشته باشد. بنابراین اگر کلاس شما با نام SmsService تعریف شده است، فایل را smsService.js نامگذاری کنید. (در Node.js معمولاً از حروف کوچک برای نام فایل‌ها استفاده می‌شود.)