niazpardazSms 1.0.2

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

NiazpardazSms SDK for Python

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

نصب

pip

pip install niazpardazSms

با پشتیبانی async (aiohttp)

pip install niazpardazSms[async]

با پشتیبانی httpx

pip install niazpardazSms[httpx]

همه وابستگی‌ها

pip install niazpardazSms[all]

شروع سریع

from niazpardaz_sms import NiazpardazSmsClient, SendResultCode

# ساخت کلاینت با API Key
client = NiazpardazSmsClient("YOUR_API_KEY")

# ارسال پیامک
result = client.send(
    from_number="10001234",
    to_number="09123456789",
    message="سلام از نیازپرداز!"
)

if result.result_code == SendResultCode.SEND_WAS_SUCCESSFUL:
    print(f"BatchSmsId: {result.batch_sms_id}")

امکانات

ارسال پیامک تکی

result = client.send(
    from_number="10001234",
    to_number="09123456789",
    message="متن پیامک",
    is_flash=False,
    send_delay=None
)

print(f"شناسه ارسال: {result.batch_sms_id}")
print(f"وضعیت: {result.result_code}")

ارسال گروهی (یک متن به چند شماره)

result = client.send_bulk(
    from_number="10001234",
    to_numbers=["09123456789", "09198765432"],
    message="پیام گروهی",
    is_flash=False
)

print(f"شناسه ارسال: {result.batch_sms_id}")
print(f"وضعیت: {result.result_code}")

ارسال LikeToLike (هر شماره پیام مخصوص خودش)

result = client.send_like_to_like(
    from_number="10001234",
    to_numbers=["09123456789", "09198765432"],
    messages=["سلام علی جان", "سلام رضا جان"]
)

print(f"SmsId: {result.sms_id}")

ارسال پیامک صوتی OTP

result = client.send_voice_otp(
    from_number="10001234",
    to_number="09123456789",
    otp="12345"
)

print(f"شناسه ارسال: {result.batch_sms_id}")
print(f"وضعیت: {result.result_code}")

گزارش تحویل ارسال گروهی

from niazpardaz_sms import DeliveryResultCode

delivery = client.get_batch_delivery(
    batch_sms_id=123456,
    page_index=1,
    page_size=100
)

if delivery.result_code == DeliveryResultCode.SUCCESS:
    for i, number in enumerate(delivery.numbers):
        print(f"{number}: {delivery.delivery_status[i]}")

گزارش تحویل ارسال LikeToLike

delivery = client.get_delivery_like_to_like(sms_id=789)

if delivery.result_code == DeliveryResultCode.SUCCESS:
    for i, number in enumerate(delivery.numbers):
        print(f"{number}: {delivery.delivery_status[i]}")

اعتبار

from niazpardaz_sms import CreditResultCode

credit = client.get_credit()
if credit.result_code == CreditResultCode.SUCCESS:
    print(f"اعتبار: {credit.credit}")

شماره‌های فرستنده

senders = client.get_sender_numbers()
for sender in senders.senders:
    print(sender)

تعداد پیامک‌های دریافتی

inbox_count = client.get_inbox_count(is_read=False)
print(f"تعداد: {inbox_count.inbox_count}")

لیست پیامک‌ها

message_result = client.get_messages(
    message_type=1,
    from_numbers="10001234",
    page_index=1,
    page_size=50
)

if message_result.result_code == 0:
    for message in message_result.messages:
        print(f"متن پیامک: {message.content}")

دریافت پیامک‌ها بر اساس بازه زمانی

from datetime import datetime, timedelta

message_result = client.get_messages_by_date_range(
    message_type=1,
    from_numbers="10001234",
    from_date=datetime.now() - timedelta(days=1),
    to_date=datetime.now()
)

if message_result.result_code == 0:
    for message in message_result.messages:
        print(f"متن پیامک: {message.content}")

لیست سیاه مخابرات (بررسی یک شماره)

is_black = client.number_is_in_telecom_blacklist("09123456789")
print(f"در لیست سیاه: {is_black.is_black}")

لیست سیاه مخابرات (استخراج شماره‌های لیست سیاه از یک لیست)

from niazpardaz_sms import BlacklistResultCode

blacklist = client.extract_telecom_blacklist_numbers(
    ["09123456789", "09198765432", "09351234567"]
)

if blacklist.result_code == BlacklistResultCode.SUCCESS:
    for number in blacklist.black_list_numbers:
        print(number)

بررسی محتوای پیامک

check = client.check_sms_content("متن پیامک تست")
print(f"متن معتبر است: {check.is_valid}")

---

استفاده Async

برای استفاده با فریم‌ورک‌های async مثل FastAPI، aiohttp یا Django async:

نصب وابستگی‌های async

pip install niazpardazSms[async]
# یا
pip install niazpardazSms[httpx]

مثال با FastAPI

from fastapi import FastAPI
from niazpardaz_sms import AsyncNiazpardazSmsClient, SendResultCode

app = FastAPI()

@app.post("/send-sms")
async def send_sms(to_number: str, message: str):
    async with AsyncNiazpardazSmsClient("YOUR_API_KEY") as client:
        result = await client.send(
            from_number="10001234",
            to_number=to_number,
            message=message
        )
        
        return {
            "success": result.result_code == SendResultCode.SEND_WAS_SUCCESSFUL,
            "batch_sms_id": result.batch_sms_id
        }

مثال با aiohttp

import asyncio
from niazpardaz_sms import AsyncNiazpardazSmsClient

async def main():
    async with AsyncNiazpardazSmsClient("YOUR_API_KEY") as client:
        # ارسال پیامک
        result = await client.send(
            from_number="10001234",
            to_number="09123456789",
            message="سلام!"
        )
        print(f"BatchSmsId: {result.batch_sms_id}")
        
        # دریافت اعتبار
        credit = await client.get_credit()
        print(f"اعتبار: {credit.credit}")

asyncio.run(main())

مثال با Django async

# views.py
from django.http import JsonResponse
from niazpardaz_sms import AsyncNiazpardazSmsClient, SendResultCode

async def send_sms_view(request):
    async with AsyncNiazpardazSmsClient("YOUR_API_KEY") as client:
        result = await client.send(
            from_number="10001234",
            to_number=request.GET.get("to"),
            message=request.GET.get("message")
        )
        
        return JsonResponse({
            "success": result.result_code == SendResultCode.SEND_WAS_SUCCESSFUL,
            "batch_sms_id": result.batch_sms_id
        })

استفاده با httpx

from niazpardaz_sms import AsyncNiazpardazSmsClient

async with AsyncNiazpardazSmsClient("YOUR_API_KEY", use_httpx=True) as client:
    result = await client.send(
        from_number="10001234",
        to_number="09123456789",
        message="سلام!"
    )

---

کدهای نتیجه

کدهای نتیجه ارسال (SendResultCode)

کد	مقدار	توضیحات
0	SEND_WAS_SUCCESSFUL	ارسال موفق ✅
1	INVALID_USER_NAME_OR_PASSWORD	نام کاربر یا رمز نامعتبر
2	USER_BLOCKED	کاربر مسدود
3	INVALID_SENDER_NUMBER	شماره فرستنده نامعتبر
4	LIMITATION_IN_DAILY_SEND	محدودیت روزانه
5	LIMITATION_IN_RECEIVER_COUNT	حداکثر 1000 گیرنده
6	SENDER_LINE_IS_INACTIVE	خط غیرفعال
7	SMS_CONTENT_FILTERED_WORDS_IS_INCLUDED	کلمات فیلتر شده
8	NO_CREDIT	اعتبار ناکافی
9	SYSTEM_BEING_UPDATED	در حال بروزرسانی
10	WEB_SERVICE_NO_ACTIVE	وب سرویس غیرفعال
11	NOT_IMPLEMENTED	پیاده سازی نشده
12	LIKE_TO_LIKE_SEND_RECEIVER_AND_MESSAGE_COUNT_SHOULD_EQUAL	تعداد پیام و شماره نابرابر
13	LIMITATION_IN_MESSAGE_CONTENT_COUNT	حداکثر 100 پیام
14	USER_TARIFF_NOT_DETERMINED	تعرفه تعریف نشده
15	DUPLICATE_SEND_SMS	ارسال تکراری
16	INVALID_NUMBER_EMPTY_OR_BLACK_LIST	شماره نامعتبر یا بلاک لیست
17	TEXT_NOT_FOUND	متن خالی
18	NOT_VALID_TEMPLATE_FOUND	مغایرت با قالب
19	USER_EXPIRED	کاربر منقضی
20	USER_IS_NOT_ACTIVE	کاربر غیرفعال
21	INVALID_PARAMETERS	پارامتر نامعتبر
22	IP_BLOCKED	آی پی بلاک شده
23	ENQUEUE_FAILED	خطا در صف ارسال
24	DUPLICATE_REQUEST_THRESHOLD	درخواست تکراری
25	INVALID_API_KEY	ApiKey نامعتبر
26	ERROR_CREATE_VOICE_FILE	خطا در ساخت فایل صوتی

کدهای نتیجه گزارش تحویل (DeliveryResultCode)

کد	مقدار	توضیحات
0	SUCCESS	موفق ✅
-1	SERVICE_CONNECTION_ERROR	خطا در ارتباط با سرویس دهنده
-2	INVALID_BATCH_SMS_ID	پیام با این کد وجود ندارد
-3	REPORT_EXPIRED	مهلت یک هفته ای گزارش پایان یافته
-4	MESSAGE_IN_QUEUE	پیام در صف ارسال مخابرات است
-5	TOO_EARLY	حداقل یک دقیقه بعد از ارسال اقدام نمایید
-6	IP_BLOCKED	آی پی بلاک شده
-7	INVALID_API_KEY	ApiKey نامعتبر

وضعیت تحویل پیامک (SmsDeliveryStatus)

کد	مقدار	توضیحات
0	SENT_TO_TELECOM	ارسال شده به مخابرات
1	DELIVERED	رسیده به گوشی ✅
2	NOT_DELIVERED	نرسیده به گوشی
3	SMS_FAILED	خطای مخابراتی
4	UNKNOWN_ERROR	خطای نامشخص
5	RECEIVED_BY_TELECOM	رسیده به مخابرات
6	NOT_RECEIVED_BY_TELECOM	نرسیده به مخابرات
7	BLACK_LISTED	مسدود شده توسط مقصد
8	UNKNOWN	نامشخص
9	REJECTED_BY_TELECOM	مخابرات پیام را مردود اعلام کرد
10	CANCELED	کنسل شده توسط اپراتور
11	NOT_SENT	ارسال نشده
12	NO_TELEGRAM	تلگرام ندارد
13	IN_QUEUE	در صف ارسال

---

مدیریت خطا

from niazpardaz_sms import NiazpardazSmsClient, NiazpardazApiException, SendResultCode

client = NiazpardazSmsClient("YOUR_API_KEY")

try:
    result = client.send("10001234", "09123456789", "تست")
    
    if result.result_code != SendResultCode.SEND_WAS_SUCCESSFUL:
        print(f"خطا: {result.result_code}")
except NiazpardazApiException as ex:
    print(f"خطای API: {ex.message}")
    print(f"کد خطا: {ex.error_code}")
except Exception as ex:
    print(f"خطای شبکه: {ex}")

---

استفاده در فریم‌ورک‌های مختلف

Flask

from flask import Flask, request, jsonify
from niazpardaz_sms import NiazpardazSmsClient, SendResultCode

app = Flask(__name__)
client = NiazpardazSmsClient("YOUR_API_KEY")

@app.route("/send-sms", methods=["POST"])
def send_sms():
    data = request.json
    result = client.send(
        from_number="10001234",
        to_number=data["to"],
        message=data["message"]
    )
    
    return jsonify({
        "success": result.result_code == SendResultCode.SEND_WAS_SUCCESSFUL,
        "batch_sms_id": result.batch_sms_id
    })

Django

# views.py
from django.http import JsonResponse
from django.views.decorators.http import require_POST
from niazpardaz_sms import NiazpardazSmsClient, SendResultCode
import json

client = NiazpardazSmsClient("YOUR_API_KEY")

@require_POST
def send_sms(request):
    data = json.loads(request.body)
    result = client.send(
        from_number="10001234",
        to_number=data["to"],
        message=data["message"]
    )
    
    return JsonResponse({
        "success": result.result_code == SendResultCode.SEND_WAS_SUCCESSFUL,
        "batch_sms_id": result.batch_sms_id
    })

Celery (Background Tasks)

from celery import Celery
from niazpardaz_sms import NiazpardazSmsClient

app = Celery('tasks', broker='redis://localhost:6379/0')

@app.task
def send_sms_task(to_number: str, message: str):
    client = NiazpardazSmsClient("YOUR_API_KEY")
    result = client.send(
        from_number="10001234",
        to_number=to_number,
        message=message
    )
    return result.batch_sms_id

---

سازگاری

• Python 3.7+
• Flask
• Django
• FastAPI
• aiohttp
• Celery
• و هر فریم‌ورک دیگری

مجوز

MIT License

پشتیبانی

• 📚 مستندات: https://niazpardaz-sms.com/webservice
• 🐛 گزارش باگ: GitHub Issues