📱 راهنمای کامل پکیج رسمی پیشرو پیامک برای Node.js

🎯 درباره پکیج

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

با این کتابخانه، می‌توانید به‌راحتی پیامک‌های تأیید، اطلاع‌رسانی، بازاریابی و هر نوع پیام دیگری را به کاربران خود ارسال کنید و کد پیگیری دریافت نمایید. این پکیج با استفاده از axios برای ارسال درخواست‌های HTTP طراحی شده و از async/await برای کدنویسی غیرهمزمان پشتیبانی می‌کند.

📦 پیش‌نیازها

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

• Node.js نسخه ۱۴ یا بالاتر روی سیستم نصب باشد.

• مدیر پکیج npm یا yarn در دسترس باشد.

• اتصال به اینترنت برای ارتباط با وب‌سرویس.

• یک توکن معتبر از پنل کاربری پیشرو پیامک دریافت کرده باشید.

⚙️ مراحل نصب و راه‌اندازی

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

npm install pishropayamak-sms

گام دوم: نصب با yarn (اختیاری)
اگر از yarn استفاده می‌کنید، می‌توانید با دستور زیر پکیج را نصب کنید:

yarn add pishropayamak-sms

گام سوم: تنظیم توکن
توکن خود را از پنل کاربری پیشرو پیامک دریافت کنید. می‌توانید توکن را به‌صورت مستقیم یا با استفاده از متغیرهای محیطی تنظیم کنید.

روش اول (استفاده مستقیم)

روش دوم (استفاده از متغیر محیطی - توصیه‌شده)

🚀 نحوه استفاده از پکیج

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

📝 پارامترهای ورودی متد sendSms

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

• پارامتر اول، شماره خط اختصاصی شما به‌عنوان فرستنده است که مقدار آن ضروری می‌باشد.

• پارامتر دوم، لیستی از شماره موبایل گیرندگان است که باید به‌صورت یک آرایه (Array) ارسال شود و مقدار آن ضروری می‌باشد.

• پارامتر سوم، متن پیامک است که حداکثر طول آن هزار کاراکتر بوده و مقدار آن ضروری می‌باشد.

• پارامتر چهارم، نوع پیام است که مقدار صفر برای معمولی و مقدار یک برای فلش می‌باشد و در صورت عدم تعیین، به‌صورت پیش‌فرض روی صفر تنظیم می‌شود.

📤 خروجی متد ارسال پیامک

خروجی این متد یک شیء (Object) است که در دو حالت متفاوت بازگردانده می‌شود.
در صورت موفقیت، شیء شامل دو کلید success با مقدار true و id با مقدار عددی کد پیگیری خواهد بود.
در صورت خطا، شیء شامل دو کلید success با مقدار false و error با پیام توضیحی مربوطه خواهد بود.

برخی از خطاهای رایج شامل موارد زیر می‌باشند:

• خطای ۴۰۱: توکن نامعتبر یا منقضی شده است.

• خطای ۴۰۳: دسترسی ندارید یا اعتبار حساب کافی نیست.

• خطای ۴۰۰: پارامترهای ارسالی نامعتبر هستند.

• خطای شبکه: اتصال اینترنت قطع است یا API مسدود شده است.

💡 مثال‌های عملی از کاربرد پکیج

برای آشنایی بیشتر با کاربرد این پکیج، چند مثال عملی را مرور می‌کنیم.

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

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

ارسال پیام فلش: با تنظیم نوع پیام بر روی عدد یک، پیامک شما به‌صورت فلش (نمایشی) برای گیرنده ارسال می‌شود.

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

🔒 نکات امنیتی مهم

برای حفظ امنیت پروژه خود، حتماً به نکات زیر توجه کنید:

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

• برای ارتباط با سرور، همواره از پروتکل امن HTTPS استفاده می‌شود.

• توکن‌ها ممکن است دارای تاریخ انقضا باشند، بنابراین به‌طور دوره‌ای آنها را بررسی و در صورت نیاز تمدید کنید.

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

🧪 عیب‌یابی مشکلات رایج

مشکل اول: Error: Cannot find module 'pishropayamak-sms'
اگر با این خطا مواجه شدید، ابتدا مطمئن شوید که پکیج را با دستور npm install pishropayamak-sms نصب کرده‌اید. سپس بررسی کنید که در پوشه صحیح قرار دارید و فایل node_modules وجود دارد.

مشکل دوم: خطای 403 در هنگام انتشار
اگر هنگام انتشار با خطای 403 مواجه شدید، باید از توکن دسترسی با قابلیت Bypass 2FA استفاده کنید یا از کد OTP استفاده نمایید.

مشکل سوم: خطای گواهی SSL
در محیط توسعه، ممکن است با خطای گواهی SSL مواجه شوید که در این صورت می‌توانید برای تست، تأیید گواهی را به‌صورت موقت غیرفعال کنید (فقط برای تست).

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

📚 منابع و مستندات بیشتر

برای اطلاعات بیشتر و دریافت راهنمایی‌های تکمیلی، می‌توانید از منابع زیر استفاده کنید:

• وب‌سایت رسمی پیشرو پیامک

• ایمیل پشتیبانی

• مخزن گیت‌هاب پکیج

• صفحه پکیج در npm

📄 مجوز و مشارکت

این پکیج تحت مجوز MIT منتشر شده است. اگر مشکلی پیدا کردید یا پیشنهادی برای بهبود دارید، خوشحال می‌شویم که در مخزن گیت‌هاب موضوع جدیدی ایجاد کنید یا درخواست تغییر ارسال نمایید.

ساخته شده با ❤️ توسط پیشرو پیامک