niazpardazSms 1.0.2
کتابخانه رسمی پایتون برای کار با پنل پیامکی نیازپرداز
License: MIT
Requires Python: >=3.7
Keywords: sms, niazpardaz, پیامک, نیازپرداز, api, sdk, iran, persian, otp

# NiazpardazSms SDK for Python

کتابخانه رسمی پایتون برای کار با پنل پیامکی نیازپرداز

[![PyPI](https://img.shields.io/pypi/v/niazpardazSms.svg)](https://pypi.org/project/niazpardazSms)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Python](https://img.shields.io/pypi/pyversions/niazpardazSms.svg)](https://pypi.org/project/niazpardazSms)

## نصب

### pip
```bash
pip install niazpardazSms
```

### با پشتیبانی async (aiohttp)
```bash
pip install niazpardazSms[async]
```

### با پشتیبانی httpx
```bash
pip install niazpardazSms[httpx]
```

### همه وابستگی‌ها
```bash
pip install niazpardazSms[all]
```

## شروع سریع

```python
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}")
```

## امکانات

### ارسال پیامک تکی

```python
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}")
```

### ارسال گروهی (یک متن به چند شماره)

```python
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 (هر شماره پیام مخصوص خودش)

```python
result = client.send_like_to_like(
    from_number="10001234",
    to_numbers=["09123456789", "09198765432"],
    messages=["سلام علی جان", "سلام رضا جان"]
)

print(f"SmsId: {result.sms_id}")
```

### ارسال پیامک صوتی OTP

```python
result = client.send_voice_otp(
    from_number="10001234",
    to_number="09123456789",
    otp="12345"
)

print(f"شناسه ارسال: {result.batch_sms_id}")
print(f"وضعیت: {result.result_code}")
```

### گزارش تحویل ارسال گروهی

```python
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

```python
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]}")
```

### اعتبار

```python
from niazpardaz_sms import CreditResultCode

credit = client.get_credit()
if credit.result_code == CreditResultCode.SUCCESS:
    print(f"اعتبار: {credit.credit}")
```

### شماره‌های فرستنده

```python
senders = client.get_sender_numbers()
for sender in senders.senders:
    print(sender)
```

### تعداد پیامک‌های دریافتی

```python
inbox_count = client.get_inbox_count(is_read=False)
print(f"تعداد: {inbox_count.inbox_count}")
```

### لیست پیامک‌ها

```python
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}")
```

### دریافت پیامک‌ها بر اساس بازه زمانی

```python
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}")
```

### لیست سیاه مخابرات (بررسی یک شماره)

```python
is_black = client.number_is_in_telecom_blacklist("09123456789")
print(f"در لیست سیاه: {is_black.is_black}")
```

### لیست سیاه مخابرات (استخراج شماره‌های لیست سیاه از یک لیست)

```python
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)
```

### بررسی محتوای پیامک

```python
check = client.check_sms_content("متن پیامک تست")
print(f"متن معتبر است: {check.is_valid}")
```

---

## استفاده Async

برای استفاده با فریم‌ورک‌های async مثل FastAPI، aiohttp یا Django async:

### نصب وابستگی‌های async

```bash
pip install niazpardazSms[async]
# یا
pip install niazpardazSms[httpx]
```

### مثال با FastAPI

```python
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

```python
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

```python
# 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

```python
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 | در صف ارسال |

---

## مدیریت خطا

```python
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

```python
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

```python
# 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)

```python
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](https://github.com/NiazpardazSms/niazpardaz-sms-python/issues)