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

آغاز به کار

مقدمه

سرويس ‍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

متدها

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

متد balance

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

URL

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

پارامترها

ندارد

خروجی

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

{
    "status" : 0,
    "balance" : 1000
}

{
    "status" : 18,
    "balance" : null
}

نمونه‌کد

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

پارامترها

فرستنده

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

• 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" : []
}

نمونه‌کد

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", "پيامک فارسی"],"recipients":["0912xxxxxxx","0903xxxxxxx"]}' \
    'https://sms.magfa.com/api/http/sms/v2/send'

# post gzip compressed json data
echo '{"senders": ["30008710", "30008710"], "messages":["test msg", "پيامک فارسی"],"recipients":["0912xxxxxxx","0903xxxxxxx"]}' | \
gzip | \
curl --basic --user "$username/$domain:$password" \
    -H 'Accept: application/json' \
    -H "Content-Type: application/json" \
    -H "Content-Encoding: gzip" \
    --data-binary @-
    'https://sms.magfa.com/api/http/sms/v2/send'

# or post form data
curl --basic --user "$username/$domain:$password" \
    -H 'Accept: application/json' \
    -d 'senders=3000xx&senders=3000xxxxxxxx&messages=test msg&messages=پيامک فارسی&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);
$header[] = 'Content-Type: application/json';
// IF want send GZip compressed
$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

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

خروجی

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

{
    "status" : 0,
    "mid" : 1111111111
}

{
    "status" : 18,
    "mid" : -1
}

نمونه‌کد

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

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":[]
}

نمونه‌کد

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

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" : []
}

نمونه‌کد

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);

کدهای خطا

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