راه‌اندازی سرویس

    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- getCredit: توسط فراخوانی این تابع می‌توانید مقدار شارژ پنل خود را به ریال چک نمائید تا در صورت نیاز به شارژ پنل اقدام نمائید. البته به صورت خودکار در صورت پایین آمدن حساب از مبلغ 100 هزار ریال سیستم بصورت اتوماتیک یکبار شما را به صورت پیامکی مطلع می‌سازد.
6- getUSSD: این تابع برای اطلاع شما از کد USSD فعال برای استعلام رمز یکبارمصرف کاربرد دارد. البته در هر دو تابع درج کد یکبارمصرف USSD، در خروجی تابع و در پارامتر USSD این مقدار به شما پاس داده خواهد شد اما در صورت نیاز در هر زمان می‌توانید بدون درج رمز یکبارمصرف و رایگان از این تابع استفاده نمائید.

کاربر با شماره‌گیری کدي که در خروجي توابع با نام USSD در پاسخ سرور وجود دارد مي‌تواند رمز يکبار مصرف خود را مشاهده نمايد. در حال حاضر يکي از اين دو کد به شما پاس داده خواهد شد. نکته بعدي اينکه در هر لحظه با فراخواني تابع getUSSD مي‌توانيد کد USSD را دريافت نمائيد.

*500*1234567#
*6655*100200300#

setOTP تابع

php نمونه کد:
        $curl = curl_init();              
        curl_setopt_array($curl, array(
        CURLOPT_URL => 'https://my.mrotp.ir/api/OTP/v1/setOTP',
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_ENCODING => '',
        CURLOPT_MAXREDIRS => 10,
        CURLOPT_TIMEOUT => 0,
        CURLOPT_FOLLOWLOCATION => true,
        CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
        CURLOPT_CUSTOMREQUEST => 'POST',
        CURLOPT_POSTFIELDS => array('apiKey' => 'your api Key','mobile' => 'mobile number','OTP' => 'your OTP','validTime' => '1 to 1440'),
        ));
        
        $response = curl_exec($curl);
        
        curl_close($curl);
        echo $response;  

                

به وسیله این تابع یک رمز OTP برای شماره موبایل مورد نظرتان در سیستم درج می‌کنید. :

https://my.mrotp.ir/api/OTP/v1/setOTP

نمونه خروجی :

{
    "code": 10236,
    "USSD": *500*1234567#,
    "message": "OTP(4321) Successfully registered for mobile number 09121112233 for 1 minutes."
}
                

و در Body درخواست.POST پارامترهای ارسالی به روش

Parameter	Format	Entry in	Description
apiKey	String	Body	صادر شده برای شما API key.
mobile	String	Body	شماره موبایلی که می‌خواهید برای او رمز یکبارمصرف درج کنید با فرمت (09121112233).
OTP	Integer	Body	یک عدد تصادفی 3 تا 8 رقمی که همان رمز یکبار مصرف مورد نظر شماست.
validTime	Integer	Body	میزان عمر رمز OTP شماست که می‌تواند عددی بین 1 تا 1440 دقیقه یعنی 24 ساعت باشد.
type	string	Body	این فیلد باید با یکی از سه مقدار SMS، USSD و يا VOICE پر شود و مشخص می‌کند کد یکبار مصرف در زیرساخت USSD تعریف گردد و یا به صورت پیامک و يا پيامک صوتي (گفتاري) برای کاربر ارسال گردد.

* در صورتی که در خروجی این تابع در پارامتر code عددی بالاتر از 100 دریافت کردید به این معناست که کد با موفقیت درج شده است. در صورت وجود خطا کد خطای مورد نظر و توضیحات آن برگردانده می‌شود.

* پارامتر USSD نيز کدي که کاربر بايد شماره‌گيري کند تا OTP مورد نظر را ببيند برمي‌گرداند.

setRandomOTP تابع

php نمونه کد:
$curl = curl_init();

    curl_setopt_array($curl, array(
    CURLOPT_URL => 'https://my.mrotp.ir/api/OTP/v1/setRandomOTP',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => '',
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 0,
    CURLOPT_FOLLOWLOCATION => true,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS => array('apiKey' => 'your api Key','mobile' => 'mobile number','length' => 'length f OTP(3 to 8)','validTime' => '1 to 1440'),
    ));

    $response = curl_exec($curl);

    curl_close($curl);
    echo $response;

                

به وسیله این تابع یک رمز OTP برای شماره موبایل مورد نظرتان در سیستم درج می‌کنید با این تفاوت که شما فقط طول رمز را که عددی بین 3 تا 8 رقم است را ارسال نموده و سیستم به صورت تصادفی رمز را تولید و پس از ثبت در سیستم آن را با عنوان OTP به شما در خروجی تحویل می‌دهد. این کد را می‌توانید در سمت خودتان ذخیره کنید.

https://my.mrotp.ir/api/OTP/v1/setRandomOTP

نمونه خروجی :

{
    "code": 101,
    "OTP": 53398,
    "USSD": *500*1234567#,
    "message": "OTP(53398) Successfully registered for mobile number 09121113344 for 1 minutes."
}

                

POST پارامترهای ارسالی به روش

Parameter	Format	Entry in	Description
apiKey	String	Body	صادر شده برای شما API key.
mobile	String	Body	شماره موبایلی که می‌خواهید برای او رمز یکبارمصرف درج کنید با فرمت (09121112233).
length	Integer	Body	طول رمز مورد نظر شماست که می‌تواند عددی بین 3 تا 8 باشد.
validTime	Integer	Body	میزان عمر رمز OTP شماست که می‌تواند عددی بین 1 تا 1440 دقیقه یعنی 24 ساعت باشد.
type	string	Body	این فیلد باید با یکی از سه مقدار SMS، USSD و يا VOICE پر شود و مشخص می‌کند کد یکبار مصرف در زیرساخت USSD تعریف گردد و یا به صورت پیامک و يا پيامک صوتي (گفتاري) برای کاربر ارسال گردد.

*در صورتی که در خروجی این تابع در پارامتر code عددی بالاتر از 100 دریافت کردید به این معناست که کد با موفقیت درج شده است. رمز تولید شده نیز در متغیر OTP برای شما در خروجی برگردانده می‌شود. در صورت وجود خطا کد خطای مورد نظر و توضیحات آن برگردانده می‌شود.

* پارامتر USSD نيز کدي که کاربر بايد شماره‌گيري کند تا OTP مورد نظر را ببيند برمي‌گرداند.

verifyOTP تابع

php نمونه کد:
                $curl = curl_init();

                curl_setopt_array($curl, array(
                CURLOPT_URL => 'https://my.mrotp.ir/api/OTP/v1/verifyOTP',
                CURLOPT_RETURNTRANSFER => true,
                CURLOPT_ENCODING => '',
                CURLOPT_MAXREDIRS => 10,
                CURLOPT_TIMEOUT => 0,
                CURLOPT_FOLLOWLOCATION => true,
                CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
                CURLOPT_CUSTOMREQUEST => 'POST',
                CURLOPT_POSTFIELDS => array('apiKey' => 'your api Key','mobile' => 'mobile number','OTP' => 'your OTP for Search'),
                ));

                $response = curl_exec($curl);

                curl_close($curl);
                echo $response;
         
                

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

https://my.mrotp.ir/api/OTP/v1/verifyOTP

نمونه خروجی :

{
    "code": 1315,
    "OTP": 4321,
    "mobile": "09121113344",
    "accept": "YES",
    "message": "OTP(4321) Successfully verify for mobile number 09183178622."
}


                

POST پارامترهای ارسالی به روش

Parameter	Format	Entry in	Description
apiKey	String	Body	صادر شده برای شما API key.
mobile	String	Body	شماره موبایلی که می‌خواهید برای او رمز یکبارمصرف را بررسی کنید. با فرمت (09121112233).
OTP	Integer	Body	یک عدد تصادفی 3 تا 8 رقمی که همان رمز یکبار مصرف (OTP) مورد نظر شما جهت بررسی بوده که کاربر در سایت یا اپلیکیشن وارد کرده است.

در صورتی که در خروجی این تابع در پارامتر accept مقدار YES را دریافت کردید یعنی این کد برای آن شماره موبایل در سیستم موجود و از زمان انقضای آن نیز نگذشته است. در صورت انقضای کد و یا نامعتبر بودن اطلاعات دیگر، این متغیر مقدار NO را برمی‌گرداند.

sendPatternSMS تابع

php نمونه کد:
                
                $curl = curl_init();

                curl_setopt_array($curl, array(
                CURLOPT_URL => 'https://my.mrotp.ir/api/OTP/v1/sendPatternSMS',
                CURLOPT_RETURNTRANSFER => true,
                CURLOPT_ENCODING => '',
                CURLOPT_MAXREDIRS => 10,
                CURLOPT_TIMEOUT => 0,
                CURLOPT_FOLLOWLOCATION => true,
                CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
                CURLOPT_CUSTOMREQUEST => 'POST',
                CURLOPT_POSTFIELDS => array('apiKey' => 'your api Key','mobile' => 'mobile number','patternId' => 'Pattern id','params' => 'params with «;» delimiter'),
                ));

                $response = curl_exec($curl);

                curl_close($curl);
                echo $response;
         
                

به کمک اين تابع مي‌توانيد انواع پيامک هاي اطلاع رساني را حتي براي شماره هاي فيلتر شده ارسال نمائيد. در تنظيمات سامانه در قسمت قالب هاي آماده متن مورد نظر خود را وارد نموده و براي قسمت هاي دايناميک از {} استفاده نمائيد. داخل کروشه عدد پارامتر مورد نظر قرا خواهد گرفت. پس از تائيد قالب توسط مدير مي‌توانيد با فراخواني تابع و ارسال پارامترها، اين مقادير با کروشه ها جايگزين خواهد شد. پارامترهاي ارسالي را با ; از يکديگر جدا کنيد. متن شما حداکثر مي‌تواند 10 مقدار دايناميک (کروشه با مقادير 0 تا 10) داشته باشد. تعداد کاراکتر ارسالی شما برای هر پارامتر محدود و 15 کاراکتر است. در صورت ارسال کاراکتر بیشتر با کد خطا -21 روبرو خواهید شد.

https://my.mrotp.ir/api/OTP/v1/sendPatternSMS

نمونه خروجی :

{
    "code": 1315,
    "message": "SMS pattern sent Successfully."
}


                

POST پارامترهای ارسالی به روش

Parameter	Format	Entry in	Description
apiKey	String	Body	صادر شده برای شما API key.
mobile	String	Body	شماره موبایل گيرنده پيامک با فرمت (09121112233).
patternId	Integer	Body	کد پترن يا قالب آماده که در صفحه قالب هاي آماده مشاهده مي‌کنيد. قالب بايد توسط مدير تاييد شده باشد.
params	String	Body	مقادير مختلف پارامتر را به صورت بهم پيوسته و با جدا کننده ; در اين فيلد ارسال نمائيد. براي مثال در صورتي که در متن قالب آماده {0} و {1} وجود داشته باشد و در اين فيلد عبارت علي;محمدي را ارسال کنيد کلمه علي با {0} و کلمه محمدي با {1} جايگزين خواهد شد.

در صورتي که در خروجي اين تابع مقدار code عدد بزرگتر از 1000 دريافت کرديد ارسال موفقيت آميز بوده و کد پيگيري آن را نيز دريافت نموده ايد.

getCredit تابع

                    
    php نمونه کد:
    $curl = curl_init();

    curl_setopt_array($curl, array(
    CURLOPT_URL => 'https://my.mrotp.ir/api/OTP/v1/getCredit',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => '',
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 0,
    CURLOPT_FOLLOWLOCATION => true,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS => array('apiKey' => 'your api Key'),
    ));

    $response = curl_exec($curl);

    curl_close($curl);
    echo $response;
        

            
                    
                

این تابع جهت دريافت شارژ کيف پول شما طراحي شده است.

https://my.mrotp.ir/api/OTP/v1/getCredit

نمونه خروجی :

{
    "code": 1,
    "credit": "329263930",
    "message": "موجودي حساب شما 329263930 ريال مي‌باشد."
}


                

POST پارامترهای ارسالی به روش

Parameter	Format	Entry in	Description
apiKey	String	Body	صادر شده برای شما API key.

اين تابع در صورت صحت عملکرد مقدار شارژ حساب کاربري شما را برگردانده و در غير اينصورت کد خطاي مربوطه را بازمي‌گرداند.

getUSSD تابع

                    
    php نمونه کد:
    $curl = curl_init();

    curl_setopt_array($curl, array(
    CURLOPT_URL => 'https://my.mrotp.ir/api/OTP/v1/getUSSD',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_ENCODING => '',
    CURLOPT_MAXREDIRS => 10,
    CURLOPT_TIMEOUT => 0,
    CURLOPT_FOLLOWLOCATION => true,
    CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_POSTFIELDS => array('apiKey' => 'your api Key'),
    ));

    $response = curl_exec($curl);

    curl_close($curl);
    echo $response;
        

            
                    
                

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

https://my.mrotp.ir/api/OTP/v1/getUSSD

نمونه خروجی :

{
    "USSD": *500*1234567#
}


                

POST پارامترهای ارسالی به روش

Parameter	Format	Entry in	Description
apiKey	String	Body	صادر شده برای شما API key.

اين تابع در صورت صحت عملکرد کد USSD که کاربر بايد براي دريافت رمز يکبارمصرف خود شماره‌گيري کند را برمي‌گرداند.

خطاهای برگشتی

لازم به توضیح است که تمامی کدهای خطا در متغیری به نام 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	در پارامترهای ارسالی لینک وجود دارد.