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

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

هشدار

توکن ها با کلید امضا شده اند اما برای افزایش امنیت و کاهش نگرانی درباره حملات MITM حتما از SSL استفاده کنید.

هشدار

درصورتی که در روز بیش از 50 شماره دریافت کنید ولی هیچکدام را فعال سازی نکنید حساب کاربری شما مسدود و طی پیامکی به شما اطلاع داده می شود، برای باز کردن حساب باید با پشتیبانی سایت تماس بگیرید.

نکته

برای افزایش امنیت برای webhook یک آدرس مخفی در سرور خود قرار دهید یا با یک رمز طولانی از آن محافظ کنید
نمونه
example.com/my_looooooooooooooong_secret_url
example.com/webhook?secret=mySuperSecretKey

نکته

اگر از افزونه های امنیتی استفاده می کنید IP 89.42.211.109 را در white-list سرور خود قرار دهید

موضوعات

آشنایی مختصر با 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 تمام قیمت های ارائه شده به ریال می باشد

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" }