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

آغاز به کار

مقدمه

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

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

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

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

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

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

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

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

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

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

احراز هويت

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

متدهای HTTP

متدها

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

متد getCredit

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

URL

https://sms.magfa.com/magfaHttpService?service=getcredit&...

https://sms.magfa.com/api/http/sms/v1?service=getcredit&...

پارامترها

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

خروجی

ميزان مانده اعتبار (double) / کدهای خطا

نمونه‌کد

curl

# bash

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

# call
curl --get \
    --data-urlencode "username=$username" \
    --data-urlencode "password=$password" \
    --data-urlencode "domain=$domain" \
    --data-urlencode 'service=getcredit' \
    'https://sms.magfa.com/api/http/sms/v1'

php

// credentials
$username = 'USER';
$password = 'PASS';
$domain = 'magfa';

// data
$data = [];
$data['username'] = $username;
$data['password'] = $password;
$data['domain'] = $domain;

$data['service'] = 'getcredit';
    
// url
$url = 'https://sms.magfa.com/api/http/sms/v1?'. http_build_query($data);

// call
$contents = file_get_contents($url);

java

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

// url
URL url = new URL("https://sms.magfa.com/api/http/sms/v1?service=getcredit&username=" + username + "&password=" + password + "&domain=" + domain + "");

URLConnection con = url.openConnection();
InputStream in = con.getInputStream();
String encoding = con.getContentEncoding();

encoding = encoding == null ? "UTF-8" : encoding;

String contents = IOUtils.toString(in, encoding);

python

# https://requests.readthedocs.io/en/master/
import requests

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

# call
contents = requests.get("https://sms.magfa.com/api/http/sms/v1?service=getcredit&username=" + username + "&password=" + password + "&domain=" + magfa + "");
print(contents.text());

C#

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

// Client
using var client = new HttpClient();

// Call
var content = await client.GetStringAsync("https://sms.magfa.com/api/http/sms/v1?service=getcredit&username="+username+"&password="+password+"&domain="+domain+"");

متد enqueue

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

URL

https://sms.magfa.com/magfaHttpService?service=enqueue&...

https://sms.magfa.com/api/http/sms/v1?service=enqueue&...

پارامترها

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

فرستنده

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

• 3000xxxxxx
• 983000xxxxxx
• %2B983000xxxxxx

گيرنده

شماره‌ی گيرنده را به صورت‌های زير می‌توانيد مورد استفاده قرار دهيد. برای ارسال به چندين گيرنده، شماره‌ها را با کاما [,] از هم جدا نمایید

• 09xxxxxxxxx
• 989xxxxxxxxx
• %2B989xxxxxxxxx
• 9xxxxxxxxx

پيام

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

خروجی

شناسه پيامک به ازای هر گيرنده (long) در هر خط خروجی / کدهای خطا

نمونه‌کد

curl

# bash

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

# call
curl --get \
    --data-urlencode "username=$username" \
    --data-urlencode "password=$password" \
    --data-urlencode "domain=$domain" \
    --data-urlencode 'service=enqueue' \
    --data-urlencode 'from=983000' \
    --data-urlencode 'to=0912xxxxxxx,0935xxxxxxx' \
    --data-urlencode 'text=sample text' \
    'https://sms.magfa.com/api/http/sms/v1'

php

// credentials
$username = 'USER';
$password = 'PASS';
$domain = 'magfa';

// data
$data = [];
$data['username'] = $username;
$data['password'] = $password;
$data['domain'] = $domain;

$data['service'] = 'enqueue';

$data['from'] = '983000xxxx';
$data['to'] = '0912xxxxxxx,0935xxxxxxx';
$data['text'] = 'sample text';

// url
$url = 'https://sms.magfa.com/api/http/sms/v1?'. http_build_query($data);

// call
$contents = file_get_contents($url);

java

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

// url
URL url = new URL("https://sms.magfa.com/api/http/sms/v1?service=enqueue&username=" + username + "&password=" + password + "&domain=" + domain + "&from=983000&to=0912xxxxxxx,0935xxxxxxx&text=sample text");

URLConnection con = url.openConnection();

InputStream in = con.getInputStream();
String encoding = con.getContentEncoding();
encoding = encoding == null ? "UTF-8" : encoding;

String contents = IOUtils.toString(in, encoding);

python

# https://requests.readthedocs.io/en/master/
import requests

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

# call
contents = requests.get("https://sms.magfa.com/api/http/sms/v1?service=enqueue&username=" + username + "&password=" + password + "&domain=" + magfa + "&from=983000&to=0912xxxxxxx,0935xxxxxxx&text=sample text");
print(contents.text());

C#

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

// Client
using var client = new HttpClient();

// Call
var content = await client.GetStringAsync("https://sms.magfa.com/api/http/sms/v1?service=enqueue&username="+username+"&password="+password+"&domain="+domain+"&from=983000&to=0912xxxxxxx,0935xxxxxxx&text=sample text");

متد ‫‪getMessageId

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

URL

https://sms.magfa.com/magfaHttpService?service=getMessageId&...

https://sms.magfa.com/api/http/sms/v1?service=getMessageId&...

خروجی

شناسه پیامک متناظر (long) / کدهای خطا

نمونه‌کد

curl

# bash

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

# call
curl --get \
    --data-urlencode "username=$username" \
    --data-urlencode "password=$password" \
    --data-urlencode "domain=$domain" \
    --data-urlencode 'service=getmessageid' \
    --data-urlencode 'chkmessageid=123' \
    'https://sms.magfa.com/api/http/sms/v1'

php

// credentials
$username = 'USER';
$password = 'PASS';
$domain = 'magfa';

// data
$data = [];
$data['username'] = $username;
$data['password'] = $password;
$data['domain'] = $domain;

$data['service'] = 'getMessageId';

$data['chkmessageid'] = 123;
    
// url
$url = 'https://sms.magfa.com/api/http/sms/v1?'. http_build_query($data);

// call
$contents = file_get_contents($url);

java

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

// url
URL url = new URL("https://sms.magfa.com/api/http/sms/v1?service=getmessageid&username=" + username + "&password=" + password + "&domain=" + domain + "&chkmessageid=123");

URLConnection con = url.openConnection();
InputStream in = con.getInputStream();
String encoding = con.getContentEncoding();
encoding = encoding == null ? "UTF-8" : encoding;

String contents = IOUtils.toString(in, encoding);

python

# https://requests.readthedocs.io/en/master/
import requests

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

# call
contents = requests.get("https://sms.magfa.com/api/http/sms/v1?service=getmessageid&username=" + username + "&password=" + password + "&domain=" + magfa + "&chkmessageid=123");
print(contents.text());

C#

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

// Client
using var client = new HttpClient();

// Call
var content = await client.GetStringAsync("https://sms.magfa.com/api/http/sms/v1?service=getmessageid&username="+username+"&password="+password+"&domain="+domain+"&chkmessageid=123");

متد ‫‪getRealMessageStatus

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

URL

https://sms.magfa.com/magfaHttpService?service=getRealMessageStatus&...

https://sms.magfa.com/api/http/sms/v1?service=getRealMessageStatus&...

خروجی

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

• 1-: شناسه موجود نيست (شناسه نادرست یا گذشت بيش از ۲۴ ساعت از ارسال پيامک)
• 0: وضعيتی دريافت نشده
• 1: رسیده به گوشی
• 2: نرسیده به گوشی
• 8: رسیده به مخابرات
• 16: نرسیده به مخابرات

نمونه‌کد

curl

# bash

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

# call
curl --get \
    --data-urlencode "username=$username" \
    --data-urlencode "password=$password" \
    --data-urlencode "domain=$domain" \
    --data-urlencode 'service=getrealmessagestatus' \
    --data-urlencode 'messageId=121212121' \
    'https://sms.magfa.com/api/http/sms/v1'

php

// credentials
$username = 'USER';
$password = 'PASS';
$domain = 'magfa';

// data
$data = [];
$data['username'] = $username;
$data['password'] = $password;
$data['domain'] = $domain;

$data['service'] = 'getrealmessagestatus';

$data ['messageId'] = '121212121';
    
// url
$url = 'https://sms.magfa.com/api/http/sms/v1?'. http_build_query($data);

// call
$contents = file_get_contents($url);

java

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

// url
URL url = new URL("https://sms.magfa.com/api/http/sms/v1?service=getrealmessagestatus&username=" + username + "&password=" + password + "&domain=" + domain + "&messageId=121212121");

URLConnection con = url.openConnection();
InputStream in = con.getInputStream();
String encoding = con.getContentEncoding();
encoding = encoding == null ? "UTF-8" : encoding;

String contents = IOUtils.toString(in, encoding);

python

# https://requests.readthedocs.io/en/master/
import requests

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

# call
contents = requests.get("https://sms.magfa.com/api/http/sms/v1?service=getrealmessagestatus&username=" + username + "&password=" + password + "&domain=" + magfa + "&messageId=121212121");
print(contents.text())

C#

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

// Client
using var client = new HttpClient();

// Call
var content = await client.GetStringAsync("https://sms.magfa.com/api/http/sms/v1?service=getrealmessagestatus&username="+username+"&password="+password+"&domain="+domain+"&messageId=121212121");

کدهای خطا

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