راهنمای سرويس HTTP v2
پيادهسازی شده به صورت REST/JSON
آغاز به کار
مقدمه
سرويس HTTP v2 بهينهسازیشدهی سرويس HTTP v1 با متدهای REST و به صورت امن HTTPS، طراحی شده و به راحتی در همهی زبانهای برنامهنويسی قابل استفاده است. به دلیل سربار کم این سرويس، پهنای باند مصرفی در آن بسیار اندک خواهد بود. شایان ذکر است در این سرويس نیز تنها از UTF-8 پشتيبانی میشود.
افزون بر امکانات نسخهی v1 امکان دریافت پيامکهای ورودی نيز در اين سرويس فراهم شده است.
همانند نسخه v1، در اين سرويس نيز سامانه به ازای هر پيامک ارسالی، شناسهای یکتا جهت پيگیری وضعيت ارایه مینمايد. همچنین برای افزايش سرعت ارسال میتوانيد از فراخوانیهای همزمان استفاده نماييد.
نکتهها
- بیشینه تعداد شماره گيرنده در درخواستها يکصد (۱۰۰) عدد است. ارسال بيش از این تعداد با کد خطا مواجه خواهد شد
- در پاسخ همهی متدها ، پارامتر 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
پارامترها
ندارد
خروجی
به صورت JSON به شکل زير / کدهای خطا
{
"status" : 0,
"balance" : 1000
}
{
"status" : 18,
"balance" : null
}
پارامتر | نوع | توضيحات |
---|---|---|
status | int | status نشانگر وضعيت درخواست خواهد بود. مقدار صفر به معنای انجام بدون خطای درخواست و هر عدد غير از صفر کد خطای مربوطه است. |
balance | long | مانده اعتبار |
نمونهکد
- 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
پارامترها
تمامی پارامترها به صورت URL-ENCODED ارسال شوند
پارامتر | نوع | اجباری؟ | توضيحات |
---|---|---|---|
senders | string | بله | آرايهای از فرستنده |
recipients | string | بله | آرايهای از گيرنده |
messages | string | بله | آرايهای از پيام |
encodings | int | آرايهای از يکی از مقادير 0 (تشخيص خودکار زبان پیامک[پيش فرض])، 2 (فارسی)، 5 (ارسال به صورت 8BIT) و 6 (ارسال به صورت BINARY) | |
uids | long | آرايهای از شناسهی یکتای کاربر | |
udhs | string | آرايهای از 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" : []
}
پارامتر | نوع | توضيحات |
---|---|---|
status | int | status نشانگر وضعيت درخواست خواهد بود. مقدار صفر به معنای انجام بدون خطای درخواست و هر عدد غير از صفر کد خطای مربوطه است. |
messages | array | نتيجهی پردازش پيامکهای ارسالی |
پارامتر | نوع | توضيحات |
---|---|---|
status | int | status نشانگر وضعيت درخواست خواهد بود. مقدار صفر به معنای انجام بدون خطای درخواست و هر عدد غير از صفر کد خطای مربوطه است. |
id | long | شناسه يکتای پیامک |
userId | long | شناسهی یکتای کاربر |
parts | int | تعداد بخشهای پيامک |
tariff | float | تعرفه |
alphabet | string | DEFAULT برای لاتین و UCS2 برای فارسی |
recipient | string | گيرنده |
نمونهکد
- 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 ارسال شوند
پارامتر | نوع | اجباری؟ | توضيحات |
---|---|---|---|
uid | long | بله | شناسهی یکتای کاربر |
URL
خروجی
به صورت JSON به شکل زير / کدهای خطا
{
"status" : 0,
"mid" : 1111111111
}
{
"status" : 18,
"mid" : -1
}
پارامتر | نوع | توضيحات |
---|---|---|
status | int | status نشانگر وضعيت درخواست خواهد بود. مقدار صفر به معنای انجام بدون خطای درخواست و هر عدد غير از صفر کد خطای مربوطه است. |
mid | long | شناسه يکتای پیامک یا ۱- در صورت نيافتن شناسه |
نمونهکد
- 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 ارسال شوند
پارامتر | نوع | اجباری؟ | توضيحات |
---|---|---|---|
mids | long | بله | شناسه يکتای پیامک (حد اکثر يکصد (۱۰۰) عدد و جدا شده با کاما) |
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":[]
}
پارامتر | نوع | توضيحات |
---|---|---|
status | int | status نشانگر وضعيت درخواست خواهد بود. مقدار صفر به معنای انجام بدون خطای درخواست و هر عدد غير از صفر کد خطای مربوطه است. |
dlrs | array | آرايهای از وضعيت شناسههای ارسالی |
پارامتر | نوع | توضيحات |
---|---|---|
mid | long | شناسه يکتای پیامک |
status | int | وضعيت |
date | string | تاريخ (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 ارسال شوند
پارامتر | نوع | اجباری؟ | توضيحات |
---|---|---|---|
count | int | بله | تعداد پیامکهای ورودی |
URL
خروجی
به صورت 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" : []
}
پارامتر | نوع | توضيحات |
---|---|---|
status | int | status نشانگر وضعيت درخواست خواهد بود. مقدار صفر به معنای انجام بدون خطای درخواست و هر عدد غير از صفر کد خطای مربوطه است. |
messages | array | پيامکها |
پارامتر | نوع | توضيحات |
---|---|---|
body | string | پيام |
senderNumber | string | فرستنده |
recipientNumber | string | گيرنده |
date | string | تاريخ (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 با طول آرايه گيرندگان تطابق ندارد |