📱 راهنمای کامل پکیج رسمی پیشرو پیامک برای پایتون

🎯 درباره پکیج

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

با این کتابخانه، می‌توانید به‌راحتی پیامک‌های تأیید، اطلاع‌رسانی، بازاریابی و هر نوع پیام دیگری را به کاربران خود ارسال کنید و کد پیگیری دریافت نمایید.

📦 پیش‌نیازها

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

• پایتون نسخه ۳.۸ یا بالاتر روی سیستم نصب باشد.

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

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

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

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

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

pip install pishropayamak-sms

گام دوم: ایجاد محیط مجازی (توصیه‌شده برای اوبونتو ۲۴+)
اگر از اوبونتو ۲۴ یا سیستم‌های مشابه استفاده می‌کنید که خطای externally-managed-environment می‌دهند، بهتر است از محیط مجازی استفاده کنید.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

مشکل اول: خطای externally-managed-environment
اگر با این خطا مواجه شدید، باید از محیط مجازی استفاده کنید یا از گزینه --break-system-packages استفاده نمایید (توصیه نمی‌شود).

مشکل دوم: ModuleNotFoundError: No module named 'pishropayamak_sms'
پکیج را با دستور pip install pishropayamak-sms نصب کنید. اگر در محیط مجازی هستید، مطمئن شوید که محیط مجازی فعال است.

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

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

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

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

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

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

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

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

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

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

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