خوش آمدید به مستندات وب سرویس SMS

یک راه‌حل کامل و حرفه‌ای برای یکپارچه‌سازی سرویس پیامک در اپلیکیشن‌های شما

JWT Authentication RESTful API Secure & Fast

سرعت بالا

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

🔒

امنیت کامل

احراز هویت با JWT و رمزنگاری قوی

📊

گزارش‌گیری دقیق

پیگیری کامل وضعیت ارسال پیامک‌ها

🎯

ارسال هدفمند

قابلیت ارسال تکی، گروهی و زمان‌بندی شده

شروع کار

خوش آمدید! این مستندات برای توسعه‌دهندگانی طراحی شده که می‌خواهند سرویس SMS را در اپلیکیشن‌های خود یکپارچه کنند. با استفاده از وب سرویس ما، می‌توانید به راحتی پیامک‌های خود را مدیریت و ارسال کنید.

توجه مهم: تمامی درخواست‌ها از طریق HTTP و با متدهای GET یا POST قابل ارسال هستند. برای داده‌های حجیم، استفاده از متد POST و ارسال داده در قالب FormData توصیه می‌شود.
Case Sensitivity: به بزرگی و کوچکی حروف در پارامترها دقت کنید. تمام پارامترها case-sensitive هستند.
dev@limoapp:~$ curl -X POST "https://deftsms.ir/api/sms/send/simple"
dev@limoapp:~$

پیش‌نیازها

قبل از شروع به کار، مطمئن شوید که موارد زیر را دارید:

آشنایی با JWT

JSON Web Token (JWT) یک استاندارد باز (RFC 7519) برای انتقال امن اطلاعات بین طرفین در قالب JSON است. این توکن‌ها به صورت دیجیتالی امضا می‌شوند و اعتبارسنجی آن‌ها آسان است.

مزایای JWT

  • • امنیت بالا
  • • حجم کم
  • • خودکفا و مستقل
  • • سازگاری با همه زبان‌ها

ساختار JWT

  • • Header (الگوریتم)
  • • Payload (داده‌ها)
  • • Signature (امضا)
الگوریتم اجباری: تمامی توکن‌های JWT باید با الگوریتم HS256 رمزنگاری شوند.

حساب کاربری

نام کاربری (username) شما که در تمام درخواست‌ها باید ارسال شود. این شناسه منحصر به فرد شما در سیستم است.

کلید خصوصی (Secret Key)

کلید خصوصی شما برای رمزنگاری توکن‌های JWT استفاده می‌شود. این کلید را هرگز با کسی به اشتراک نگذارید!

هشدار امنیتی: کلید خصوصی خود را در محیط production به صورت Environment Variable ذخیره کنید و از کامیت کردن آن در Git خودداری نمایید.

ارسال تکی

برای ارسال یک پیامک به یک شماره مشخص از این endpoint استفاده کنید.

POST https://deftsms.ir/api/sms/send/simple

پارامترهای ورودی

پارامتر نوع توضیحات وضعیت
username string نام کاربری حساب شما اجباری
token string توکن JWT تولید شده اجباری

داده‌های Payload برای JWT

پارامتر نوع توضیحات وضعیت
number string شماره موبایل گیرنده اجباری
message string متن پیامک اجباری

پاسخ (Response)

JSON Response
{
    "success": true,
    "error": false,
    "status": "success",
    "code": 200,
    "messages": [],
    "data": null,
    "total": 0
}

مثال عملی

ابتدا توکن JWT را در jwt.io بسازید:

ارسال تکی زماندار

برای ارسال پیامک در زمان مشخص (زمان‌بندی شده) از این endpoint استفاده کنید.

POST https://deftsms.ir/api/sms/send/simple_scheduled
فرمت زمان: زمان ارسال باید به فرمت میلادی Y-m-d H:i:s و با منطقه زمانی ایران/تهران باشد. مثال: 2024-03-21 14:30:00

داده‌های Payload

پارامتر نوع توضیحات وضعیت
number string شماره موبایل گیرنده اجباری
message string متن پیامک اجباری
scheduleDateTime string زمان ارسال (Y-m-d H:i:s) اجباری

ارسال گروهی

برای ارسال یک پیامک به چندین شماره به صورت همزمان (حداکثر 100 شماره در هر درخواست).

POST https://deftsms.ir/api/sms/send/multi
محدودیت تعداد: در هر درخواست حداکثر می‌توانید به 100 شماره پیامک ارسال کنید. برای تعداد بیشتر، درخواست‌های متعدد ارسال نمایید.

داده‌های Payload

پارامتر نوع توضیحات وضعیت
numbers array آرایه‌ای از شماره موبایل‌ها اجباری
message string متن پیامک اجباری
Payload Example
{
    "numbers": [
        "09123456789",
        "09367894561",
        "09151234567"
    ],
    "message": "پیام شما"
}

ارسال گروهی زماندار

ارسال پیامک به چندین شماره در زمان مشخص (حداکثر 100 شماره).

POST https://deftsms.ir/api/sms/send/multi_scheduled

داده‌های Payload

پارامتر نوع توضیحات وضعیت
numbers array آرایه شماره موبایل‌ها اجباری
message string متن پیامک اجباری
scheduleDateTime string زمان ارسال اجباری

ارسال متناظر

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

POST https://deftsms.ir/api/sms/send/correspond
نحوه عملکرد: اولین عنصر آرایه messages به اولین عنصر آرایه numbers ارسال می‌شود. بنابراین تعداد و ترتیب آرایه‌ها باید یکسان باشد.

داده‌های Payload

پارامتر نوع توضیحات وضعیت
numbers array آرایه شماره موبایل‌ها اجباری
messages array آرایه متن‌های پیامک اجباری
مثال
{
    "numbers": ["09123456789", "09367894561"],
    "messages": ["سلام آقای احمدی", "سلام خانم محمدی"]
}

دریافت مانده اعتبار

برای مشاهده مانده اعتبار ریالی حساب کاربری خود از این endpoint استفاده کنید.

POST https://deftsms.ir/api/user/credit/index

داده‌های Payload

پارامتر نوع توضیحات وضعیت
username string نام کاربری اجباری

پاسخ موفق

Success Response
{
    "success": true,
    "error": false,
    "status": "success",
    "code": 200,
    "messages": [],
    "data": "125000", // مانده اعتبار به ریال
    "total": 0
}

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

برای دریافت لیست پیامک‌های دریافتی (inbox) با قابلیت فیلتر بر اساس زمان و صفحه‌بندی.

POST https://deftsms.ir/api/sms/receive/index

داده‌های Payload

پارامتر نوع توضیحات وضعیت
limit integer تعداد رکورد (پیش‌فرض: 10) اختیاری
offset integer شروع از رکورد (پیش‌فرض: 0) اختیاری
startDateTime string از تاریخ (Y-m-d H:i:s) اختیاری
endDateTime string تا تاریخ (Y-m-d H:i:s) اختیاری

پاسخ موفق

Response
{
    "success": true,
    "error": false,
    "status": "success",
    "code": 200,
    "messages": [],
    "data": [
        {
            "number": "09123456789",
            "message": "متن پیامک",
            "dateCreated": "2024-01-15 14:30:00"
        }
    ],
    "total": 145
}

نمونه کدها

کدهای آماده برای پیاده‌سازی سریع در پروژه‌های خود

simple.php
<?php
    // مقادیر پیش نیاز
    $secret_key = "your-secret-key-here"; // کلید خصوصی برای ساختن JWT
    $username = "your-username-key-here"; // نام کاربری حساب کاربری شما
    $url = "https://deftsms.ir/api/sms/send/simple";  // آدرس وب سرویس

    // شروع فرایند تولید توکن JWT
    $header = [
        "typ" => "JWT",
        "alg" => "HS256"
    ];

    $header = json_encode($header);
    $header = base64_encode($header);

    $payload = [
        "number"=> "09156535299", // شماره موبایل گیرنده  پیامک
        "message"=> "test" // متن پیامک
    ];
    $payload = json_encode($payload);
    $payload = base64_encode($payload);

    $signature = hash_hmac("sha256", "{$header}.{$payload}", $secret_key, true);
    $signature = base64_encode($signature);

    $token = "{$header}.{$payload}.{$signature}"; // توکن تولید شده

    // پایان فرایند تولید توکن JWT

    // شروع فرایند درخواست

    // دیتای مورد ورودی مورد نیاز برای درخواست
    $data = array(
        "username"  => $username,
        "token"     => $token
    );

    $options = array(
        // use key "http" even if you send the request to https://...
        "http" => array(
            "header"  => "Content-type: application/x-www-form-urlencoded\r\n",
            "method"  => "POST",
            "content" => http_build_query($data)
        )
    );
    $context  = stream_context_create($options);
    $result = file_get_contents($url, false, $context);
    if ($result === FALSE) { /* Handle error */ }
    var_dump($result);
    // پایان فرایند درخواست