راهاندازی سرویس
API Endpoint
https://my.mrotp.ir/api/OTP/v1/
برای استفاده از این سرویس ابتدا باید در سایت MrOTP.ir ثبتنام نموده و پس از درخواست استفاده از سرویس USSD، SMS و Voice OTP برای شما API Key صادر شده و میتوانید از توابع این وبسرویس استفاده کنید.
برای اطلاعات بیشتر به سایت https://mrotp.ir مراجعه نمائید.
برای استفاده از این وبسرویس هشت تابع درنظر گرفته شده است:
1- setOTP: با این تابع میتوانید رمز مورد نظر خودتان را برای شماره موبایل مشخص و برای مدت زمان اعتبار دلخواه در سیستم درج نمائید.
2- setRandomOTP: با این تابع میتوانید تعداد رقمهای رمز مورد نظرتان را مشخص نمائید تا سیستم به صورت اتوماتیک یک رمز تصادفی برای مدت زمان مشخص شده توسط شما برای شماره موبایل مورد نظرتان در سیستم درج نموده و در خروجی به شما تحویل نماید تا در صورت نیاز در دیتابیس سمت خودتان نیز ذخیره کنید.
3- verifyOTP: پس از شمارهگیری کد USSD توسط کاربر و مشاهده و ثبت کد در سایت و یا اپلیکیشن شما، نیاز است تا آن را با سیستم ما چک نموده و از اعتبار و درست بودن رمز مطمئن شوید. به وسیله این تابع و ارسال شماره موبایل و OTP وارد شده توسط کاربر میتوانید وضعیت آن را بررسی نمائید.
4- sendPatternSMS: در صورت نياز به اطلاع رساني کاربران باخط خدماتي و دريافت 100 درصدي کاربران ميتوانيد متن مورد نظر را با پارامترهاي آن در پنل کاربري تعريف نموده و با فراخواني اين تابع و ارسال پارامترها از خط خدماتي ما به کاربران پيامک دهيد. براي مثال:
{0} {1} گرامي سفارش شما با کد پيگيري {2} تحويل اداره پست گرديد.
حال با فراخواني تابع و ارسال نام، نام خانوادگي و شماره پيگيري محصول، اين مقادير با {0} {1} {2} جايگزين شده و پيامک براي کاربر ارسال خواهد شد.
5- sendSMS: این تابع برای مشتریان دارای دسترسی، امکان ارسال پیامک از سناریوهای از پیش طراحیشده را فراهم میکند.
6- getCredit: توسط فراخوانی این تابع میتوانید مقدار شارژ پنل خود را به ریال چک نمائید تا در صورت نیاز به شارژ پنل اقدام نمائید. البته به صورت خودکار در صورت پایین آمدن حساب از مبلغ 100 هزار ریال سیستم بصورت اتوماتیک یکبار شما را به صورت پیامکی مطلع میسازد.
7- getUSSD: این تابع برای اطلاع شما از کد USSD فعال برای استعلام رمز یکبارمصرف کاربرد دارد. البته در هر دو تابع درج کد یکبارمصرف USSD، در خروجی تابع و در پارامتر USSD این مقدار به شما پاس داده خواهد شد اما در صورت نیاز در هر زمان میتوانید بدون درج رمز یکبارمصرف و رایگان از این تابع استفاده نمائید.
8- SendDigits: این تابع برای اتصال افزونه دیجیتس وردپرس (Digits WordPress Plugin) به وبسرویس OTP از طریق درگاه پیامک سفارشی یا Custom SMS Gateway طراحی شده است. نسخه اصلی انگلیسی Digits، نسخههای راست چین و ژاکت و نسخههای عرضهشده توسط شرکتهای دیگر، در صورت داشتن قابلیت تعریف درگاه سفارشی، میتوانند از این تابع برای ثبت یا ارسال رمز یکبارمصرف از طریق USSD، پیامک یا پیامک صوتی استفاده کنند. تنظیمات این اتصال داخل افزونه انجام میشود و نیازی به نوشتن نمونهکد جداگانه ندارد.
کاربر با شمارهگیری کدي که در خروجي توابع با نام USSD در پاسخ سرور وجود دارد ميتواند رمز يکبار مصرف خود را مشاهده نمايد. در حال حاضر يکي از اين دو کد به شما پاس داده خواهد شد. نکته بعدي اينکه در هر لحظه با فراخواني تابع getUSSD ميتوانيد کد USSD را دريافت نمائيد.
*6655*100200300#
setOTP تابع
به وسیله این تابع یک رمز OTP برای شماره موبایل مورد نظرتان در سیستم درج میکنید. :
https://my.mrotp.ir/api/OTP/v1/setOTP
example.cjs ذخیره و با دستور node example.cjs اجرا کنید.نسخه موردنیاز: Node.js 18 یا بالاتر؛ برای محیط عملیاتی از نسخه LTS تحت پشتیبانی استفاده کنید.
امنیت API Key: کلید را در متغیر محیطی
OTP_API_KEY روی سرور نگهداری کنید. آن را داخل کد، مخزن، JavaScript مرورگر یا بسته فرانتاند قرار ندهید و هرگز به مرورگر ارسال نکنید.<?php
$curl = curl_init();
$data = [
'apiKey' => 'your api Key',
'mobile' => '09121112233',
'OTP' => '4321',
'validTime' => '5',
'type' => 'USSD'
];
curl_setopt_array($curl, [
CURLOPT_URL => 'https://my.mrotp.ir/api/OTP/v1/setOTP',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CONNECTTIMEOUT => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => http_build_query($data),
]);
$response = curl_exec($curl);
if ($response === false) {
throw new RuntimeException(curl_error($curl));
}
curl_close($curl);
echo $response;const apiKey = process.env.OTP_API_KEY;
if (!apiKey) {
throw new Error('OTP_API_KEY environment variable is not set.');
}
async function main() {
const controller = new AbortController();
const timeout = setTimeout(() => controller.abort(), 30000);
const data = new URLSearchParams({
apiKey,
mobile: "09121112233",
OTP: "4321",
validTime: "5",
type: "USSD"
});
try {
const response = await fetch('https://my.mrotp.ir/api/OTP/v1/setOTP', {
method: 'POST',
body: data,
signal: controller.signal
});
const result = await response.json();
console.log(result);
} finally {
clearTimeout(timeout);
}
}
main().catch((error) => {
console.error(error);
process.exitCode = 1;
});import requests
data = {
'apiKey': 'your api Key',
'mobile': '09121112233',
'OTP': '4321',
'validTime': '5',
'type': 'USSD'
}
response = requests.post(
'https://my.mrotp.ir/api/OTP/v1/setOTP',
data=data,
timeout=30
)
response.raise_for_status()
print(response.json())using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Threading.Tasks;
class Program
{
static void Main()
{
SendAsync().GetAwaiter().GetResult();
}
static async Task SendAsync()
{
using (var client = new HttpClient())
{
client.Timeout = TimeSpan.FromSeconds(30);
using (var content = new FormUrlEncodedContent(new[]
{
new KeyValuePair<string, string>("apiKey", "your api Key"),
new KeyValuePair<string, string>("mobile", "09121112233"),
new KeyValuePair<string, string>("OTP", "4321"),
new KeyValuePair<string, string>("validTime", "5"),
new KeyValuePair<string, string>("type", "USSD")
}))
using (var response = await client.PostAsync(
"https://my.mrotp.ir/api/OTP/v1/setOTP", content))
{
var result = await response.Content.ReadAsStringAsync();
response.EnsureSuccessStatusCode();
Console.WriteLine(result);
}
}
}
}
نمونه خروجی :
{
"code": 10236,
"USSD": "*6655*100200300#",
"message": "USSD OTP [4321] was successfully registered for mobile number 09121112233 and is valid for 5 minutes."
}
و در Body درخواست.POST پارامترهای ارسالی به روش
| Parameter | Format | Entry in | Description |
|---|---|---|---|
| apiKey | String | Body | صادر شده برای شما API key. |
| mobile | String | Body | شماره موبایلی که میخواهید برای او رمز یکبارمصرف درج کنید. چهار فرمت 09121112233، 9121112233، +989121112233 و 00989121112233 پذیرفته میشوند. |
| OTP | Integer | Body | یک عدد تصادفی 3 تا 8 رقمی که همان رمز یکبار مصرف مورد نظر شماست. |
| validTime | Integer | Body | میزان عمر رمز OTP شماست که میتواند عددی بین 1 تا 1440 دقیقه یعنی 24 ساعت باشد. |
| type | string | Body | این فیلد اختیاری است و میتواند با یکی از سه مقدار SMS، USSD و يا VOICE پر شود و مشخص میکند کد یکبار مصرف در زیرساخت USSD تعریف گردد و یا به صورت پیامک و يا پيامک صوتي (گفتاري) برای کاربر ارسال گردد. اگر این پارامتر ارسال نشود، مقدار پیشفرض آن USSD است. |
* در صورتی که در خروجی این تابع در پارامتر code عددی بالاتر از 100 دریافت کردید به این معناست که کد با موفقیت درج شده است. در صورت وجود خطا کد خطای مورد نظر و توضیحات آن برگردانده میشود.
* پارامتر USSD نيز کدي که کاربر بايد شمارهگيري کند تا OTP مورد نظر را ببيند برميگرداند.
setRandomOTP تابع
به وسیله این تابع یک رمز OTP برای شماره موبایل مورد نظرتان در سیستم درج میکنید با این تفاوت که شما فقط طول رمز را که عددی بین 3 تا 8 رقم است را ارسال نموده و سیستم به صورت تصادفی رمز را تولید و پس از ثبت در سیستم آن را با عنوان OTP به شما در خروجی تحویل میدهد. این کد را میتوانید در سمت خودتان ذخیره کنید.
https://my.mrotp.ir/api/OTP/v1/setRandomOTP
example.cjs ذخیره و با دستور node example.cjs اجرا کنید.نسخه موردنیاز: Node.js 18 یا بالاتر؛ برای محیط عملیاتی از نسخه LTS تحت پشتیبانی استفاده کنید.
امنیت API Key: کلید را در متغیر محیطی
OTP_API_KEY روی سرور نگهداری کنید. آن را داخل کد، مخزن، JavaScript مرورگر یا بسته فرانتاند قرار ندهید و هرگز به مرورگر ارسال نکنید.<?php
$curl = curl_init();
$data = [
'apiKey' => 'your api Key',
'mobile' => '09121112233',
'length' => '5',
'validTime' => '5',
'type' => 'USSD'
];
curl_setopt_array($curl, [
CURLOPT_URL => 'https://my.mrotp.ir/api/OTP/v1/setRandomOTP',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CONNECTTIMEOUT => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => http_build_query($data),
]);
$response = curl_exec($curl);
if ($response === false) {
throw new RuntimeException(curl_error($curl));
}
curl_close($curl);
echo $response;const apiKey = process.env.OTP_API_KEY;
if (!apiKey) {
throw new Error('OTP_API_KEY environment variable is not set.');
}
async function main() {
const controller = new AbortController();
const timeout = setTimeout(() => controller.abort(), 30000);
const data = new URLSearchParams({
apiKey,
mobile: "09121112233",
length: "5",
validTime: "5",
type: "USSD"
});
try {
const response = await fetch('https://my.mrotp.ir/api/OTP/v1/setRandomOTP', {
method: 'POST',
body: data,
signal: controller.signal
});
const result = await response.json();
console.log(result);
} finally {
clearTimeout(timeout);
}
}
main().catch((error) => {
console.error(error);
process.exitCode = 1;
});import requests
data = {
'apiKey': 'your api Key',
'mobile': '09121112233',
'length': '5',
'validTime': '5',
'type': 'USSD'
}
response = requests.post(
'https://my.mrotp.ir/api/OTP/v1/setRandomOTP',
data=data,
timeout=30
)
response.raise_for_status()
print(response.json())using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Threading.Tasks;
class Program
{
static void Main()
{
SendAsync().GetAwaiter().GetResult();
}
static async Task SendAsync()
{
using (var client = new HttpClient())
{
client.Timeout = TimeSpan.FromSeconds(30);
using (var content = new FormUrlEncodedContent(new[]
{
new KeyValuePair<string, string>("apiKey", "your api Key"),
new KeyValuePair<string, string>("mobile", "09121112233"),
new KeyValuePair<string, string>("length", "5"),
new KeyValuePair<string, string>("validTime", "5"),
new KeyValuePair<string, string>("type", "USSD")
}))
using (var response = await client.PostAsync(
"https://my.mrotp.ir/api/OTP/v1/setRandomOTP", content))
{
var result = await response.Content.ReadAsStringAsync();
response.EnsureSuccessStatusCode();
Console.WriteLine(result);
}
}
}
}
نمونه خروجی :
{
"code": 101,
"OTP": 53398,
"USSD": "*6655*100200300#",
"message": "USSD OTP [53398] was successfully registered for mobile number 09121112233 and is valid for 5 minutes."
}
POST پارامترهای ارسالی به روش
| Parameter | Format | Entry in | Description |
|---|---|---|---|
| apiKey | String | Body | صادر شده برای شما API key. |
| mobile | String | Body | شماره موبایلی که میخواهید برای او رمز یکبارمصرف درج کنید. چهار فرمت 09121112233، 9121112233، +989121112233 و 00989121112233 پذیرفته میشوند. |
| length | Integer | Body | طول رمز مورد نظر شماست که میتواند عددی بین 3 تا 8 باشد. |
| validTime | Integer | Body | میزان عمر رمز OTP شماست که میتواند عددی بین 1 تا 1440 دقیقه یعنی 24 ساعت باشد. |
| type | string | Body | این فیلد اختیاری است و میتواند با یکی از سه مقدار SMS، USSD و يا VOICE پر شود و مشخص میکند کد یکبار مصرف در زیرساخت USSD تعریف گردد و یا به صورت پیامک و يا پيامک صوتي (گفتاري) برای کاربر ارسال گردد. اگر این پارامتر ارسال نشود، مقدار پیشفرض آن USSD است. |
*در صورتی که در خروجی این تابع در پارامتر code عددی بالاتر از 100 دریافت کردید به این معناست که کد با موفقیت درج شده است. رمز تولید شده نیز در متغیر OTP برای شما در خروجی برگردانده میشود. در صورت وجود خطا کد خطای مورد نظر و توضیحات آن برگردانده میشود.
* پارامتر USSD نيز کدي که کاربر بايد شمارهگيري کند تا OTP مورد نظر را ببيند برميگرداند.
verifyOTP تابع
این تابع شما را از بسیاری از عملیات مانند نگهداری رمزهای یکبارمصرف، چک کردن طول عمر آنها و... رهایی بخشیده و فقط کافیست رمز وارد شده توسط کاربر در اپلیکیشن و یا وبسایتتان را به این تابع ارسال نموده و در صورتی که این رمز توسط یکی از دوتابع قبلی برای شما تعریف شده و مدت زمان انقضای آن نیز فرا نرسیده باشد پیام مناسب در خروجی برگردانده میگردد..
https://my.mrotp.ir/api/OTP/v1/verifyOTP
example.cjs ذخیره و با دستور node example.cjs اجرا کنید.نسخه موردنیاز: Node.js 18 یا بالاتر؛ برای محیط عملیاتی از نسخه LTS تحت پشتیبانی استفاده کنید.
امنیت API Key: کلید را در متغیر محیطی
OTP_API_KEY روی سرور نگهداری کنید. آن را داخل کد، مخزن، JavaScript مرورگر یا بسته فرانتاند قرار ندهید و هرگز به مرورگر ارسال نکنید.<?php
$curl = curl_init();
$data = [
'apiKey' => 'your api Key',
'mobile' => '09121113344',
'OTP' => '4321'
];
curl_setopt_array($curl, [
CURLOPT_URL => 'https://my.mrotp.ir/api/OTP/v1/verifyOTP',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CONNECTTIMEOUT => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => http_build_query($data),
]);
$response = curl_exec($curl);
if ($response === false) {
throw new RuntimeException(curl_error($curl));
}
curl_close($curl);
echo $response;const apiKey = process.env.OTP_API_KEY;
if (!apiKey) {
throw new Error('OTP_API_KEY environment variable is not set.');
}
async function main() {
const controller = new AbortController();
const timeout = setTimeout(() => controller.abort(), 30000);
const data = new URLSearchParams({
apiKey,
mobile: "09121113344",
OTP: "4321"
});
try {
const response = await fetch('https://my.mrotp.ir/api/OTP/v1/verifyOTP', {
method: 'POST',
body: data,
signal: controller.signal
});
const result = await response.json();
console.log(result);
} finally {
clearTimeout(timeout);
}
}
main().catch((error) => {
console.error(error);
process.exitCode = 1;
});import requests
data = {
'apiKey': 'your api Key',
'mobile': '09121113344',
'OTP': '4321'
}
response = requests.post(
'https://my.mrotp.ir/api/OTP/v1/verifyOTP',
data=data,
timeout=30
)
response.raise_for_status()
print(response.json())using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Threading.Tasks;
class Program
{
static void Main()
{
SendAsync().GetAwaiter().GetResult();
}
static async Task SendAsync()
{
using (var client = new HttpClient())
{
client.Timeout = TimeSpan.FromSeconds(30);
using (var content = new FormUrlEncodedContent(new[]
{
new KeyValuePair<string, string>("apiKey", "your api Key"),
new KeyValuePair<string, string>("mobile", "09121113344"),
new KeyValuePair<string, string>("OTP", "4321")
}))
using (var response = await client.PostAsync(
"https://my.mrotp.ir/api/OTP/v1/verifyOTP", content))
{
var result = await response.Content.ReadAsStringAsync();
response.EnsureSuccessStatusCode();
Console.WriteLine(result);
}
}
}
}
نمونه خروجی :
{
"code": 1315,
"OTP": 4321,
"mobile": "09121113344",
"accept": "YES",
"message": "OTP (4321) was successfully verified for mobile number 09121113344."
}
POST پارامترهای ارسالی به روش
| Parameter | Format | Entry in | Description |
|---|---|---|---|
| apiKey | String | Body | صادر شده برای شما API key. |
| mobile | String | Body | شماره موبایلی که میخواهید رمز یکبارمصرف او را بررسی کنید. چهار فرمت 09121112233، 9121112233، +989121112233 و 00989121112233 پذیرفته میشوند. |
| OTP | Integer | Body | یک عدد تصادفی 3 تا 8 رقمی که همان رمز یکبار مصرف (OTP) مورد نظر شما جهت بررسی بوده که کاربر در سایت یا اپلیکیشن وارد کرده است. |
در صورتی که در خروجی این تابع در پارامتر accept مقدار YES را دریافت کردید یعنی این کد برای آن شماره موبایل در سیستم موجود و از زمان انقضای آن نیز نگذشته است. در صورت انقضای کد و یا نامعتبر بودن اطلاعات دیگر، این متغیر مقدار NO را برمیگرداند.
sendPatternSMS تابع
به کمک اين تابع ميتوانيد انواع پيامک هاي اطلاع رساني را حتي براي شماره هاي فيلتر شده ارسال نمائيد. در تنظيمات سامانه در قسمت قالب هاي آماده متن مورد نظر خود را وارد نموده و براي قسمت هاي دايناميک از {} استفاده نمائيد. داخل کروشه عدد پارامتر مورد نظر قرار خواهد گرفت. پس از تائيد قالب توسط مدير ميتوانيد با فراخواني تابع و ارسال پارامترها، اين مقادير را با کروشهها جايگزين نمائيد. پارامترهاي ارسالي را با ; از يکديگر جدا کنيد. هر قالب حداکثر ميتواند 5 مقدار دايناميک (از {0} تا {4}) داشته باشد. تعداد کاراکتر ارسالی هر پارامتر متنی حداکثر 15 کاراکتر است و در صورت ارسال مقدار طولانیتر با کد خطای -21 روبرو خواهید شد. تاریخ و ساعت قابل ارسال هستند و استفاده از کاراکترهای /، :، فاصله و نیمفاصله در پارامترها مجاز است. ارسال لینک در پارامترها مجاز نیست و با کد خطای -24 رد میشود.
https://my.mrotp.ir/api/OTP/v1/sendPatternSMS
example.cjs ذخیره و با دستور node example.cjs اجرا کنید.نسخه موردنیاز: Node.js 18 یا بالاتر؛ برای محیط عملیاتی از نسخه LTS تحت پشتیبانی استفاده کنید.
امنیت API Key: کلید را در متغیر محیطی
OTP_API_KEY روی سرور نگهداری کنید. آن را داخل کد، مخزن، JavaScript مرورگر یا بسته فرانتاند قرار ندهید و هرگز به مرورگر ارسال نکنید.<?php
$curl = curl_init();
$data = [
'apiKey' => 'your api Key',
'mobile' => '09121112233',
'patternId' => '184',
'params' => 'علی;محمدی'
];
curl_setopt_array($curl, [
CURLOPT_URL => 'https://my.mrotp.ir/api/OTP/v1/sendPatternSMS',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CONNECTTIMEOUT => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => http_build_query($data),
]);
$response = curl_exec($curl);
if ($response === false) {
throw new RuntimeException(curl_error($curl));
}
curl_close($curl);
echo $response;const apiKey = process.env.OTP_API_KEY;
if (!apiKey) {
throw new Error('OTP_API_KEY environment variable is not set.');
}
async function main() {
const controller = new AbortController();
const timeout = setTimeout(() => controller.abort(), 30000);
const data = new URLSearchParams({
apiKey,
mobile: "09121112233",
patternId: "184",
params: "علی;محمدی"
});
try {
const response = await fetch('https://my.mrotp.ir/api/OTP/v1/sendPatternSMS', {
method: 'POST',
body: data,
signal: controller.signal
});
const result = await response.json();
console.log(result);
} finally {
clearTimeout(timeout);
}
}
main().catch((error) => {
console.error(error);
process.exitCode = 1;
});import requests
data = {
'apiKey': 'your api Key',
'mobile': '09121112233',
'patternId': '184',
'params': 'علی;محمدی'
}
response = requests.post(
'https://my.mrotp.ir/api/OTP/v1/sendPatternSMS',
data=data,
timeout=30
)
response.raise_for_status()
print(response.json())using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Threading.Tasks;
class Program
{
static void Main()
{
SendAsync().GetAwaiter().GetResult();
}
static async Task SendAsync()
{
using (var client = new HttpClient())
{
client.Timeout = TimeSpan.FromSeconds(30);
using (var content = new FormUrlEncodedContent(new[]
{
new KeyValuePair<string, string>("apiKey", "your api Key"),
new KeyValuePair<string, string>("mobile", "09121112233"),
new KeyValuePair<string, string>("patternId", "184"),
new KeyValuePair<string, string>("params", "علی;محمدی")
}))
using (var response = await client.PostAsync(
"https://my.mrotp.ir/api/OTP/v1/sendPatternSMS", content))
{
var result = await response.Content.ReadAsStringAsync();
response.EnsureSuccessStatusCode();
Console.WriteLine(result);
}
}
}
}
نمونه خروجی :
{
"code": 1315,
"message": "Pattern SMS sent successfully."
}
POST پارامترهای ارسالی به روش
| Parameter | Format | Entry in | Description |
|---|---|---|---|
| apiKey | String | Body | صادر شده برای شما API key. |
| mobile | String | Body | شماره موبایل گیرنده پیامک. چهار فرمت 09121112233، 9121112233، +989121112233 و 00989121112233 پذیرفته میشوند. |
| patternId | Integer | Body | کد پترن يا قالب آماده که در صفحه قالب هاي آماده مشاهده ميکنيد. قالب بايد توسط مدير تاييد شده باشد. |
| params | String | Body | مقادير مختلف پارامتر را به صورت بهم پيوسته و با جدا کننده ; در اين فيلد ارسال نمائيد. براي مثال در صورتي که در متن قالب آماده {0} و {1} وجود داشته باشد و در اين فيلد عبارت علي;محمدي را ارسال کنيد کلمه علي با {0} و کلمه محمدي با {1} جايگزين خواهد شد. |
در صورتي که در خروجي اين تابع مقدار code عدد بزرگتر از 1000 دريافت کرديد ارسال موفقيت آميز بوده و کد پيگيري آن را نيز دريافت نموده ايد.
sendSMS تابع
این تابع برای ارسال پیامک بدون استفاده از قالب پترن اپراتور طراحی شده است و یک سرویس عمومی برای ارسال متن دلخواه محسوب نمیشود. دسترسی به آن صرفاً برای مشتریانی فعال میشود که از نرمافزارها یا سرویسهای مشخص مورد تأیید شرکت استفاده میکنند. متن پیامها در سناریوهای از پیش طراحیشده داخل همان نرمافزارها تولید میشود و فعالسازی دسترسی هر API Key فقط توسط مدیر سامانه انجام میگیرد. متن نباید دارای لینک باشد و حداکثر میتواند ۸ پارت باشد. در صورتی که مدیر سامانه این محدودیت را برای API Key فعال کرده باشد، متن باید با «لغو11» یا «لغو=11» پایان یابد.
https://my.mrotp.ir/api/OTP/v1/sendSMS
example.cjs ذخیره و با دستور node example.cjs اجرا کنید.نسخه موردنیاز: Node.js 18 یا بالاتر؛ برای محیط عملیاتی از نسخه LTS تحت پشتیبانی استفاده کنید.
امنیت API Key: کلید را در متغیر محیطی
OTP_API_KEY روی سرور نگهداری کنید. آن را داخل کد، مخزن، JavaScript مرورگر یا بسته فرانتاند قرار ندهید و هرگز به مرورگر ارسال نکنید.<?php
$curl = curl_init();
$data = [
'apiKey' => 'your api Key',
'mobile' => '09123456789',
'message' => 'متن پیام شما
لغو11',
'requestId' => bin2hex(random_bytes(16))
];
curl_setopt_array($curl, [
CURLOPT_URL => 'https://my.mrotp.ir/api/OTP/v1/sendSMS',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CONNECTTIMEOUT => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => http_build_query($data),
]);
$response = curl_exec($curl);
if ($response === false) {
throw new RuntimeException(curl_error($curl));
}
curl_close($curl);
echo $response;const { randomUUID } = require('node:crypto');
const apiKey = process.env.OTP_API_KEY;
if (!apiKey) {
throw new Error('OTP_API_KEY environment variable is not set.');
}
async function main() {
const controller = new AbortController();
const timeout = setTimeout(() => controller.abort(), 30000);
const data = new URLSearchParams({
apiKey,
mobile: "09123456789",
message: "متن پیام شما\nلغو11",
requestId: randomUUID().replace(/-/g, '')
});
try {
const response = await fetch('https://my.mrotp.ir/api/OTP/v1/sendSMS', {
method: 'POST',
body: data,
signal: controller.signal
});
const result = await response.json();
console.log(result);
} finally {
clearTimeout(timeout);
}
}
main().catch((error) => {
console.error(error);
process.exitCode = 1;
});import secrets
import requests
data = {
'apiKey': 'your api Key',
'mobile': '09123456789',
'message': 'متن پیام شما\nلغو11',
'requestId': secrets.token_hex(16)
}
response = requests.post(
'https://my.mrotp.ir/api/OTP/v1/sendSMS',
data=data,
timeout=30
)
response.raise_for_status()
print(response.json())using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Threading.Tasks;
class Program
{
static void Main()
{
SendAsync().GetAwaiter().GetResult();
}
static async Task SendAsync()
{
using (var client = new HttpClient())
{
client.Timeout = TimeSpan.FromSeconds(30);
using (var content = new FormUrlEncodedContent(new[]
{
new KeyValuePair<string, string>("apiKey", "your api Key"),
new KeyValuePair<string, string>("mobile", "09123456789"),
new KeyValuePair<string, string>("message", "متن پیام شما\nلغو11"),
new KeyValuePair<string, string>("requestId", Guid.NewGuid().ToString("N"))
}))
using (var response = await client.PostAsync(
"https://my.mrotp.ir/api/OTP/v1/sendSMS", content))
{
var result = await response.Content.ReadAsStringAsync();
response.EnsureSuccessStatusCode();
Console.WriteLine(result);
}
}
}
}
نمونه خروجی موفق:
{
"code": 123456,
"parts": 1,
"price": 1200,
"message": "SMS sent successfully."
}
POST پارامترهای ارسالی به روش
| Parameter | Format | Entry in | Description |
|---|---|---|---|
| apiKey | String | Body | کلید API سرویس OTP |
| mobile | String | Body | شماره موبایل گیرنده. چهار فرمت 09121112233، 9121112233، +989121112233 و 00989121112233 پذیرفته میشوند. |
| message | String | Body | متن کامل پیامک با شرایط ذکرشده |
| requestId | String | Body | شناسه یکتای هر درخواست؛ بین ۸ تا ۶۴ کاراکتر و شامل حروف انگلیسی، عدد، خط تیره یا زیرخط. اگر درخواست قبلی با همین شناسه با موفقیت ارسال شده باشد، همان نتیجه قبلی بدون ارسال مجدد و بدون کسر هزینه برگردانده میشود. اگر درخواست قبلی ناموفق یا در حال پردازش باشد، تکرار این شناسه با خطای -28 رد میشود. |
در ارسال موفق، کد رهگیری اپراتور در code و تعداد پارت و هزینه در parts و price برگردانده میشود.
تکرار یک درخواست موفق با همان requestId باعث ارسال یا کسر هزینه مجدد نمیشود و همان نتیجه قبلی را برمیگرداند.
getCredit تابع
این تابع جهت دريافت شارژ کيف پول شما طراحي شده است.
https://my.mrotp.ir/api/OTP/v1/getCredit
example.cjs ذخیره و با دستور node example.cjs اجرا کنید.نسخه موردنیاز: Node.js 18 یا بالاتر؛ برای محیط عملیاتی از نسخه LTS تحت پشتیبانی استفاده کنید.
امنیت API Key: کلید را در متغیر محیطی
OTP_API_KEY روی سرور نگهداری کنید. آن را داخل کد، مخزن، JavaScript مرورگر یا بسته فرانتاند قرار ندهید و هرگز به مرورگر ارسال نکنید.<?php
$curl = curl_init();
$data = [
'apiKey' => 'your api Key'
];
curl_setopt_array($curl, [
CURLOPT_URL => 'https://my.mrotp.ir/api/OTP/v1/getCredit',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CONNECTTIMEOUT => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => http_build_query($data),
]);
$response = curl_exec($curl);
if ($response === false) {
throw new RuntimeException(curl_error($curl));
}
curl_close($curl);
echo $response;const apiKey = process.env.OTP_API_KEY;
if (!apiKey) {
throw new Error('OTP_API_KEY environment variable is not set.');
}
async function main() {
const controller = new AbortController();
const timeout = setTimeout(() => controller.abort(), 30000);
const data = new URLSearchParams({
apiKey
});
try {
const response = await fetch('https://my.mrotp.ir/api/OTP/v1/getCredit', {
method: 'POST',
body: data,
signal: controller.signal
});
const result = await response.json();
console.log(result);
} finally {
clearTimeout(timeout);
}
}
main().catch((error) => {
console.error(error);
process.exitCode = 1;
});import requests
data = {
'apiKey': 'your api Key'
}
response = requests.post(
'https://my.mrotp.ir/api/OTP/v1/getCredit',
data=data,
timeout=30
)
response.raise_for_status()
print(response.json())using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Threading.Tasks;
class Program
{
static void Main()
{
SendAsync().GetAwaiter().GetResult();
}
static async Task SendAsync()
{
using (var client = new HttpClient())
{
client.Timeout = TimeSpan.FromSeconds(30);
using (var content = new FormUrlEncodedContent(new[]
{
new KeyValuePair<string, string>("apiKey", "your api Key")
}))
using (var response = await client.PostAsync(
"https://my.mrotp.ir/api/OTP/v1/getCredit", content))
{
var result = await response.Content.ReadAsStringAsync();
response.EnsureSuccessStatusCode();
Console.WriteLine(result);
}
}
}
}
نمونه خروجی :
{
"code": 1,
"credit": "329263930",
"message": "موجودي حساب شما 329263930 ريال ميباشد."
}
POST پارامترهای ارسالی به روش
| Parameter | Format | Entry in | Description |
|---|---|---|---|
| apiKey | String | Body | صادر شده برای شما API key. |
اين تابع در صورت صحت عملکرد مقدار شارژ حساب کاربري شما را برگردانده و در غير اينصورت کد خطاي مربوطه را بازميگرداند.
getUSSD تابع
این تابع جهت دريافت کد USSD که کاربر شما براي دريافت رمز خود بايد شمارهگيري کند طراحي شده است. دقت کنيد که در صورت فراخواني تابع setOTP اين مقدار به شما برگردانده ميشود و نياز به فراخواني مجدد نيست و فقط در صورتي که به هر دليلي نياز به کد USSD فعال سيستم داشته باشيد ميتوانيد آن را صدا بزنيد.
https://my.mrotp.ir/api/OTP/v1/getUSSD
example.cjs ذخیره و با دستور node example.cjs اجرا کنید.نسخه موردنیاز: Node.js 18 یا بالاتر؛ برای محیط عملیاتی از نسخه LTS تحت پشتیبانی استفاده کنید.
امنیت API Key: کلید را در متغیر محیطی
OTP_API_KEY روی سرور نگهداری کنید. آن را داخل کد، مخزن، JavaScript مرورگر یا بسته فرانتاند قرار ندهید و هرگز به مرورگر ارسال نکنید.<?php
$curl = curl_init();
$data = [
'apiKey' => 'your api Key'
];
curl_setopt_array($curl, [
CURLOPT_URL => 'https://my.mrotp.ir/api/OTP/v1/getUSSD',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CONNECTTIMEOUT => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => http_build_query($data),
]);
$response = curl_exec($curl);
if ($response === false) {
throw new RuntimeException(curl_error($curl));
}
curl_close($curl);
echo $response;const apiKey = process.env.OTP_API_KEY;
if (!apiKey) {
throw new Error('OTP_API_KEY environment variable is not set.');
}
async function main() {
const controller = new AbortController();
const timeout = setTimeout(() => controller.abort(), 30000);
const data = new URLSearchParams({
apiKey
});
try {
const response = await fetch('https://my.mrotp.ir/api/OTP/v1/getUSSD', {
method: 'POST',
body: data,
signal: controller.signal
});
const result = await response.json();
console.log(result);
} finally {
clearTimeout(timeout);
}
}
main().catch((error) => {
console.error(error);
process.exitCode = 1;
});import requests
data = {
'apiKey': 'your api Key'
}
response = requests.post(
'https://my.mrotp.ir/api/OTP/v1/getUSSD',
data=data,
timeout=30
)
response.raise_for_status()
print(response.json())using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Threading.Tasks;
class Program
{
static void Main()
{
SendAsync().GetAwaiter().GetResult();
}
static async Task SendAsync()
{
using (var client = new HttpClient())
{
client.Timeout = TimeSpan.FromSeconds(30);
using (var content = new FormUrlEncodedContent(new[]
{
new KeyValuePair<string, string>("apiKey", "your api Key")
}))
using (var response = await client.PostAsync(
"https://my.mrotp.ir/api/OTP/v1/getUSSD", content))
{
var result = await response.Content.ReadAsStringAsync();
response.EnsureSuccessStatusCode();
Console.WriteLine(result);
}
}
}
}
نمونه خروجی :
{
"USSD": "*6655*100200300#"
}
POST پارامترهای ارسالی به روش
| Parameter | Format | Entry in | Description |
|---|---|---|---|
| apiKey | String | Body | صادر شده برای شما API key. |
اين تابع در صورت صحت عملکرد کد USSD که کاربر بايد براي دريافت رمز يکبارمصرف خود شمارهگيري کند را برميگرداند.
اتصال افزونه دیجیتس وردپرس (Digits WordPress Plugin) به وبسرویس OTP
اگر برای ورود و ثبتنام با شماره موبایل در سایت وردپرسی (WordPress) خود از افزونه یا پلاگین دیجیتس (Digits) استفاده میکنید، میتوانید آن را از طریق گزینه درگاه پیامک سفارشی یا Custom SMS Gateway به وبسرویس OTP متصل کنید. این روش به نسخه خاصی از فروشنده محدود نیست و برای نسخه اصلی انگلیسی Digits، نسخههای دیجیتس راست چین و ژاکت یا نسخه تهیهشده از عرضهکنندگان دیگر قابل استفاده است؛ به شرط آنکه نسخه مورد استفاده امکان تعریف درگاه سفارشی را داشته باشد.
مسیر SendDigits برای سازگاری با تنظیمات درگاه سفارشی افزونه Digits طراحی شده و امکان ثبت یا ارسال کد تأیید و رمز یکبارمصرف OTP از طریق USSD، پیامک یا پیامک صوتی را فراهم میکند. برای این اتصال نیازی به نوشتن کد PHP، JavaScript، Python یا C# نیست و آدرس وبسرویس، روش درخواست و پارامترها از داخل تنظیمات افزونه وارد میشوند. نام و محل دقیق گزینهها ممکن است در ترجمهها یا نسخههای مختلف افزونه کمی متفاوت باشد.
تنظیم درگاه سفارشی پلاگین Digits
| Setting | Value | Description |
|---|---|---|
| SMS Gateway | Custom | درگاه پیامک را روی حالت سفارشی یا Custom قرار دهید. |
| HTTP Method | POST | روش ارسال درخواست باید POST باشد. |
| Gateway URL | https://my.mrotp.ir/api/OTP/v1/SendDigits |
این آدرس را در قسمت URL درگاه سفارشی افزونه وارد کنید. |
شماره موبایل ارسالی افزونه میتواند با یکی از چهار فرمت 09121112233، 9121112233، +989121112233 یا 00989121112233 باشد. برای پیامک مقدار type=SMS، برای پیامک صوتی مقدار type=VOICE و برای ثبت رمز در بستر USSD مقدار type=USSD استفاده میشود. پارامتر type اختیاری است و اگر ارسال نشود، مقدار پیشفرض آن USSD خواهد بود. کلید API را فقط در تنظیمات سمت سرور وردپرس و افزونه Digits نگهداری کنید و آن را در کدهای قابل مشاهده مرورگر قرار ندهید.
جزئیات پارامترها و تنظیمات مرحلهبهمرحله را در آموزش اتصال افزونه دیجیتس راست چین وردپرس به وبسرویس OTP و آموزش اتصال پلاگین Digits ژاکت به سامانه پیامک OTP مشاهده کنید.
خطاهای برگشتی
لازم به توضیح است که تمامی کدهای خطا در متغیری به نام message توضیح خطای بوجود آمده را همراه دارند.
| Error Code | Description |
|---|---|
| -1 | API Key نامعتبر. |
| -2 | شماره موبایل نامعتبر. |
| -3 | OTP نامعتبر. |
| -4 | زمان اعتبار کد نامعتبر. |
| -6 | سرویس OTP برای شما غیر فعال شده است. |
| -7 | موجودي حساب کافي نيست. کاربري خود را در سايت mrotp.ir شارژ نمائيد. |
| -10 | خطای نامشخص. |
| -11 | IP سیستم یا سروری که با آن توابع را فراخوانی میکنید با IP معرفی شده در پنل مغایرت دارد. |
| -12 | OTP ارسالی شما به دلیل مغایرت شماره موبایل، عدم وجود در سیستم و یا گذشتن از زمان اعتبار آن تایید نشد. |
| -13 | مشکل در احراز هویت اکانت شما. |
| -14 | کاربر قبلا با ارسال 11 به سرشماره ارسال OTP دريافت پيامک از اين سرشماره را غير فعال کرده است. با ارسال مجدد 12 به همان سرشماره امکان ارسال مجددا فعال خواهد شد. |
| -15 | کد معرف ارسال شده (ReferralId) معتبر نيست |
| -16 | خطا در طول کاراکترهاي OTP |
| -17 | خطا در بازیابی کد پترن در ارسال پیامک با قالب آماده |
| -18 | خطا در متن قالب آماده و یا پارامترهای ارسالی |
| -19 | قالب آماده توسط مدیر تایید نشده است. |
| -20 | سرويس موقتا قطع ميباشد. |
| -21 | خطا در طول یکی از پارامترهای ارسالی به تابع ارسال پترن |
| -22 | پاسخی از اپراتور پیامک دریافت نشد. |
| -23 | پاسخی از اپراتور پیامک صوتی دریافت نشد. |
| -24 | متن یا پارامتر ارسالی حاوی لینک است. |
| -25 | دسترسی ارسال متن آزاد برای این API Key فعال نیست. |
| -26 | متن پیامک نامعتبر است یا شرایط الزامی متن را ندارد. |
| -27 | تعداد پارت پیامک بیشتر از سقف مجاز ۸ پارت است. |
| -28 | requestId نامعتبر یا تکراری است. |
| -29 | یکی از محدودیتهای تعداد درخواست، شماره گیرنده یا سقف روزانه رعایت نشده است. |