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

تمام پاسخ های موفق حاوی کد 20X می باشند و پاسخ های ناموفق هم با کد 40X ارسال می شوند ، بعلاوه فیلد ok در پاسخ ها هم نشان دهنده موفقیت آمیز بودن عملیات است

موضوعات

• آشنایی مختصر با Oauth2
• دریافت توکن ها
• دریافت مقدار موجودی
• دریافت قیمت ها برای سرویس
• دریافت قیمت ها برای چند سرویس
• دریافت شماره
• دریافت یک شماره برای چند سرویس
• بررسی دریافت پیامک
• لغو شماره

آشنایی مختصر با Oauth2

ابتدا باید با مفاهیم زیر آشنا شوید:

• Client callback url: آدرسی که سیم‌کارت آنلاین من کد مجوز را به آن ارسال می کند
• Client id id, api شما در سرور سیمکارت آنلاین من
• Refresh token: برای دریافت access token استفاده می شود شما باید این توکن را در مکانی امن در سرور خود ذخیره کنید با استفاده از این توکن می توانید درخواست access token بدهید
• Client secret: برای دریافت refersh token استفاده می شود

درصورتی که برای اولین بار است که از Oauth2 استفاده می‌کنید خواندن این پست در ویرگول را پیشنهاد می‌کنیم

دریافت توکن ها

از صفحه اول وب سایت یک کلاینت جدید بسازید سپس از طریق کلاینت خود(Consumer) به آدرس https://myonlinesim.com/oauth/authorize یک درخواست GET همراه با clientId برای دریافت کد مجوز ارسال کنید ارسال کنید

عنوان	متود	آدرس
دریافت کد مجوز	GET	https://myonlinesim.com/oauth/authorize?client_id=CLIENT_ID&response_type=code&scope&state=RANDOM_STRING

نمونه کد php:

function generateRandomString($length = 10) { $characters = '0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ'; $charactersLength = strlen($characters); $randomString = ''; for ($i = 0; $i < $length; $i++) { $randomString .= $characters[rand(0, $charactersLength - 1)]; return $randomString; } session_start(); $state = generateRandomString(40); $_SESSION["state"] = $state; $query = http_build_query([ 'client_id' => 'CLIENT_ID', 'response_type' => 'code', 'scope' => '', 'state' => $state ]); header('Location: https://myonlinesim.com/oauth/authorize?' . $query);

پس از ارسال درخواست به آدرس بالا کد مجوز به callback uri ایی که در مراحل قبل تعریف کرده اید ارسال می شود

کد مجوز را از طریق کوئری code در صفحه مورد نظر دریافت کنید و درخواست دیگری همراه با client secret جهت دریافت access token و refresh token ارسال کنید
نکته : عمر access token ها سه ماه و عمر refresh token ها سه سال است.
پس از طی شدن عمر access token ها می توانید با refresh token یک access tokenجدید دریاف کنید و هر 3 سالی یکبار هم با استفاده از مراحل بالا باید یک refresh token جدید دریافت کنید

برای تعیین زمان ارسال درخواست جدید می توانید از مقدار expires_in استفاده کنید.

oauth/token [POST]

نام پارامتر	مورد نیاز	توضیحات
grant_type	بله	authorization_code
client_id	بله	ID ایی که دریافت کرده اید
client_secret	بله	مطمئن شوید این مورد را در مکانی دور از دسترس کاربران نگه داری می‌کنید
code	بله	کد مجوزی که سرور سیمکارت آنلاین من به آدرسی که شما مشخص کرده اید ارسال می‌کند

نمونه کد php:

if ($_SESSION["state"] == $_GET['state']) { $http = new GuzzleHttp\Client; $response = $http->post('https://myonlinesim.com/oauth/token', ['form_params' => [ 'grant_type' => 'authorization_code', 'client_id' => 'CLIENT_ID', 'client_secret' => 'CLIENT_SECRET', 'code' => $_GET['code'], ],]); $apiResponse = json_decode((string) $response->getBody(), true); echo $apiResponse; }

oauth/token [POST]

نام پارامتر	مورد نیاز	توضیحات
grant_type	بله	refresh_token
refresh_token	بله	refresh token ایی که در مراحل قبل دریافت کرده اید
client_id	بله	ID ایی که دریافت کرده اید
client_secret	بله	مطمئن شوید این مورد را در مکانی دور از دسترس کاربران نگه داری می‌کنید
scope	خیر

نمونه کد php:

$http = new GuzzleHttp\Client; $response = $http->post('https://myonlinesim.com/oauth/token', [ 'form_params' => [ 'grant_type' => 'refresh_token', 'refresh_token' => 'the-refresh-token', 'client_id' => 'client-id', 'client_secret' => 'client-secret', 'scope' => '', ], ]); return json_decode((string) $response->getBody(), true);

پس از دریافت توکن ها باید access token را در Authorization هدرِ درخواست های آینده ارسال کنید

Header تمام درخواست های آینده باید به شکل زیر باشد

نام هدر	مقدار
Authorization	Bearer + access_token
Accept	application/json

دریافت مقدار موجودی

api/user/credit [POST]

پاسخ دریافتی (status : 200)

{"ok":true,"credit": 1000000, "status": "credit" }

دریافت قیمت ها برای سرویس

api/number/prices [POST]

لیست سرویس ها : کلیک کنید

نام پارامتر	مورد نیاز	توضیحات
service_code	بله	کد سرویس

نمونه پاسخ دریافتی

{ "name": "قرقیزستان", "code": "11", "count": 83, "price": 38000 }, { "name": "ویتنام", "code": "10", "count": 4209, "price": 44000 }, { "name": "مالزی", "code": "7", "count": 4110, "price": 46000 }, ...

دریافت قیمت ها برای چند سرویس

api/number/prices_for_multiple_services [POST]

حداکثر 5 سرویس را همزان می توانید سفارش دهید
لیست سرویس ها : کلیک کنید

نام پارامتر	مورد نیاز	توضیحات
services	بله	کد سرویس های درخواستی با , جدا کنید مانند tw,ig

نمونه پاسخ دریافتی

{ "name": "قرقیزستان", "code": "11", "count": 83, "price": 38000 }, { "name": "ویتنام", "code": "10", "count": 4209, "price": 44000 }, { "name": "مالزی", "code": "7", "count": 4110, "price": 46000 }, ...

دریافت شماره

می توانید پارامتر URL هم ارسال کنید تا سرور پیامک های دریافتی را به آدرس شما ارسال کند.

api/number/get [POST]

شماره ها پس از 15 دقیقه منقضی می شوند

لیست کشور ها : کلیک کنید

نام پارامتر	مورد نیاز	توضیحات
service_code	بله	کد سرویس
country_code	بله	کد کشور
callback	خبر	برای تنظیم webhook پیام به صورت POST با فیلد هایی دقیقا مثل پاسخ بخش بررسی پیامک به سرور شما ارسال می شود

نمونه پاسخ دریافتی

{"ok",true, "id": "pmbk5ez", "number": "178075XX00", "number_id": "XXXXXX", "country": "60", "service": "tg", "created_at": "2020-05-02T07:14:38.000000Z", "updated_at": "2020-05-02T07:14:38.000000Z", "status": "received", "is_expired": false } ...

خطا ها

اتمام موجودی

{ "ok":false,"status": "try_again_later", "error": {},"message":"APPROPRIATE MESSAGE" }

اعتبار شما برای خرید این شماره کافی نیست

{ "ok":false,"status": "not_enough_credit","message":"APPROPRIATE MESSAGE" }

دریافت شماره برای چند سرویس

می توانید پارامتر URL هم ارسال کنید تا سرور پیامک های دریافتی را به آدرس شما ارسال کند.

api/number/multiple_services [POST]

شماره ها پس از 15 دقیقه منقضی می شوند

لیست کشور ها : کلیک کنید

نام پارامتر	مورد نیاز	توضیحات
services	بله	کد سرویس
country	بله	کد کشور
callback	خبر	برای تنظیم webhook پیام به صورت POST با فیلد هایی دقیقا مثل پاسخ بخش بررسی پیامک به سرور شما ارسال می شود

نمونه پاسخ دریافتی

[ {"ok",true, "id": "pmbk5ez", "number": "178075XX00", "number_id": "XXXXXX", "country": "60", "service": "tg", "created_at": "2020-05-02T07:14:38.000000Z", "updated_at": "2020-05-02T07:14:38.000000Z", "status": "received", "is_expired": false }, {"ok",true, "id": "pmbk5et", "number": "483075XX00", "number_id": "XXXXXX", "country": "0", "service": "ig", "created_at": "2020-05-02T07:14:38.000000Z", "updated_at": "2020-05-02T07:14:38.000000Z", "status": "received", "is_expired": false }, ] ...

بررسی دریافت پیامک

api/number/sms [POST]

هر 20 یا 30 ثانیه یک درخواست ارسال کنید درغیر اینصورت توسط سرور تا یک دقیقه بلاک می‌شوید

نام پارامتر	مورد نیاز	توضیحات
service_code	بله	کد سرویس
country_code	بله	کد کشور
number_id	بله	فیلد number_id در مراحل قبل

نمونه پاسخ دریافتی

{ "ok":true,"status":"received", "sms":"SMS" }

خطا ها

هنوز پیامی دریافت نشده

{ "ok":"false","status": "no_message","message":"APPROPRIATE MESSAGE" }

منقضی شده

{ "ok":"false","status": "expired","message":"APPROPRIATE MESSAGE" }

شماره درخواستی پیدا نشد

{ "ok":"false","status": "number_not_found","message":"APPROPRIATE MESSAGE" }

لغو شماره

api/number/ban [POST]

نام پارامتر	مورد نیاز	توضیحات
service_code	بله	کد سرویس
is_ban	بله	در صورتی که شماره ریپورت شده بود 1 و در غیر اینصورت 0 را ارسال کنید.
number_id	بله	فیلد number_id در مراحل قبل

نمونه پاسخ دریافتی

{ "ok":true,"status":"deleted","message":"APPROPRIATE MESSAGE" }

خطا ها

شمار اجازه حذف کردن این شماره را ندارید (در صورتی که درخواست حذف کردن شماره های کاربر دیگری را بدهید یا بخواهید شماره ای که پیام دریافت کرده است را حذف کنید)

{ "ok":false,"status": "you cannot ban this number","message":"APPROPRIATE MESSAGE" }

منقضی شده

{ "ok":false,"status": "expired","message":"APPROPRIATE MESSAGE" }

شماره درخواستی پیدا نشد

{ "ok":false,"status":"not_found","message":"APPROPRIATE MESSAGE" }