آموزش ارسال پیامک با پایتون از کلید API تا بررسی پاسخ وب سرویس پیامکی

برای ارسال پیامک با پایتون، به حساب فعال سامانه پیامکی، کلید API و مشخصات متد ارسال نیاز دارید.

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

پیش از کدنویسی روش ارسال را مشخص کنید

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

برای شروع اتصال به وب سرویس پیامک پیام رسان، از مسیر «API» و «کلید API» درخواست فعال سازی بدهید. پس از فعال سازی، کلید بسازید و خط مجاز حساب را مشخص کنید.

پیش از اجرای نمونه، این موارد را آماده کنید:

• کلید معتبر و اعتبار کافی برای ارسال آزمایشی؛
• شماره فرستنده مجاز و شماره گیرنده متعلق به خودتان؛
• دسترسی شبکه سرور به نشانی API و تنظیمات مجاز دسترسی حساب.

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

محیط پایتون و متغیرها را آماده کنید

یک محیط مجازی با دستور python -m venv .venv بسازید و آن را فعال کنید. سپس python -m pip install requests را اجرا کنید. در ویندوز می توانید مفسر محیط مجازی را مستقیماً از مسیر .venv\Scripts\python.exe فراخوانی کنید؛ در لینوکس مسیر متناظر .venv/bin/python است.

متغیرهای PAYAM_RESAN_API_KEY، SMS_SENDER و SMS_RECIPIENT را برای همان فرایندی تعریف کنید که برنامه را اجرا می کند. مقدار اول کلید واقعی، مقدار دوم خط حساب و مقدار سوم شماره آزمایشی شماست. صرف ساختن فایل .env باعث خواندن خودکار آن با os.environ نمی شود.

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

نمونه ارسال پیامک با API در پایتون

این نمونه، متد SendBulk نسخه V3 را با یک گیرنده فراخوانی می کند. ساختار بدنه از راهنمای رسمی ارسال گروهی و نشانی HTTPS از صفحه وب سرویس گرفته شده است.

import os

import requests

payload = {

    “ApiKey”: os.environ[“PAYAM_RESAN_API_KEY”],

    “Sender”: int(os.environ[“SMS_SENDER”]),

    “Text”: “این یک پیام آزمایشی از برنامه پایتون است.”,

    “Recipients”: [{

        “Destination”: int(os.environ[“SMS_RECIPIENT”]),

        “UserTraceId”: 14050001,

    }],

}

try:

    response = requests.post(

        “https://api.sms-webservice.com/api/V3/SendBulk”,

        json=payload,

        timeout=(5, 20),

    )

    response.raise_for_status()

    result = response.json()

except requests.exceptions.Timeout:

    raise SystemExit(“مهلت ارتباط تمام شد؛ نتیجه ارسال نامشخص است.”)

except requests.exceptions.HTTPError:

    raise SystemExit(f”خطای HTTP: {response.status_code}”)

except requests.exceptions.JSONDecodeError:

    raise SystemExit(“پاسخ سرویس JSON معتبر نیست.”)

except requests.exceptions.RequestException:

    raise SystemExit(“ارتباط با سرویس تکمیل نشد.”

if not isinstance(result, dict):

    raise SystemExit(“ساختار پاسخ با قرارداد مورد انتظار سازگار نیست.”)

if result.get(“Success”) is not True:

    raise SystemExit(f”خطای عملیات: {result.get(‘ErrorCode’)}”)

print(“درخواست پذیرفته شد؛ اطلاعات پیام را برای پیگیری ذخیره کنید.”)

فایل را مثلاً با نام send_sms.py ذخیره و با مفسر همان محیط اجرا کنید. تعریف نشدن متغیر محیطی یا مقدار غیرعددی شماره، پیش از ارسال درخواست خطا ایجاد می کند. مقدار UserTraceId در این نمونه فرضی است؛ برای اتصال واقعی، شناسه پیگیری مرتبط با رخداد خودتان را طبق قرارداد متد تعیین کنید.

پاسخ سرویس را در چند سطح بررسی کنید

متد raise_for_status() خطاهای HTTP را بررسی می کند و response.json() بدنه را می خواند. معتبر بودن JSON به تنهایی موفقیت عملیات را ثابت نمی کند.

همانطور که در requests.readthedocs.io گفته شده: «If no timeout is specified explicitly, requests do not time out.» (منبع)

ترجمه: اگر زمان انتظار را صریح تعیین نکنید، Requests محدودیت زمانی اعمال نمی کند.

در نمونه، اعداد ۵ و ۲۰ ثانیه تنظیمات پیشنهادی برای اتصال و انتظار خواندن داده هستند؛ این ها تضمین زمان پاسخ سرویس نیستند. این تنظیم نیز سقف قطعی مدت کل عملیات را تعیین نمی کند. مقادیر را با شرایط شبکه و نیاز برنامه تنظیم کنید.

پس از پذیرش، شناسه های برگشتی در Result را طبق قرارداد متد ذخیره کنید. پیام رسان برای استعلام وضعیت، StatusById را معرفی می کند. در پایگاه داده، «پذیرفته شده» و «تحویل شده» را جدا نگه دارید.

خطاها و ارسال تکراری را مدیریت کنید

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

در صورت دریافت HTTP ۴۲۹، نرخ درخواست ها را کاهش دهید. استاندارد RFC 6585 این کد را به محدودیت نرخ مربوط می داند و امکان وجود هدر Retry-After را توضیح می دهد. این تعریف، ادعای پشتیبانی همه ارائه دهندگان از همین رفتار نیست. (متن استاندارد)

برای توسعه ارسال گروهی هم سقف متدها را یکسان فرض نکنید. صفحه رسمی پیام رسان هنگام بررسی، سقف Send را ۹۹ گیرنده و گروه های SendMultiple را ۱۰۰تایی اعلام کرده است. این ظرفیت ها را بدون بررسی به SendBulk تعمیم ندهید.

اتصال را برای استفاده واقعی آماده کنید

در برنامه های Django یا Flask، منطق API پیامک را در یک ماژول مستقل نگه دارید تا تنظیمات، تفسیر پاسخ و ثبت رخدادها در یک محل مدیریت شوند. برای حجم بالاتر، اجرای ارسال در صف کار به پاسخ گویی درخواست اصلی سایت کمک می کند.

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

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

برای لاگ ها، شناسه داخلی، زمان درخواست و کد نتیجه معمولاً کاربردی تر از ذخیره تمام بدنه هستند. شماره ها را ماسک کنید و کلید API یا متن حساس پیام را ثبت نکنید. آزمون اولیه را با تعداد محدود و شماره خودتان انجام دهید و سپس اتصال را به رخداد واقعی برنامه متصل کنید.

پرسش های متداول

آیا پایتون بدون پنل پیامکی هم پیامک می فرستد

در روش این آموزش، پایتون نقش کلاینت را دارد و ارسال از طریق حساب ارائه دهنده انجام می شود. کتابخانه Requests خودش شبکه ارسال پیامک نیست.

آیا برای اتصال باید کتابخانه اختصاصی نصب کنیم

خیر. برای یک API مبتنی بر HTTP می توان درخواست را مستقیم ساخت. استفاده از کتابخانه اختصاصی به سازگاری و نیاز پروژه بستگی دارد.

چرا با پاسخ موفق هنوز پیامک دریافت نشده است

پذیرش درخواست با تحویل تفاوت دارد. ابتدا نتیجه عملیات و سپس گزارش وضعیت پیام را بررسی کنید.

آیا همین نمونه برای ارسال کد ورود کافی است

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

آیا باید پس از هر خطا درخواست را تکرار کنیم

خیر. خطاهای ورودی به اصلاح نیاز دارند و نتیجه نامشخص ارتباط باید پیش از تکرار بررسی شود.