وب سرویس پیامک با پایتون؛ راهنمای توسعه‌دهندگان

این راهنما مکمل مستندات وب‌سرویس است و روی سه سناریوی رایج توسعه‌دهندگان پایتون تمرکز دارد: ارسال ساده، بررسی وضعیت، و ارسال OTP.

نصب پیش‌نیاز

# فقط به کتابخانه requests نیاز دارید
pip install requests

۱. ارسال یک پیامک ساده

import requests

API_KEY = "YOUR_API_KEY"
headers = {"Authorization": f"Bearer {API_KEY}"}

payload = {
    "line": "5000xxxxxx",
    "to": ["09121234567"],
    "text": "سفارش شما ثبت شد."
}
r = requests.post("https://api.free-sms.ir/v1/send", headers=headers, json=payload)
print(r.json())

۲. بررسی وضعیت تحویل

msg_id = r.json()["id"]
status = requests.get(f"https://api.free-sms.ir/v1/status/{msg_id}", headers=headers)
print(status.json())  # {'status': 'delivered'}

۳. ارسال کد یکبار مصرف (OTP)

otp_payload = {"to": "09121234567", "template": "login_otp"}
r2 = requests.post("https://api.free-sms.ir/v1/otp", headers=headers, json=otp_payload)
print(r2.json())

مدیریت خطا

همیشه کد وضعیت HTTP پاسخ را بررسی کنید؛ اگر کلید API نامعتبر یا اعتبار پنل تمام شده باشد، پاسخ با کد ۴۰۱ یا ۴۰۲ برمی‌گردد. پیشنهاد می‌شود یک تلاش مجدد (retry) با فاصله‌ی کوتاه برای خطاهای شبکه‌ای پیاده‌سازی کنید.

جمع‌بندی

• برای ارسال ساده از اندپوینت /send، برای OTP از /otp استفاده کنید؛ ترکیب این دو در یک پروژه رایج است (مثلاً OTP برای ورود و /send برای اطلاع‌رسانی سفارش).
• همیشه پاسخ HTTP را بررسی کنید؛ اعتماد کورکورانه به موفقیت درخواست باعث گم‌شدن خطاهای اعتبار یا کلید نامعتبر می‌شود.
• برای پروژه‌های Django/FastAPI، منطق ارسال را در یک ماژول جدا (sms_client.py) نگه دارید تا تست و نگهداری ساده‌تر شود.

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