راهنمای سرويس HTTP v2

پياده‌سازی شده به صورت REST/JSON

آغاز به کار

مقدمه

سرويس ‍HTTP v2 بهينه‌سازی‌شده‌ی سرويس HTTP v1 با متدهای REST و به صورت امن HTTPS، طراحی شده و به راحتی در همه‌ی زبان‌های برنامه‌نويسی قابل استفاده است. به دلیل سربار کم این سرويس، پهنای باند مصرفی در آن بسیار اندک خواهد بود. شایان ذکر است در این سرويس نیز تنها از UTF-8 پشتيبانی می‌شود.
افزون بر امکانات نسخه‌ی v1 امکان در‌یافت پيامک‌های ورودی نيز در اين سرويس فراهم شده است.
همانند نسخه v1، در اين سرويس نيز سامانه به ازای هر پيامک ارسالی، شناسه‌ای یکتا جهت پيگیری وضعيت ارایه می‌نمايد. همچنین برای افزايش سرعت ارسال می‌توانيد از فراخوانی‌های همزمان استفاده نماييد.

نکته‌ها

  1. بیشینه تعداد شماره گيرنده در درخواست‌ها يک‌صد (۱۰۰) عدد است. ارسال بيش از این تعداد با کد خطا مواجه خواهد شد
  2. در پاسخ همه‌ی متدها ، پارامتر status نشانگر وضعيت درخواست خواهد بود. مقدار صفر به معنای انجام بدون خطای درخواست و هر عدد غير از صفر کد خطای مربوطه است.

آغاز کار با سرويس

گام اول: ايجاد حساب کاربری و ورود به سامانه‌ی پیام‌دهی مگفا

پس از ايجاد حساب کاربری شما در سامانه‌‌ی پيام‌دهی مگفا، می‌توانيد با اطلاعات ورود (نام‌ کاربری/رمزعبور/دامنه) خود، به پنل سامانه‌ی پيام‌دهی مگفا وارد شويد.

گام دوم: فعال‌سازی شماره

جهت فعال‌سازی ارسال پیامک، کافی است تا با مراجعه به منوی «مديریت حساب»/«شماره‌ها»، در برگه‌ی «اطلاعات شماره‌ها» مشخصات استفاده‌کننده‌ی نهايی شماره را وارد نمايید. پس از ثبت موفق، این اطلاعات برای بررسی به سامانه‌ی احراز هويت ارسال شده و پس از لحظاتی در صورت درست بودن اطلاعات، وضعیت آن به تاييد شده (تيک سبز) تغيير خواهد یافت.

گام سوم: دريافت رمزعبور (گذر واژه) سرويس.

پس از ورود به سامانه، با مراجعه به منوی «مديریت حساب»/«رمز عبور و امنيت»، می‌توانيد در برگه‌ی «رمز عبور سرويس‌ها» از سامانه رمزی دريافت نمايید که در فراخوانی سرويس قابل استفاده خواهد بود. برای این منظور باید رمز اصلی را که هنگام ورود به سامانه وارد نموده‌اید بار ديگر وارد نماييد تا به صورت خودکار رمز عبور سرويس برای شما توليد شود. پس از توليد در هنگام فراخوانی سرويس، از رمز سرويس توليد شده استفاده نماييد.

گام چهارم: معرفی آی‌پی‌های معتبر

افزون بر فراخوانی سرويس به صورت HTTPS، در صورت نياز با مراجعه به منوی «مديریت حساب»/«رمز عبور و امنيت»، می‌توانيد در برگه‌ی «آی‌پی‌های معتبر» اقدام به فعال‌سازی بررسی و همچنین ثبت آی‌پی(های) مبدا نماييد. بدیهی است با فعال‌سازی این بخش درخواست‌هایی با مبدا غير از آی‌پی‌های معرفی‌شده با پیغام خطا مواجه شده و سامانه از پاسخ‌گویی به این درخواست‌ها خودداری می‌نمايد.

احراز هويت

احراز هويت اين سرويس بر اساس ارسال نام‌کاربری، رمز عبور سرويس و دامنه در سرایند HTTP با کليد Authorization و به صورت HTTP Basic Authentication است که در آن username به صورت ترکيب «نام‌کاربری به همراه دامنه» و password نيز همان رمز عبور سرويس ، به صورت زير است:

USERNAME/DOMAIN:PASSWORD

 

GET https://sms.magfa.com/api/http/sms/v2

Authorization: Basic VVNFUk5BTUUvRE9NQUlOOlBBU1NXT1JECg==

فشرده‌سازی

برای کاهش پهنای باند مصرفی و همچنين افزايش سرعت ارسال اطلاعات در شبکه، امکان فشرده‌سازی درخواست‌ها و پاسخ‌ها وجود دارد. نحوه‌ی به کارگيری این قابليت در نمونه کدها نشان داده شده است

متدهای HTTP

متد HTTPتوضيحات
GETهمه‌ی متدها به جز ارسال پيامک
POSTتنها متد ارسال پيامک

متدها

متدهای پیاده‌سازی‌شده به شرح زير است:

متدتوضيحات
balanceدريافت مانده اعتبار حساب
sendارسال پيامک به يک یا چند گيرنده (حداکثر يک‌صد (۱۰۰) عدد)
‫‪midدريافت شناسه یکتای پيامک متناظر با شناسه کاربر
‫‪statusesپيگيری وضعيت نهایی پيامک
‫‪messagesدریافت پیامک‌های ورودی (حداکثر يک‌صد (۱۰۰) عدد)

متد balance

از اين متد برای دريافت مانده اعتبار حساب استفاده می‌شود.

URL

https://sms.magfa.com/api/http/sms/v2/balance

پارامترها

ندارد

خروجی

به صورت JSON به شکل زير / کدهای خطا

{
    "status" : 0,
    "balance" : 1000
}
{
    "status" : 18,
    "balance" : null
}
پارامترنوعتوضيحات
statusintstatus نشانگر وضعيت درخواست خواهد بود. مقدار صفر به معنای انجام بدون خطای درخواست و هر عدد غير از صفر کد خطای مربوطه است.
balancelongمانده اعتبار

نمونه‌کد

curl
# bash

# credentials username='username' password='password' domain='domain'

# call curl --basic --user "$username/$domain:$password" \     -H 'Accept: application/json' \     'https://sms.magfa.com/api/http/sms/v2/balance'
php
// credentials
$username = "username";
$password = "password";
$domain = "magfa";

// url $url = 'https://sms.magfa.com/api/http/sms/v2/balance';

// Initializes a new cURL session $ch = curl_init($url);

// Set the CURLOPT options curl_setopt($ch, CURLOPT_HEADER, FALSE);

// JSON curl_setopt($ch, CURLOPT_HTTPHEADER, ['Accept: application/json']);

// Basic Auth curl_setopt($ch, CURLOPT_USERPWD, $username."/".$domain . ":" . $password);

// Set the CURLOPT_RETURNTRANSFER option to true curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);

// call $response = curl_exec($ch); var_dump(json_decode($response, true));
java
/*
* Java samples are made with glassfish jersey-client
*/

// Credentials String username = "username"; String password = "password"; String domain = "domain";

// Url String url = "https://sms.magfa.com/api/http/sms/v2/";

// Auth HttpAuthenticationFeature feature = HttpAuthenticationFeature.basic(username + "/" + domain, password);

// Client Client client = ClientBuilder.newBuilder()     .register(feature)     .build();

// call CreditResult response = client.target(url)     .path("balance/")     .request(MediaType.APPLICATION_JSON)     .get(CreditResult.class);

if(response.getStatus() != 0 )     System.out.println("error: " + response.getStatus()); else     System.out.println("mid: " + response.getBalance());
python
#
# Python samples are made with Requests: HTTP for Humans
#
# https://requests.readthedocs.io/en/master/
#
import requests

url = "https://sms.magfa.com/api/http/sms/v2/balance" headers = {'accept': "application/json", 'cache-control': "no-cache"}

# credentials username = "username" password = "password" domain = "domain"

# call response = requests.get(url, headers=headers, auth=(username + '/' + domain, password)) print(response.json())
C#
/**
* C# samples are made with RestSharp
* REST API client library for .Net
*
* https://restsharp.dev/
*/

using RestSharp; using RestSharp.Authenticators;

// Credentials string username = "username"; string password = "password"; string domain = "magfa";

// Client var client = new RestClient("https://sms.magfa.com/api/http/sms/v2/balance");

// Auth client.Authenticator = new HttpBasicAuthenticator(username + "/" + domain, password);

// Request var request = new RestRequest(Method.GET); request.AddHeader("cache-control", "no-cache"); request.AddHeader("accept", "application/json");

// Call IRestResponse response = client.Execute(request);

متد send

برای ارسال يک يا چند پيامک به يک یا چند گيرنده (حداکثر ۱۰۰ عدد) از اين متد می‌توان استفاده کرد. مقدار بازگشتی این متد حاوی آرایه‌ای است که مقادير آن نشانگر شرايط درخواست است بدین ترتيب که اگر پارامتر‌ها صحيح باشند و پيامک به صورت موفقيت‌آميز در سيستم پيام‌دهی قرار گيرد به ازای هر پيامک، شناسه يکتای پيامک، شناسه کاربر، تعداد بخش، تعرفه، الفبا (DEFAULT برای لاتین و UCS2 برای فارسی) به همراه شماره گیرنده يا کد خطا به همراه شناسه کاربر و شماره گيرنده در خروجی قرار خواهد گرفت.
ارسال پيامک به دو صورت ارسال پارامترها به صورت JSON و همچنین FORM قابل انجام است.
همچنین همه‌ی پارامترها به صورت آرایه بوده و امکان ارسال به صورت یک به چند (درصورتی که تعداد گیرندگان چند عدد باشد و بقیه پارامتر‌ها يکی)، و چند به چند (در صورتی که پارامترهای فرستنده، گيرنده و متن چندين عدد و به تعداد برابر) وجود دارد.

URL

https://sms.magfa.com/api/http/sms/v2/send

پارامترها

تمامی پارامترها به صورت URL-ENCODED ارسال شوند

پارامترنوعاجباری؟توضيحات
sendersstringبلهآرايه‌ای از فرستنده
recipientsstringبلهآرايه‌ای از گيرنده
messagesstringبلهآرايه‌ای از پيام
encodingsintآرايه‌ای از يکی از مقادير 0 (تشخيص خودکار زبان پیامک[پيش فرض])، 2 (فارسی)، 5 (ارسال به صورت 8BIT) و 6 (ارسال به صورت BINARY)
uidslongآرايه‌ای از شناسه‌ی یکتای کاربر
udhsstringآرايه‌ای از UDH (برای اطلاعات بيشتر به مستند UDH مراجعه نماييد)
فرستنده

شماره فرستنده به یکی از حالت‌های زير قابل استفاده است:

  • 3000xxxxxx
  • 983000xxxxxx
  • +983000xxxxxx
گيرنده

شماره‌ی گيرنده را به صورت‌های زير می‌توانيد مورد استفاده قرار دهيد.

  • 09xxxxxxxxx
  • 989xxxxxxxxx
  • +989xxxxxxxxx
  • 9xxxxxxxxx
پيام

متن پيامک بايد به صورت UTF-8 باشد. بر اساس نوع متن (فارسی، لاتین و باينری)، طول متن و نيز با توجه به تعرفه‌ی تخصیص‌داده‌شده به حساب، هزينه‌ی پيامک تشخيص داده‌شده و از مانده اعتبار کسر می‌گردد. با توجه به محدود بودن حجم پیامک در استاندارد شبکه‌های تلفن همراه (۱۴۰ بايت)، شرکت مگفا به صورت خودکار و در صورت نياز (طولانی بودن متن پيامک) اقدام به شکستن متن طولانی به تعداد بخش‌های مناسب می‌نمايد.
طول استاندارد يک پيامک فارسی ۷۰ کاراکتر ( هر کاراکتر ۲ بايت)، پيامک باينری ۱۴۰ بايت و لاتین ۱۶۰ کاراکتر (هر کاراکتر ۷ بيت) است. وجود حتی يک کاراکتر چند بايتی (غير ASCII) منجر به تشخيص پيامک به صورت فارسی خواهد شد تا متن ارسالی به درستی ارسال گردد.
با توجه به این که گوشی برای تشخيص بخش‌های یک پيامک نياز به اطلاعاتی دارد، قسمتی از حجم پيامک (معمولا ۶ بايت از ۱۴۰ بایت) صرف این اطلاعات خواهد شد. در اين صورت برای پيامک‌های طولانی هر بخش پيامک فارسی ۶۷ و هر بخش پيامک لاتين ۱۵۳ کاراکتر می‌تواند داشته باشد.

خروجی

مشخصات پيامک‌های ارسالی به صورت زیر / کدهای خطا

{
    "status" : 0,
    "messages" : [
        { "status" : 13, "userId" : "1223", "recipient" : "98912xxxxxxx" },
        { "status" : 0, "id": 111111111, "userId" : 1224, "parts": 3, "tariff": 160.00, "alphabet": "UCS2", "recipient" : "98913xxxxxxx"}
    ]
}
{
    "status" : 19,
    "messages" : []
}
پارامترنوعتوضيحات
statusintstatus نشانگر وضعيت درخواست خواهد بود. مقدار صفر به معنای انجام بدون خطای درخواست و هر عدد غير از صفر کد خطای مربوطه است.
messagesarrayنتيجه‌‌ی پردازش پيامک‌های ارسالی
پارامترنوعتوضيحات
statusintstatus نشانگر وضعيت درخواست خواهد بود. مقدار صفر به معنای انجام بدون خطای درخواست و هر عدد غير از صفر کد خطای مربوطه است.
idlongشناسه يکتای پیامک
userIdlongشناسه‌ی یکتای کاربر
partsintتعداد بخش‌های پيامک
tarifffloatتعرفه
alphabetstringDEFAULT برای لاتین و UCS2 برای فارسی
recipientstringگيرنده

نمونه‌کد

curl
# bash

# credentials username='username' password='password' domain='domain'

# post json data curl --basic --user "$username/$domain:$password" \     -H 'Accept: application/json' \     -H "Content-Type: application/json" \     -d '{"senders": ["3000xx", "3000xxxxxxxx"], "messages":["test msg", "msg 2"],"recipients":["0912xxxxxxx","0903xxxxxxx"]}' \     'https://sms.magfa.com/api/http/sms/v2/send'

# or 1post form data curl --basic --user "$username/$domain:$password" \     -H 'Accept: application/json' \     -d 'senders=3000xx&senders=3000xxxxxxxx&messages=test msg&messages=msg 2&recipients=0912xxxxxxx&recipients=0903xxxxxxx' \     'https://sms.magfa.com/api/http/sms/v2/send'
php
// credentials
$username = "username";
$password = "password";
$domain = "magfa";

// url $url = 'https://sms.magfa.com/api/http/sms/v2/send';

// data $data = [     "senders" => ["3000xx", "3000xxxxxxxx"],     "messages" => ["test msg", "msg 2"],     "recipients" => ["0912xxxxxxx","0903xxxxxxx"] ];

// Initializes a new cURL session $ch = curl_init($url);

$header = ['Accept: application/json'];

// Set the CURLOPT options curl_setopt($ch, CURLOPT_HEADER, FALSE); // GZIP Decompression curl_setopt($ch,CURLOPT_ENCODING , "gzip");

// Basic Auth curl_setopt($ch, CURLOPT_USERPWD, $username."/".$domain . ":" . $password);

// Set the CURLOPT_RETURNTRANSFER option to true curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE); // // IF want send JSON { $post_data = json_encode($data); // IF want send GZipped $post_data = gzencode($post_data); $header[] = 'Content-Encoding: gzip'; //} // ELSE IF POST Data { // $post_data = preg_replace('/%5B[0-9]+%5D=/', '=', http_build_query($data)); // } // // Attach our encoded data string to the POST fields. curl_setopt($ch, CURLOPT_POSTFIELDS, $post_data); // set headers curl_setopt($ch, CURLOPT_HTTPHEADER, $header);

// call $response = curl_exec($ch); curl_close($ch); var_dump(json_decode($response, true));
java
/*
* Java samples are made with glassfish jersey-client
*/

// Credentials String username="username"; String password="password"; String domain="domain";

// Url String url="https://sms.magfa.com/api/http/sms/v2/";

// Auth HttpAuthenticationFeature feature=HttpAuthenticationFeature.basic(username+"/"+domain,password);

// Client Client client=ClientBuilder.newBuilder()     .register(feature)     // enable GZIP Compression accepting data     .register(EncodingFilter.class)     .register(GZipEncoder.class)     // enable GZIP Compression sending data     .property(ClientProperties.USE_ENCODING,"gzip")     .build();

// ----- Data ----- @XmlRootElement class Data {     List<String>messages=new ArrayList();     List<String>recipients=new ArrayList();     List<String>senders=new ArrayList();     List<String>uids=new ArrayList();     List<String>encodings=new ArrayList();     List<String>udhs=new ArrayList(); }

Data data = new Data(); // senders data.senders.add("3000xx"); data.senders.add("3000xxxxxxxx"); // messages data.messages.add("test msg"); data.messages.add("msg 2"); // recipients data.recipients.add("0912xxxxxxx"); data.recipients.add("0903xxxxxxx"); //----- Data -----

// Call SendResult response = client.target(url)     .path("send/")     .request(MediaType.APPLICATION_JSON)     .post(Entity.entity(data, MediaType.APPLICATION_JSON), SendResult.class);

if ( response.getStatus() !=0 ) {     System.out.println("error: "+response.getStatus()); } else {     for( SendMessage msg : response.getMessages())     {         if (msg.getStatus() != 0 ) {         System.out.println("error: " + msg.getStatus());         } else {         System.out.println("mid: " + msg.getId());         }     }
python
#
# Python samples are made with Requests: HTTP for Humans
#
# https://requests.readthedocs.io/en/master/
#
import requests

url = "https://sms.magfa.com/api/http/sms/v2/send" headers = {'accept': "application/json", 'cache-control': "no-cache"}

# credentials username = "username" password = "password" domain = "domain"

# data payload_tuples = [('senders': '3000xx'), ('senders':'3000xxxxxxxx'), ('messages':'test msg'), ('messages':'msg 2'), ('recipients':'0912xxxxxxx'), ('recipients':'0903xxxxxxx')] # call post form data response = requests.post(url, headers=headers, auth=(username + '/' + domain, password), data=payload_tuples)

# or json data payload_json = {'senders': ['3000xx', '3000xxxxxxxx'], 'messages':['test msg','msg 2'], 'recipients':['0912xxxxxxx', '0903xxxxxxx']} # call json response = requests.post(url, headers=headers, auth=(username + '/' + domain, password), json=payload_json) print(response.json())
C#
/**
* C# samples are made with RestSharp
* REST API client library for .Net
*
* https://restsharp.dev/
*/

using RestSharp; using RestSharp.Authenticators;

// Credentials string username = "username"; string password = "password"; string domain = "magfa";

// Client var client = new RestClient("https://sms.magfa.com/api/http/sms/v2/send");

// Auth client.Authenticator = new HttpBasicAuthenticator(username + "/" + domain, password);

// Request var request = new RestRequest(Method.POST); request.AddHeader("cache-control", "no-cache"); request.AddHeader("accept", "application/json"); // JSON request.RequestFormat = DataFormat.Json; request.AddBody(new { senders: ['3000xx', '3000xxxxxxxx'], messages:['test msg','msg 2'], recipients:['0912xxxxxxx', '0903xxxxxxx']}); // Or POST Params // request.AddParameter("senders", "3000xx") // request.AddParameter("senders", "3000xxxxxxxx") // request.AddParameter("messages", "test msg") // request.AddParameter("messages", "msg 2") // request.AddParameter("recipients", "0912xxxxxxx") // request.AddParameter("recipients", "0903xxxxxxx")

// Call IRestResponse response = client.Execute(request);

متد ‫‪mid

در صورتی که هنگام ارسال هر پيامک، شناسه‌ی يکتای کاربر نيز به عنوان پارامتر، تحويل شده باشد، با استفاده از اين متد می‌توان شناسه‌ی پیامک متناظر با آن را دريافت کرد.
شايان ذکر است که مورد استفاده‌ی اين متد جلوگيری از ارسال تکراری پيامک به هنگام رخداد خطای ارتباطی مانند TIMEOUT است. بدین صورت که پس از بروز چنین خطاهايی هنگام ارسال پيامک به همراه شناسه‌ی يکتای کاربر، با فراخوانی این متد به ازای شناسه‌های يکتا و دریافت شناسه پیامک می‌توان از ارسال دوباره پيشگيری نمود .

پارامترها

تمامی پارامترها به صورت URL-ENCODED ارسال شوند

پارامترنوعاجباری؟توضيحات
uidlongبلهشناسه‌ی یکتای کاربر

URL

https://sms.magfa.com/api/http/sms/v2/mid/{uid}

خروجی

به صورت JSON به شکل زير / کدهای خطا

{
    "status" : 0,
    "mid" : 1111111111
}
{
    "status" : 18,
    "mid" : -1
}
پارامترنوعتوضيحات
statusintstatus نشانگر وضعيت درخواست خواهد بود. مقدار صفر به معنای انجام بدون خطای درخواست و هر عدد غير از صفر کد خطای مربوطه است.
midlongشناسه يکتای پیامک یا ۱- در صورت نيافتن شناسه

نمونه‌کد

curl
# bash

# credentials username='username' password='password' domain='domain'

# call curl --basic --user "$username/$domain:$password" \     -H 'Accept: application/json' \     'https://sms.magfa.com/api/http/sms/v2/mid/123453'
php
// credentials
$username = "username";
$password = "password";
$domain = "magfa";

// url $uid = 1234; $url = 'https://sms.magfa.com/api/http/sms/v2/mid/'.$uid;

// Initializes a new cURL session $ch = curl_init($url);

// Set the CURLOPT options curl_setopt($ch, CURLOPT_HEADER, FALSE); // JSON curl_setopt($ch, CURLOPT_HTTPHEADER, ['Accept: application/json']);

// Basic Auth curl_setopt($ch, CURLOPT_USERPWD, $username."/".$domain . ":" . $password);

// Set the CURLOPT_RETURNTRANSFER option to true curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);

// call $response = curl_exec($ch); $result = json_decode($response, true); if($result['status'] != 0 )     var_dump($result['status']); else     var_dump($result['mid']);
java
/*
* Java samples are made with glassfish jersey-client
*/

// Credentials String username = "username"; String password = "password"; String domain = "domain";

// Url String url = "https://sms.magfa.com/api/http/sms/v2/"; // Auth HttpAuthenticationFeature feature = HttpAuthenticationFeature.basic(username + "/" + domain, password);

// Client Client client = ClientBuilder.newBuilder()     .register(feature)     .build();

// call long uid = 12345L; MessageIdResult response = client.target(url)     .path("mid/" + uid)     .request(MediaType.APPLICATION_JSON)     .get(MessageIdResult.class);      // resp if(response.getStatus() != 0 )     System.out.println("error: " + response.getStatus()); else     System.out.println("mid: " + response.getMid());
python
#
# Python samples are made with Requests: HTTP for Humans
#
# https://requests.readthedocs.io/en/master/
#
import requests

uid = 12345 url = "https://sms.magfa.com/api/http/sms/v2/mid/" + uid headers = {'accept': "application/json", 'cache-control': "no-cache"}

# credentials username = "username" password = "password" domain = "domain"

# call response = requests.get(url, headers=headers, auth=(username + '/' + domain, password)) print(response.json())
C#
/**
* C# samples are made with RestSharp
* REST API client library for .Net
*
* https://restsharp.dev/
*/

using RestSharp; using RestSharp.Authenticators;

// Credentials string username = "username"; string password = "password"; string domain = "magfa";

var uid = 12345;

// Client var client = new RestClient("https://sms.magfa.com/api/http/sms/v2/mid/" + uid);

// Auth client.Authenticator = new HttpBasicAuthenticator(username + "/" + domain, password);

// Request var request = new RestRequest(Method.GET); request.AddHeader("cache-control", "no-cache"); request.AddHeader("accept", "application/json");

// Call IRestResponse response = client.Execute(request);

متد ‫‪statuses

برای پيگيری وضعيت نهایی پيامک از اين متد می‌توانيد استفاده نماييد

پارامترها

تمامی پارامترها به صورت URL-ENCODED ارسال شوند

پارامترنوعاجباری؟توضيحات
midslongبلهشناسه يکتای پیامک (حد اکثر يک‌صد (۱۰۰) عدد و جدا شده با کاما)

URL

https://sms.magfa.com/api/http/sms/v2/statuses/{mid1,mid2,...}

خروجی

به ازای هر شناسه، یک از مقادير زير به عنوان وضعيت بازگشت داده می‌شود / کدهای خطا

وضعيت
  • 1-: شناسه موجود نيست (شناسه نادرست یا گذشت بيش از ۲۴ ساعت از ارسال پيامک)
  • 0: وضعيتی دريافت نشده
  • 1: رسیده به گوشی
  • 2: نرسیده به گوشی
  • 8: رسیده به مخابرات
  • 16: نرسیده به مخابرات
{
    "status" : 0,
    "dlrs" : [
        {"mid" : 1234567, "status" : 8, "date" : "2020-01-01 00:00:00"},
        {"mid" : 7654321, "status" : -1, "date" : "2020-01-01 10:10:00"}
    ]
}
{
    "status":19,
    "dlrs":[]
}
پارامترنوعتوضيحات
statusintstatus نشانگر وضعيت درخواست خواهد بود. مقدار صفر به معنای انجام بدون خطای درخواست و هر عدد غير از صفر کد خطای مربوطه است.
dlrsarrayآرايه‌ای از وضعيت شناسه‌های ارسالی
پارامترنوعتوضيحات
midlongشناسه يکتای پیامک
statusintوضعيت
datestringتاريخ (yyyy-mm-dd hh:mm:ss)

نمونه‌کد

curl
# bash

# credentials username='username' password='password' domain='domain'

# call curl --basic --user "$username/$domain:$password" \     -H 'Accept: application/json' \     'https://sms.magfa.com/api/http/sms/v2/statuses/12345'
php
// credentials
$username = "username";
$password = "password";
$domain = "magfa";

// url $mids = [1234234, 3546435]; $url = 'https://sms.magfa.com/api/http/sms/v2/statuses/'.implode(',', $mids);

// Initializes a new cURL session $ch = curl_init($url);

// Set the CURLOPT options curl_setopt($ch, CURLOPT_HEADER, FALSE);

// JSON curl_setopt($ch, CURLOPT_HTTPHEADER, ['Accept: application/json']);

// GZIP Decompression curl_setopt($ch,CURLOPT_ENCODING , 'gzip');

// Basic Auth curl_setopt($ch, CURLOPT_USERPWD, $username."/".$domain . ":" . $password);

// Set the CURLOPT_RETURNTRANSFER option to true curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);

// call $response = curl_exec($ch); var_dump(json_decode($response, true));
java
/*
* Java samples are made with glassfish jersey-client
*/

// Credentials String username = "username"; String password = "password"; String domain = "domain";

// Url String url = "https://sms.magfa.com/api/http/sms/v2/";

// Auth HttpAuthenticationFeature feature = HttpAuthenticationFeature.basic(username + "/" + domain, password);

// Client Client client = ClientBuilder.newBuilder()     .register(feature)     // enable GZIP Compression receiving data     .register(EncodingFilter.class)     .register(GZipEncoder.class)     .build();

// call DeliveryResult response = client.target(url)     .path("statuses/")     .request(MediaType.APPLICATION_JSON)     .get(DeliveryResult.class);

if(response.getStatus() != 0 )     System.out.println("error: " + response.getStatus()); else     for (DeliveryStatus dlr : response.getDlrs()) {         System.out.println("mid: " + dlr.getMid() + ", status: " + dlr.getStatus());     }
python
#
# Python samples are made with Requests: HTTP for Humans
#
# https://requests.readthedocs.io/en/master/
#
import requests

mid = 12345 url = "https://sms.magfa.com/api/http/sms/v2/statuses/" + mid headers = {'accept': "application/json", 'cache-control': "no-cache"}

# credentials username = "username" password = "password" domain = "domain"

# call response = requests.get(url, headers=headers, auth=(username + '/' + domain, password)) print(response.json())
C#
/**
* C# samples are made with RestSharp
* REST API client library for .Net
*
* https://restsharp.dev/
*/

using RestSharp; using RestSharp.Authenticators;

// Credentials string username = "username"; string password = "password"; string domain = "magfa";

var mid = 12345;

// Client var client = new RestClient("https://sms.magfa.com/api/http/sms/v2/statuses/" + mid);

// Auth client.Authenticator = new HttpBasicAuthenticator(username + "/" + domain, password);

// Request var request = new RestRequest(Method.GET); request.AddHeader("cache-control", "no-cache"); request.AddHeader("accept", "application/json");

// Call IRestResponse response = client.Execute(request);

متد ‫‪messages

برای دريافت پيامک‌های ورودی با هر بار فراخوانی این متد، حداکثر يک‌صد پيامک ورودی به صورت آرایه برگردانده می‌شود. در صورتی که تعداد وارد نشود(URL نخست) یا عددی بیش از يک‌صد (۱۰۰) وارد شود، تعداد صد در نظر گرفته می‌شود.

پارامترها

تمامی پارامترها به صورت URL-ENCODED ارسال شوند

پارامترنوعاجباری؟توضيحات
countintبلهتعداد پیامک‌های ورودی

URL

https://sms.magfa.com/api/http/sms/v2/messages

https://sms.magfa.com/api/http/sms/v2/messages/{count}

خروجی

به صورت JSON به شکل زير / کدهای خطا

{
    "status" : 0,
    "messages" : [
        {"body":"message body", "senderNumber":"98912xxxxxxx", "recipientNumber":"983000xxxx", "date": "2020-01-01 00:00:00"},
        {"body":"message body 2", "senderNumber":"98902xxxxxxx", "recipientNumber":"983000xxxx", "date": "2020-01-01 06:00:00"}
    ]
}
{
    "status" : 19,
    "messages" : []
}
پارامترنوعتوضيحات
statusintstatus نشانگر وضعيت درخواست خواهد بود. مقدار صفر به معنای انجام بدون خطای درخواست و هر عدد غير از صفر کد خطای مربوطه است.
messagesarrayپيامک‌ها
پارامترنوعتوضيحات
bodystringپيام
senderNumberstringفرستنده
recipientNumberstringگيرنده
datestringتاريخ (yyyy-mm-dd hh:mm:ss)

نمونه‌کد

curl
# bash

# credentials username='username' password='password' domain='domain'

# call curl --basic --user "$username/$domain:$password" \     -H 'Accept: application/json' \     'https://sms.magfa.com/api/http/sms/v2/messages/50'

# gzip call curl --basic --user "$username/$domain:$password" \     -H 'Accept: application/json' \     -H 'Accept-Encoding: gzip' \     'https://sms.magfa.com/api/http/sms/v2/messages/50' | gunzip
php
// credentials
$username = "username";
$password = "password";
$domain = "magfa";

// url $count = 50; $url = 'https://sms.magfa.com/api/http/sms/v2/messages/'.$count;

// Initializes a new cURL session $ch = curl_init($url);

// Set the CURLOPT options curl_setopt($ch, CURLOPT_HEADER, FALSE);

// JSON curl_setopt($ch, CURLOPT_HTTPHEADER, ['Accept: application/json']);

// GZIP Decompression curl_setopt($ch,CURLOPT_ENCODING , 'gzip');

// Basic Auth curl_setopt($ch, CURLOPT_USERPWD, $username."/".$domain . ":" . $password);

// Set the CURLOPT_RETURNTRANSFER option to true curl_setopt($ch, CURLOPT_RETURNTRANSFER, TRUE);

// call $response = curl_exec($ch); $result = json_decode($response, true); if($result['status'] != 0 )     var_dump($result['status']); else     var_dump($result['messages']);
java
/*
* Java samples are made with glassfish jersey-client
*/

// Credentials String username = "username"; String password = "password"; String domain = "domain";

// Url String url = "https://sms.magfa.com/api/http/sms/v2/"; // Auth HttpAuthenticationFeature feature = HttpAuthenticationFeature.basic(username + "/" + domain, password);

// Client Client client = ClientBuilder.newBuilder()     .register(feature)     // enable GZIP Compression receiving data     .register(EncodingFilter.class)     .register(GZipEncoder.class)     .build();

// call int count = 50; // String shortNumber = "3000xxx"; MessagesResult response = client.target(url)     .path("messages/" + count)     //.path("messages/" + count + "/" + shortNumber)     .request(MediaType.APPLICATION_JSON)     .get(MessagesResult.class);

if(response.getStatus() != 0 )     System.out.println("error: " + response.getStatus()); else     for (IncomingMessage msg : response.getMessages()) {         System.out.println("text: " + msg.getBody());     }
python
#
# Python samples are made with Requests: HTTP for Humans
#
# https://requests.readthedocs.io/en/master/
#
import requests

count = 50 url = "https://sms.magfa.com/api/http/sms/v2/messages/" + count headers = {'accept': "application/json", 'cache-control': "no-cache"}

# credentials username = "username" password = "password" domain = "domain"

# call response = requests.get(url, headers=headers, auth=(username + '/' + domain, password)) print(response.json())
C#
/**
* C# samples are made with RestSharp
* REST API client library for .Net
*
* https://restsharp.dev/
*/

using RestSharp; using RestSharp.Authenticators;

// Credentials string username = "username"; string password = "password"; string domain = "magfa";

var count = 50;

// Client var client = new RestClient("https://sms.magfa.com/api/http/sms/v2/messages/" + count);

// Auth client.Authenticator = new HttpBasicAuthenticator(username + "/" + domain, password);

// Request var request = new RestRequest(Method.GET); request.AddHeader("cache-control", "no-cache"); request.AddHeader("accept", "application/json");

// Call IRestResponse response = client.Execute(request);

کدهای خطا

جدول کدهای خطا سرويس به شرح زير است

کد خطاتوضيحات
1شماره گيرنده نادرست است
2شماره فرستنده نادرست است
3پارامتر encoding نامعتبراست. (بررسی صحت و هم‌خوانی متن پيامک با encoding انتخابی)
4پارامتر mclass نامعتبر است
6پارامتر UDH نامعتبر است
13محتويات پيامک (تركيب UDH و متن) خالی است. (بررسی دوباره‌ی متن پيامک و پارامتر UDH)
14مانده اعتبار ريالی مورد نياز برای ارسال پیامک کافی نيست
15سرور در هنگام ارسال پيام مشغول برطرف نمودن ايراد داخلی بوده است. (ارسال مجدد درخواست)
16حساب غيرفعال است. (تماس با واحد فروش سيستم‌های ارتباطی)
17حساب منقضی شده است. (تماس با واحد فروش سيستم‌های ارتباطی)
18نام كاربری و يا كلمه عبور نامعتبر است. (بررسی مجدد نام كاربری و كلمه عبور)
19درخواست معتبر نيست. (تركيب نام كاربری، رمز عبور و دامنه اشتباه است. تماس با واحد فروش برای دريافت كلمه عبور جديد)
20شماره فرستنده به حساب تعلق ندارد
22اين سرويس برای حساب فعال نشده است
23در حال حاضر امکان پردازش درخواست جديد وجود ندارد، لطفا دوباره سعی كنيد. (ارسال مجدد درخواست)
24شناسه پيامک معتبر نيست. (ممكن است شناسه پيامک اشتباه و يا متعلق به پيامكی باشد كه بيش از يک روز از ارسال آن گذشته)
25نام متد درخواستی معتبر نيست. (بررسی نگارش نام متد با توجه به بخش متدها در اين راهنما)
27شماره گيرنده در ليست سياه اپراتور قرار دارد. (ارسال پيامک‌های تبليغاتی برای اين شماره امكان‌پذير نيست)
28شماره گیرنده، بر اساس پیش‌شماره در حال حاضر در مگفا مسدود است
29آدرس IP مبدا، اجازه دسترسی به این سرویس را ندارد
30تعداد بخش‌های پیامک بیش از حد مجاز استاندارد (۲۶۵ عدد) است
101طول آرايه پارامتر messageBodies با طول آرايه گيرندگان تطابق ندارد
102طول آرايه پارامتر messageClass با طول آرايه گيرندگان تطابق ندارد
103طول آرايه پارامتر senderNumbers با طول آرايه گيرندگان تطابق ندارد
104طول آرايه پارامتر udhs با طول آرايه گيرندگان تطابق ندارد
105طول آرايه پارامتر priorities با طول آرايه گيرندگان تطابق ندارد
106آرايه‌ی گيرندگان خالی است
107طول آرايه پارامتر گيرندگان بيشتر از طول مجاز است
108آرايه‌ی فرستندگان خالی است
109طول آرايه پارامتر encoding با طول آرايه گيرندگان تطابق ندارد
110طول آرايه پارامتر checkingMessageIds با طول آرايه گيرندگان تطابق ندارد