پایتون پرطرفدارترین زبان برای توسعه سریع بک‌اند، میکروسرویس‌ها و هوش مصنوعی است. در این راهنمای جامع، نحوه پیاده‌سازی کلاینت استاندارد برای وب‌سرویس پیامکی فری اس ام اس با کدهای سنکرون (Requests) و آسنکرون (HTTPX)، ارسال کدهای اعتبارسنجی با خط خدماتی اشتراکی زیر ۲ ثانیه و ادغام در FastAPI و Django را فرا می‌گیرید.

پیش‌نیازها و نصب کتابخانه‌های مورد نیاز

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

pip install requests httpx pydantic

۱. ارسال کدهای اعتبارسنجی با الگوی پترن (OTP Verify)

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

import requests class FreeSmsClient: BASE_URL = "https://api.free-sms.ir/v1" def __init__(self, api_key: str): self.api_key = api_key self.headers = { "Authorization": f"Bearer {self.api_key}", "Content-Type": "application/json", "Accept": "application/json" } def send_otp(self, mobile: str, pattern_id: str, params: dict) -> dict: """ارسال کد اعتبارسنجی یکبار مصرف با خط خدماتی اشتراکی""" endpoint = f"{self.BASE_URL}/sms/verify" payload = { "receptor": mobile, "template_id": pattern_id, "variables": params } resp = requests.post(endpoint, json=payload, headers=self.headers, timeout=5) resp.raise_for_status() return resp.json() # نمونه اجرا client = FreeSmsClient("YOUR_FREE_SMS_API_KEY") result = client.send_otp("09121112233", "otp_login_v1", {"code": "84920"}) print(result)

۲. کلاینت با کارایی بالا و ناهمگام (Async / HTTPX)

در وب‌اپلیکیشن‌های پرترافیک و پروژه‌های مبتنی بر FastAPI، استفاده از توابع همگام باعث مسدود شدن حلقه رویداد (Event Loop) می‌شود. با کلاینت زیر می‌توانید هزاران پیامک را با استخر اتصال پایدار ارسال کنید:

import httpx class AsyncFreeSmsClient: BASE_URL = "https://api.free-sms.ir/v1" def __init__(self, api_key: str): self.api_key = api_key self.headers = { "Authorization": f"Bearer {self.api_key}", "Content-Type": "application/json" } async def send_bulk(self, sender: str, receptors: list[str], message: str) -> dict: """ارسال پیامک انبوه اطلاع‌رسانی به چندین شماره موبایل""" async with httpx.AsyncClient(timeout=8.0) as client: resp = await client.post( f"{self.BASE_URL}/sms/send", headers=self.headers, json={ "sender": sender, "receptors": receptors, "message": message } ) resp.raise_for_status() return resp.json()

۳. نمونه پیاده‌سازی بک‌اند در فریم‌ورک FastAPI

استفاده از BackgroundTasks در FastAPI این اطمینان را می‌دهد که پاسخ HTTP کاربر با تاخیر مواجه نشود و درخواست پیامک در پس‌زمینه پردازش گردد:

from fastapi import FastAPI, BackgroundTasks, HTTPException from pydantic import BaseModel app = FastAPI(title="Auth & SMS Gateway") sms = FreeSmsClient("YOUR_FREE_SMS_API_KEY") class PhoneAuthRequest(BaseModel): mobile: str def task_send_sms(mobile: str, otp_code: str): sms.send_otp(mobile, "otp_login_v1", {"code": otp_code}) @app.post("/api/auth/request-otp") def request_otp(data: PhoneAuthRequest, bg_tasks: BackgroundTasks): import secrets code = str(secrets.randbelow(90000) + 10000) # ذخیره کد در Redis با اکسپایری ۲ دقیقه bg_tasks.add_task(task_send_sms, data.mobile, code) return {"status": "success", "message": "کد اعتبارسنجی پیامک شد"}

۴. دریافت وب‌هوک گزارش تحویل (Delivery Status Webhook)

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

@app.post("/api/sms/webhook") async def sms_delivery_webhook(payload: dict): message_id = payload.get("message_id") status = payload.get("status") # DELIVRD, UNDELIV, REJECTD mobile = payload.get("receptor") # به‌روزرسانی دیتابیس با وضعیت نهایی print(f"Status for {mobile}: {status} (ID: {message_id})") return {"received": True}

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

کد HTTPپیام خطادلیل بروز خطاروش اصلاح در کدهای پایتون
200 OKsuccessعملیات با موفقیت انجام شدشناسه پیام (message_id) را ذخیره کنید
401 Unauthorizedinvalid_api_keyکلید API اشتباه استبررسی هدر Authorization و فرمت Bearer
402 Payment Requiredinsufficient_creditاعتبار شارژ پنل ناکافی استشارژ آنلاین یا فعال‌سازی هشدار شارژ
422 Unprocessableinvalid_mobileفرمت شماره موبایل نادرست استاعتبارسنجی با ریجکس r"^09[0-9]{9}$"
429 Rate Limittoo_many_requestsارسال بیش از حد مجاز در ثانیهاستفاده از سیستم صف Celery یا RabbitMQ
بهینه‌سازی هزینه و ترافیک: در پروژه‌های جنگو، توصیه می‌شود از کتابخانه celery یا django-q برای مدیریت صف پیامک‌ها استفاده کنید تا قطعی موقت اینترنت سرور اختلالی در پاسخ‌دهی به کاربران ایجاد نکند.

سوالات متداول

آیا برای استفاده از وب‌سرویس پایتون در فری اس ام اس باید هزینه جداگانه‌ای پرداخت کنم؟+

خیر، دسترسی به وب‌سرویس RESTful و کلید API در سامانه فری اس ام اس برای تمام کاربران کاملاً رایگان است و هیچ آبونمان ماهانه یا سالانه‌ای ندارد.

چگونه با پایتون پیامک اعتبارسنجی OTP را بدون مسدودی بلک‌لیست مخابرات ارسال کنیم؟+

با استفاده از اندپوینت پترن (/v1/sms/verify) و خط خدماتی اشتراکی رایگان فری اس ام اس، پیامک کد تایید شما در کمتر از ۳ ثانیه حتی به شماره‌هایی که دریافت پیامک تبلیغاتی را بسته‌اند ارسال می‌گردد.

تفاوت کلاینت همگام (requests) با کلاینت ناهمگام (httpx / aiohttp) در ارسال انبوه چیست؟+

کلاینت همگام requests رزوه اجرایی برنامه را در انتظار پاسخ سرور بلاک می‌کند؛ اما در فریم‌ورک‌های جدید مثل FastAPI با httpx.AsyncClient هزاران درخواست همزمان بدون بلاک شدن پردازنده در میلی‌ثانیه مدیریت می‌شوند.

چگونه در صورت کمبود شارژ یا خطای اعتبارسنجی در پایتون اکسپشن‌ها را هندل کنیم؟+

وب‌سرویس فری اس ام اس کدهای وضعیت استاندارد HTTP (مانند ۴۰۱ برای کلید اشتباه و ۴۰۲ برای اتمام شارژ) برمی‌گرداند. با متد response.raise_for_status() و بررسی فیلد status کد خطا را دریافت و لاگ کنید.

آیا می‌توان وب‌هوک وضعیت دلیوری پیامک را در FastAPI یا Django دریافت کرد؟+

بله، کافیست یک روت POST در FastAPI یا ویو در Django تعریف کنید و آدرس آن را در پنل فری اس ام اس ست نمایید تا وضعیت تحویل پیامک‌ها (DELIVRD, FAILED) بلادرنگ به سیستم شما مخابره شود.