شروع کار

مستندات موجود برای استفاده برنامه نویسان از وب سرویس می باشد. با داشتن پیش نیاز های ذکر شده در مستندات می توانید از قابلیت های موجود به وسیله ی درخواست های HTTP استفاده نمایید.
برای ارسال درخواست HTTP شما می توانید از متد های GET یا POST استفاده نمایید. در صورتی که درخواست به صورت GET بود باید داده های مورد نیاز از طریق URL parameters ارسال شود و در صورتی که از درخواست POST استفاده می کنید، داده های مورد نیاز را به می توانید به دو صورت URL parameters و FormData ارسال نمایید.
در صورتی که در هر متد قصد ارسال داده های زیادی را دارید(مثلا ارسال چندین متن و یا چندین شماره) توصیه می شود از متد POST استفاده نمایید و داده ها را در قالب FormData ارسال نمایید.
خروجی همه ی متد ها در قالب JSON خواهد بود
به بزرگی یا کوچکی پارامترهای ورودی و خروجی دقت شود
در این راهنما، به بررسی نمونه‌هایی از درخواست‌های API در قالب دستورات HTTP به وسیله Postman می‌پردازیم.

پیش نیاز ها

برای استفاده از این وب سرویس به موارد زیر نیاز دارید

آشنایی با JWT

JSON Web Token (JWT) یک استاندارد باز (RFC 7519) می باشد که روشی کم حجم و جامعی را برای انتقال امن اطلاعات بین طرفین، در قالب یک JSON object تعریف می کند. این اطلاعات تبادل شده، مطمئن و قابل اعتماد می باشند زیرا به صورت دیجیتالی امضا شده اند.
برای کسب اطلاعات بیشتر می توانید به سایت آن به آدرس https://jwt.io مراجعه نمایید.
برای اکثر زبان های برنامه نویسی کتابخانه های متعددی برای تولید JWT در دسترس می باشد. لیست کتابخانه های رسمی را می توانید از https://jwt.io/libraries دریافت نمایید
کلیه توکن های تولید شده با JWT باید با الگوریتم(Algorithm) HS256 رمزنگاری شود

حساب کاریری

در همه ی درخواست ها مقداری به نام username وجود دارد که باید توسط نام کاربری حساب کاربری شما تکمیل شود

کلید خصوصی

داده های ارسالی می بایست توسط JWT رمزگزاری شود. لذا شما برای این رمزنگاری نیاز به یک کلید خصوصی دارید که مخصوص شماست.
در نگهداری این کلید خصوصی کوشا باشید. مسئولیت نگهداری از این کلید به عهده صاحب حساب کاربری می باشد.

وب سرویس ارسال تکی

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

آدرس وب سرویس: https://deftsms.ir/api/sms/send/simple

ورودی ها

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

* داده های PAYLOAD برای ساختن توکن

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

خروجی ها

عنوان نوع توضیحات
success boolean در صورتی که درخواست شما موفق بود این مقدار true می باشد
error boolean در صورتی که درخواست شما با خطا همراه بود این مقدار true می باشد
status string وضعیت درخواست را در قالب رشته اعلام می‌کند(در صورت موفق بودن "success" و در صورت ناموفق بودن "error")
messages array of string([]string) لیستی از خطاهای موجود در درخواست شما در این قسمت بازگشت می شود

                            
//نمونه خروجی موفق
{
    "success": true,
    "error": false,
    "status": "success",
    "code": 200,
    "messages": [],
    "data": null,
    "total": 0
}

// نمونه خروجی ناموفق
{
    "success": false,
    "error": true,
    "status": "error",
    "code": 401,
    "messages": [
        "کاربر یافت نشد"
    ],
    "data": null,
    "total": 0
}
                            
                        

نمونه

ابتدا باید توکن JWT را مشابه تصویر زیر تولید نمایید.
نمونه توکن تولید شده

1- الگوریتم
2- دیتای ورودی
3- کلید خصوصی
4- کد تولید شده

5- آدرس وب سرویس
6- دیتای ورودی (در قسمت توکن، کد تولید شده در قسمت 4 را وارد نمایید)
7- خروجی درخواست

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

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

آدرس وب سرویس: https://deftsms.ir/api/sms/send/simple_scheduled

ورودی ها

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

* داده های PAYLOAD برای ساختن توکن

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

خروجی ها

عنوان نوع توضیحات
success boolean در صورتی که درخواست شما موفق بود این مقدار true می باشد
error boolean در صورتی که درخواست شما با خطا همراه بود این مقدار true می باشد
status string وضعیت درخواست را در قالب رشته اعلام می‌کند(در صورت موفق بودن "success" و در صورت ناموفق بودن "error")
messages array of string([]string) لیستی از خطاهای موجود در درخواست شما در این قسمت بازگشت می شود

وب سرویس ارسال گروهی

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

آدرس وب سرویس: https://deftsms.ir/api/sms/send/multi

ورودی ها

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

* داده های PAYLOAD برای ساختن توکن

عنوان نوع توضیحات وضعیت
numbers array of string([]string) شماره موبایل هایی که قصد ارسال پیامک را به آنها دارید اجباری
message string متن پیامک اجباری

خروجی ها

عنوان نوع توضیحات
success boolean در صورتی که درخواست شما موفق بود این مقدار true می باشد
error boolean در صورتی که درخواست شما با خطا همراه بود این مقدار true می باشد
status string وضعیت درخواست را در قالب رشته اعلام می‌کند(در صورت موفق بودن "success" و در صورت ناموفق بودن "error")
messages array of string([]string) لیستی از خطاهای موجود در درخواست شما در این قسمت بازگشت می شود

                            
//نمونه خروجی موفق
{
    "success": true,
    "error": false,
    "status": "success",
    "code": 200,
    "messages": [],
    "data": null,
    "total": 0
}

// نمونه خروجی ناموفق
{
    "success": false,
    "error": true,
    "status": "error",
    "code": 401,
    "messages": [
        "کاربر یافت نشد"
    ],
    "data": null,
    "total": 0
}
                            
                        

نمونه

ابتدا باید توکن JWT را مشابه تصویر زیر تولید نمایید.
نمونه توکن تولید شده

1- الگوریتم
2- دیتای ورودی
3- کلید خصوصی
4- کد تولید شده

5- آدرس وب سرویس
6- دیتای ورودی (در قسمت توکن، کد تولید شده در قسمت 4 را وارد نمایید)
7- خروجی درخواست

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

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

آدرس وب سرویس: https://deftsms.ir/api/sms/send/multi_scheduled

ورودی ها

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

* داده های PAYLOAD برای ساختن توکن

عنوان نوع توضیحات وضعیت
numbers array of string([]string) شماره موبایل هایی که قصد ارسال پیامک را به آنها دارید اجباری
message string متن پیامک اجباری
scheduleDateTime string زمان ارسال (به صورت تاریخ و ساعت میلادی با فرمت "Y-m-d H:i:s" باشد و موقعیت جفرافیایی ایران/تهران) اجباری

خروجی ها

عنوان نوع توضیحات
success boolean در صورتی که درخواست شما موفق بود این مقدار true می باشد
error boolean در صورتی که درخواست شما با خطا همراه بود این مقدار true می باشد
status string وضعیت درخواست را در قالب رشته اعلام می‌کند(در صورت موفق بودن "success" و در صورت ناموفق بودن "error")
messages array of string([]string) لیستی از خطاهای موجود در درخواست شما در این قسمت بازگشت می شود

وب سرویس ارسال متناظر

این وب سرویس مخصوص متناظر پیامک می باشد. یک رشته شماره و متن متناظر ارسال می شود و سیستم خودکار متن هر شماره را به آن شماره ارسال می کند. انتصاب متن ها به شماره ها بر اساس موقعیت آن متن در لیست متون می باشد.(حداکثر 100 شماره در هر فراخوانی)

آدرس وب سرویس: https://deftsms.ir/api/sms/send/correspond

ورودی ها

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

* داده های PAYLOAD برای ساختن توکن

عنوان نوع توضیحات وضعیت
numbers array of string([]string) شماره موبایل هایی که قصد ارسال پیامک را به آنها دارید اجباری
messages array of string ([]string) متن های پیامک اجباری

خروجی ها

عنوان نوع توضیحات
success boolean در صورتی که درخواست شما موفق بود این مقدار true می باشد
error boolean در صورتی که درخواست شما با خطا همراه بود این مقدار true می باشد
status string وضعیت درخواست را در قالب رشته اعلام می‌کند(در صورت موفق بودن "success" و در صورت ناموفق بودن "error")
messages array of string([]string) لیستی از خطاهای موجود در درخواست شما در این قسمت بازگشت می شود

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

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

آدرس وب سرویس: https://deftsms.ir/api/user/credit/index

ورودی ها

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

* داده های PAYLOAD برای ساختن توکن

عنوان نوع توضیحات وضعیت
username string نام کاربری که می‌خواهید مانده اعتبار آن را دریافت نمایید اجباری

خروجی ها

عنوان نوع توضیحات
success boolean در صورتی که درخواست شما موفق بود این مقدار true می باشد
error boolean در صورتی که درخواست شما با خطا همراه بود این مقدار true می باشد
status string وضعیت درخواست را در قالب رشته اعلام می‌کند(در صورت موفق بودن "success" و در صورت ناموفق بودن "error")
data string در صورت معتبر بودن درخواست مقدار اعتبار کاربر در این قسمت نمایش داده می شود. در صورت ناموفق بودن این مقدار null خواهد بود
messages array of string([]string) لیستی از خطاهای موجود در درخواست شما در این قسمت بازگشت می شود

وب سرویس دریافت پیامک

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

آدرس وب سرویس: https://deftsms.ir/api/sms/receive/index

ورودی ها

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

* داده های PAYLOAD برای ساختن توکن

عنوان نوع توضیحات وضعیت
limit string or integer حداکثر تعداد پیامک ها در هر درخواست (پیش فرض 10) اختیاری
offset string or integer شروع لیست درخواست از رکورد(پیش فرض 0) اختیاری
startDateTime string شروع زمان دریافت (به صورت تاریخ و ساعت میلادی با فرمت "Y-m-d H:i:s" باشد و موقعیت جفرافیایی ایران/تهران) اختیاری
endDateTime string پایان زمان دریافت (به صورت تاریخ و ساعت میلادی با فرمت "Y-m-d H:i:s" باشد و موقعیت جفرافیایی ایران/تهران) اختیاری

خروجی ها

عنوان نوع توضیحات
success boolean در صورتی که درخواست شما موفق بود این مقدار true می باشد
error boolean در صورتی که درخواست شما با خطا همراه بود این مقدار true می باشد
status string وضعیت درخواست را در قالب رشته اعلام می‌کند(در صورت موفق بودن "success" و در صورت ناموفق بودن "error")
data array of smsObject([]smsObject) لیستی از پیامک های دریافتی
total integer تعداد کل صندوق دریافت
messages array of string([]string) لیستی از خطاهای موجود در درخواست شما در این قسمت بازگشت می شود

نمونه کدها

نمونه ای از پیاده سازی وب سرویس ها در این قسمت موجود می باشد

نمونه کد 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);
    // پایان فرایند درخواست
    
                            

نمونه کد C#

ابتدا وب سرویس ما را به پروژه خود اضافه نمایید. در زیر کلاینت موجود است.

                                
    using Newtonsoft.Json;
    using System;
    using System.Collections.Generic;
    using System.Linq;
    using System.Net.Http;
    using System.Text;
    using System.Threading.Tasks;
    using System.IdentityModel;
    using System.Security;

    // Nuget  install-package  "System.IdentityModel.Tokens.Jwt"


    public class RestClientAsync
    {
        private const string endpoint = "https://deftsms.ir/api";
        private const string sendSimple = "sms/send/simple";
        private const string sendSimpleScheduled = "sms/send/simple_scheduled";
        private const string sendMulti = "sms/send/multi";
        private const string sendMultiScheduled = "sms/send/multi_scheduled";
        private const string sendCorrespond = "sms/send/correspond";
        private const string getCredit = "user/credit/index";
        private const string getSms = "sms/receive/index";
        private string UserName;
        private string SecretKey;

        public RestClientAsync(string username, string secret_key)
        {
            UserName = username;
            SecretKey = secret_key;
        }

        private async Task<RestResponse> makeRequestAsync(Dictionary<string, string> values, string op)
        {
            var content = new FormUrlEncodedContent(values);

            using (var httpClient = new HttpClient())
            {
                var response = await httpClient.PostAsync(endpoint + op, content);
                var responseString = await response.Content.ReadAsStringAsync();

                return JsonConvert.DeserializeObject<RestResponse>(responseString);
            }
        }
        private async Task<RestResponseReceive> makeRequestReceiveAsync(Dictionary<string, string> values, string op)
        {
            var content = new FormUrlEncodedContent(values);

            using (var httpClient = new HttpClient())
            {
                var response = await httpClient.PostAsync(endpoint + op, content);
                var responseString = await response.Content.ReadAsStringAsync();

                return JsonConvert.DeserializeObject<RestResponseReceive>(responseString);
            }
        }


        // دریافت پیامک
        public async Task<RestResponseReceive> GetSMSAsync(int offset, int limit)
        {

            var securityKey = new Microsoft.IdentityModel.Tokens.SymmetricSecurityKey(Encoding.UTF8.GetBytes(SecretKey));
            var credentials = new Microsoft.IdentityModel.Tokens.SigningCredentials(securityKey, "HS256");

            var header = new JwtHeader(credentials);
            var payload = new JwtPayload
                {
                    { "offset", offset},
                    { "limit", limit}
                };
            var secToken = new JwtSecurityToken(header, payload);
            var handler = new JwtSecurityTokenHandler();
            var token = handler.WriteToken(secToken);
            var values = new Dictionary<string, string>
                {
                    { "username", UserName },
                    { "token", token }
                };

            return await makeRequestReceiveAsync(values, getSms);
        }

        // ارسال تکی
        public async Task<RestResponse> SendSimpleAsync(string number, string message)
        {

            var securityKey = new Microsoft.IdentityModel.Tokens.SymmetricSecurityKey(Encoding.UTF8.GetBytes(SecretKey));
            var credentials = new Microsoft.IdentityModel.Tokens.SigningCredentials(securityKey, "HS256");

            var header = new JwtHeader(credentials);
            var payload = new JwtPayload
                {
                    { "number", number},
                    { "message", message}
                };
            var secToken = new JwtSecurityToken(header, payload);
            var handler = new JwtSecurityTokenHandler();
            var token = handler.WriteToken(secToken);
            var values = new Dictionary<string, string>
                {
                    { "username", UserName },
                    { "token", token }
                };

            return await makeRequestAsync(values, sendSimple);
        }

        // ارسال تکی زماندار
        public async Task<RestResponse> SendSimpleScheduledAsync(string number, string message,string scheduleDateTime)
        {

            var securityKey = new Microsoft.IdentityModel.Tokens.SymmetricSecurityKey(Encoding.UTF8.GetBytes(SecretKey));
            var credentials = new Microsoft.IdentityModel.Tokens.SigningCredentials(securityKey, "HS256");

            var header = new JwtHeader(credentials);
            var payload = new JwtPayload
                {
                    { "number", number},
                    { "message", message},
                    { "scheduleDateTime", scheduleDateTime}
                };
            var secToken = new JwtSecurityToken(header, payload);
            var handler = new JwtSecurityTokenHandler();
            var token = handler.WriteToken(secToken);
            var values = new Dictionary<string, string>
                {
                    { "username", UserName },
                    { "token", token }
                };

            return await makeRequestAsync(values, sendSimpleScheduled);
        }

        // ارسال گروهی
        public async Task<RestResponse> SendMultiAsync(string[] numbers, string message)
        {

            var securityKey = new Microsoft.IdentityModel.Tokens.SymmetricSecurityKey(Encoding.UTF8.GetBytes(SecretKey));
            var credentials = new Microsoft.IdentityModel.Tokens.SigningCredentials(securityKey, "HS256");

            var header = new JwtHeader(credentials);
            var payload = new JwtPayload
                {
                    { "numbers", numbers},
                    { "message", message}
                };
            var secToken = new JwtSecurityToken(header, payload);
            var handler = new JwtSecurityTokenHandler();
            var token = handler.WriteToken(secToken);
            var values = new Dictionary<string, string>
                {
                    { "username", UserName },
                    { "token", token }
                };

            return await makeRequestAsync(values, sendMulti);
        }

        // ارسال گروهی زماندار
        public async Task<RestResponse> SendMultiScheduledAsync(string[] numbers, string message,string scheduleDateTime)
        {

            var securityKey = new Microsoft.IdentityModel.Tokens.SymmetricSecurityKey(Encoding.UTF8.GetBytes(SecretKey));
            var credentials = new Microsoft.IdentityModel.Tokens.SigningCredentials(securityKey, "HS256");

            var header = new JwtHeader(credentials);
            var payload = new JwtPayload
                {
                    { "numbers", numbers},
                    { "message", message},
                    { "scheduleDateTime", scheduleDateTime}
                };
            var secToken = new JwtSecurityToken(header, payload);
            var handler = new JwtSecurityTokenHandler();
            var token = handler.WriteToken(secToken);
            var values = new Dictionary<string, string>
                {
                    { "username", UserName },
                    { "token", token }
                };
            return await makeRequestAsync(values, sendMultiScheduled);
        }

        public async Task<RestResponse> SendCorrespondAsync(string[] numbers, string[] messages)
        {

            var securityKey = new Microsoft.IdentityModel.Tokens.SymmetricSecurityKey(Encoding.UTF8.GetBytes(SecretKey));
            var credentials = new Microsoft.IdentityModel.Tokens.SigningCredentials(securityKey, "HS256");

            var header = new JwtHeader(credentials);
            var payload = new JwtPayload
                {
                    { "numbers", numbers},
                    { "messages", messages}
                };
            var secToken = new JwtSecurityToken(header, payload);
            var handler = new JwtSecurityTokenHandler();
            var token = handler.WriteToken(secToken);
            var values = new Dictionary<string, string>
                {
                    { "username", UserName },
                    { "token", token }
                };
            return await makeRequestAsync(values, sendCorrespond);
        }

        public async Task<RestResponse> GetCreditAsync()
        {

            var securityKey = new Microsoft.IdentityModel.Tokens.SymmetricSecurityKey(Encoding.UTF8.GetBytes(SecretKey));
            var credentials = new Microsoft.IdentityModel.Tokens.SigningCredentials(securityKey, "HS256");

            var header = new JwtHeader(credentials);
            var payload = new JwtPayload
                {
                    { "username", UserName}
                };
            var secToken = new JwtSecurityToken(header, payload);
            var handler = new JwtSecurityTokenHandler();
            var token = handler.WriteToken(secToken);
            var values = new Dictionary<string, string>
                {
                    { "username", UserName },
                    { "token", token }
                };
            return await makeRequestAsync(values, getCredit);
        }
    }


    //response class
    public class RestResponse
    {
        public bool success { get; set; }
        public bool error { get; set; }
        public string status { get; set; }
        public int code { get; set; }
        public string[] messages { get; set; }
        public string data { get; set; }
    }

    public class InboxMessage
    {
        public string number { get; set; }
        public string message { get; set; }
        public string dateCreated { get; set; }
    }
    public class RestResponseReceive
    {
        public bool success { get; set; }
        public bool error { get; set; }
        public string status { get; set; }
        public int code { get; set; }
        public string[] messages { get; set; }
        public InboxMessage[] data { get; set; }
        public int total { get; set; }
    }
                            

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

                                
    const string username = "your-username-key-here"; // نام کاربری حساب کاربری شما
    const string secret_key = your-secret-key-here"; // کلید خصوصی برای ساختن JWT
    const string number = "09156535299";  // شماره موبایل گیرنده  پیامک
    const string message = "test";  // متن پیامک

    RestClientAsync client = new RestClientAsync(username, secret_key);
	client.SendSimpleAsync(number, message); // برای ارسال ساده