Niksms 1.2.0

niksms webservice

niksms Python SDK

این پکیج برای اتصال آسان به وب‌سرویس پیامک Kendez.NikSms (نسخه REST و gRPC) در پایتون طراحی شده است.

This package provides an easy-to-use Python SDK for connecting to the Kendez.NikSms SMS web service (REST & gRPC).

نصب / Installation

pip install niksms

ویژگی‌ها / Features

• اتصال به REST API و gRPC
• قابل استفاده در پروژه‌های مختلف پایتون
• استفاده از آدرس‌های ثابت و قابل اعتماد
• پشتیبانی از تمام متدهای ارسال پیامک (تکی، گروهی، PTP، OTP)
• دریافت وضعیت پیامک‌ها و اطلاعات پنل

استفاده سریع / Quick Usage

REST Example

from niksms import NiksmsRestClient

client = NiksmsRestClient(api_key="YOUR_API_KEY")

# ارسال پیامک تکی
result = client.send_single(sender_number="5000...", phone="0912...", message="کد تایید شما: 1234")
print(result)

# دریافت اعتبار
credit = client.get_credit()
print(credit)

gRPC Example

from niksms import NiksmsGrpcClient

client = NiksmsGrpcClient(api_key="YOUR_API_KEY")

# ارسال پیامک تکی
result = client.send_single(sender_number="5000...", phone="0912...", message="کد تایید شما: 1234")
print(result)

# دریافت اعتبار
credit = client.get_credit()
print(credit)

مستندات کامل / Complete Documentation

متدهای ارسال پیامک / SMS Sending Methods

1. ارسال پیامک تکی / Send Single SMS

REST:

from niksms import NiksmsRestClient

client = NiksmsRestClient(api_key="YOUR_API_KEY")

result = client.send_single(
    sender_number="50004001",           # شماره فرستنده
    phone="09123456789",                # شماره گیرنده
    message="سلام! این یک پیام تست است.",  # متن پیام
    message_id="unique_id_123",         # شناسه یکتا (اختیاری)
    send_date="2024-01-01T10:30:00",    # تاریخ ارسال (اختیاری)
    send_type=1                         # نوع ارسال (اختیاری)
)
print(result)

gRPC:

from niksms import NiksmsGrpcClient

client = NiksmsGrpcClient(api_key="YOUR_API_KEY")

result = client.send_single(
    sender_number="50004001",
    phone="09123456789", 
    message="سلام! این یک پیام تست است.",
    message_id="unique_id_123",
    send_date="2024-01-01T10:30:00",
    send_type=1
)
print(result)

2. ارسال پیامک گروهی / Send Group SMS

REST:

recipients = [
    {"Phone": "09123456789", "MessageId": "msg_001"},
    {"Phone": "09123456790", "MessageId": "msg_002"},
    {"Phone": "09123456791", "MessageId": "msg_003"}
]

result = client.send_group(
    sender_number="50004001",
    message="پیام گروهی برای همه کاربران",
    recipients=recipients,
    send_date="2024-01-01T10:30:00",
    send_type=1
)
print(result)

gRPC:

recipients = [
    {"Phone": "09123456789", "MessageId": "msg_001"},
    {"Phone": "09123456790", "MessageId": "msg_002"},
    {"Phone": "09123456791", "MessageId": "msg_003"}
]

result = client.send_group(
    sender_number="50004001",
    message="پیام گروهی برای همه کاربران",
    recipients=recipients,
    send_date="2024-01-01T10:30:00",
    send_type=1
)
print(result)

3. ارسال PTP (هر نفر پیام متفاوت) / Send PTP SMS

REST:

recipients = [
    {"Phone": "09123456789", "Message": "سلام علی", "MessageId": "ptp_001"},
    {"Phone": "09123456790", "Message": "سلام رضا", "MessageId": "ptp_002"},
    {"Phone": "09123456791", "Message": "سلام مریم", "MessageId": "ptp_003"}
]

result = client.send_ptp(
    sender_number="50004001",
    recipients=recipients,
    send_date="2024-01-01T10:30:00",
    send_type=1
)
print(result)

gRPC:

recipients = [
    {"Phone": "09123456789", "Message": "سلام علی", "MessageId": "ptp_001"},
    {"Phone": "09123456790", "Message": "سلام رضا", "MessageId": "ptp_002"},
    {"Phone": "09123456791", "Message": "سلام مریم", "MessageId": "ptp_003"}
]

result = client.send_ptp(
    sender_number="50004001",
    recipients=recipients,
    send_date="2024-01-01T10:30:00",
    send_type=1
)
print(result)

4. ارسال پیامک OTP / Send OTP SMS

REST:

result = client.send_otp(
    sender_number="50004001",
    phone="09123456789",
    message="کد تایید شما: 1234",
    message_id="otp_001",
    send_date="2024-01-01T10:30:00",
    send_type=1
)
print(result)

gRPC:

result = client.send_otp(
    sender_number="50004001",
    phone="09123456789",
    message="کد تایید شما: 1234",
    message_id="otp_001",
    send_date="2024-01-01T10:30:00",
    send_type=1
)
print(result)

متدهای دریافت اطلاعات / Information Methods

1. دریافت اعتبار / Get Credit

REST:

credit_info = client.get_credit()
print(f"اعتبار باقی‌مانده: {credit_info}")

gRPC:

credit_info = client.get_credit()
print(f"اعتبار باقی‌مانده: {credit_info}")

2. دریافت تاریخ انقضای پنل / Get Panel Expire Date

REST:

expire_date = client.get_panel_expire_date()
print(f"تاریخ انقضای پنل: {expire_date}")

gRPC:

expire_date = client.get_panel_expire_date()
print(f"تاریخ انقضای پنل: {expire_date}")

3. دریافت وضعیت پیامک‌ها / Get SMS Status

REST:

message_ids = ["msg_001", "msg_002", "msg_003"]
status = client.get_sms_status(message_ids)
print(f"وضعیت پیامک‌ها: {status}")

gRPC:

message_ids = ["msg_001", "msg_002", "msg_003"]
status = client.get_sms_status(message_ids)
print(f"وضعیت پیامک‌ها: {status}")

مثال کامل / Complete Example

from niksms import NiksmsRestClient, NiksmsGrpcClient
import time

# تنظیمات
API_KEY = "YOUR_API_KEY"
SENDER_NUMBER = "50004001"

# استفاده از REST API
print("=== REST API Example ===")
rest_client = NiksmsRestClient(api_key=API_KEY)

# ارسال پیامک تکی
single_result = rest_client.send_single(
    sender_number=SENDER_NUMBER,
    phone="09123456789",
    message="سلام! این یک پیام تست از REST API است."
)
print("Single SMS Result:", single_result)

# ارسال پیامک گروهی
group_recipients = [
    {"Phone": "09123456789", "MessageId": "group_001"},
    {"Phone": "09123456790", "MessageId": "group_002"}
]
group_result = rest_client.send_group(
    sender_number=SENDER_NUMBER,
    message="پیام گروهی از REST API",
    recipients=group_recipients
)
print("Group SMS Result:", group_result)

# دریافت اعتبار
credit = rest_client.get_credit()
print("Credit:", credit)

# دریافت وضعیت پیامک‌ها
status = rest_client.get_sms_status(["group_001", "group_002"])
print("Status:", status)

# استفاده از gRPC API
print("\n=== gRPC API Example ===")
try:
    grpc_client = NiksmsGrpcClient(api_key=API_KEY)
    
    # ارسال پیامک OTP
    otp_result = grpc_client.send_otp(
        sender_number=SENDER_NUMBER,
        phone="09123456789",
        message="کد تایید شما: 1234",
        message_id="otp_001"
    )
    print("OTP SMS Result:", otp_result)
    
    # دریافت اطلاعات پنل
    panel_info = grpc_client.get_panel_expire_date()
    print("Panel Expire Date:", panel_info)
    
except Exception as e:
    print(f"gRPC Error: {e}")

مدیریت خطا / Error Handling

from niksms import NiksmsRestClient
import requests

client = NiksmsRestClient(api_key="YOUR_API_KEY")

try:
    result = client.send_single(
        sender_number="50004001",
        phone="09123456789",
        message="پیام تست"
    )
    print("Success:", result)
    
except requests.exceptions.HTTPError as e:
    print(f"HTTP Error: {e}")
except requests.exceptions.ConnectionError as e:
    print(f"Connection Error: {e}")
except Exception as e:
    print(f"General Error: {e}")

نکات مهم / Important Notes

1. API Key: کلید API خود را از پنل کاربری دریافت کنید
2. شماره فرستنده: شماره فرستنده باید از شماره‌های مجاز پنل شما باشد
3. نوع ارسال: مقادیر مختلف send_type برای انواع مختلف پیامک
4. تاریخ ارسال: فرمت تاریخ باید YYYY-MM-DDTHH:MM:SS باشد
5. شناسه پیام: برای پیگیری وضعیت پیامک‌ها، شناسه یکتا تعیین کنید

پشتیبانی / Support

برای پشتیبانی و راهنمایی بیشتر با تیم فنی تماس بگیرید. 021-74552000

نسخه / Version: 1.0.0
آخرین به‌روزرسانی / Last Update: 2024