مستندات - ابریش ؛ ارائه دهنده خدمات ابری

مستندات برای توسعه دهندگان

برای ارتباط با سرویس های سامانه آنک باید اطلاعات زیر را در اختیار داشته باشید. در صورتی که هر یک از این اطلاعات را در اختیار ندارید لطفا با پشتیبان سامانه تماس حاصل نمایید:

نام کاربری ثبت شده در سامانه register.abrish.ir

این نام کاربری یک بار و د ر زمان ثبت نام شما در سامانه abrish توسط خود شما و یا توسط پشتیبان سامانه تولید شده است. در صورتی که نام کاربری خود را در اختیار ندارید لطفا با پشتیبان سامانه ارتباط برقرار نمایید. این نام کاربری معمولا آدرس رایانامه رابط مشتری با شرکت سماتوس می باشد. در این متن از این پس به این نام کاربری RegisterName گفته خواهد شد.

کلید درهم سازی

چنانچه این کلید را تا کنون دریافت ننموده اید، آن را به صورتی امن از پشتیبان سامانه دریافت نمایید. از این پس به این کلید APIKey گفته خواهد شد.

نحوه تولید یک درخواست

برای ایجاد یک درخواست لازم است یک درخواست به آدرس https://register.abrish.ir/service.php ارسال گردد. برای این درخواست دو پارامتر params و checksum به صورت POST باید ارسال شوند.

- پارامتر params یک متغیر از نوع رشته است که محتوای آن یک شیء با قالب JSON می باشد. این پارامتر به صورت ثابت دارای اجزاء زیر می باشد:
  - serviceusername: این همان RegisterName است که باید در هر درخواست ارسال شود.
  - mod: این عضو نام ماژولی است که قرار است فراخوانی شود. در توضیحات بخش های بعد هر یک از ماژول ها شرح داده خواهند شد.
  - action: نام تابعی از ماژول انتخاب شده است که قرار است فراخوانی شود. مقادیر ممکن برای این پارامتر ورودی نیز در بخش های بعدی توضیح داده خواهند شد.
- پارامتر checksum به این صورت محاسبه می شود:

checksum=SHA1(params+APIKey)

به عبارتی checksum عبارت است از درهم سازی رشته حاصل از اتصال APIKey به انتهای params که این متغیر وظیفه اصلی احراز هویت را برعهده دارد. توجه نمایید تحت هیچ شرایطی APIKey را به صورت متن ارسال نمایید. چنانچه چنین خطایی رخ داد بلافاصله با پشتیبان سامانه تماس حاصل نمایید و به صورتی امن APIKey جدید دریافت نمایید.

خروجی همواره یک شیء یا آرایه با قالب JSON می باشد. در صورت بروز خطا خروجی دارای یک ویژگی با نام error خواهد بود که پیغام خطای مناسب را در اختیار قرار می دهد.

یک نمونه کد PHP ساده برای فراخوانی یک سرویس

$ch = curl_init("https://register.abrish.ir/service.php");
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

$apiKey = 'کلید درهم سازی دریافت شده از پشتیبانی';

$paramsList = array();
$paramsList['serviceusername'] = 'نام کاربری ثبت نام در سامانه';

$paramsList['mod'] = 'Organization';
$paramsList['action'] = 'getAll';

//Other required parameters based on given documentations
$paramsList[‘...’] = ‘...’; 

$params = array();
$params['params'] = json_encode($paramsList);
$params['checksum'] = sha1(json_encode($paramsList).$apiKey);

curl_setopt($ch, CURLOPT_POSTFIELDS, $params);
$res = curl_exec($ch);

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

نام ماژول

Organization

نام تابع

getAll

این درخواست لیستی از تمام سازمان هایی که توسط RegisterName ثبت شده اند را در خروجی ارائه می نماید.

پارامتر ورودی

ندارد

خروجی ها : آرایه ای که هر عضو آن به شرح زیر است

شناسه سازمان تعریف شده. این شناسه بعدا در فراخوانی درخواست های دیگر مورد استفاده قرار می گیرد.

name

نام سازمان تعریف شده

userscount

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

rolescount

تعداد سمت های تعریف شده در سازمان (این ویژگی مربوط به سازمان الکترونیک پیوند است)

rolescount

تعداد سمت های تعریف شده در سازمان (این ویژگی مربوط به سازمان الکترونیک پیوند است)

plantype

نوع طرح خریداری شده

timedout

آیا اعتبار سازمان به پایان رسیده است (۰: خیر ۱: بلی)

duration

تاریخ انقضای طرح خریداری شده برای سازمان با قالب هجری شمسی

allowedusers

تعداد مجاز تعریف کاربر برای سازمان

ماژول Organization تابع saveName

نام ماژول

Organization

نام تابع

saveName

در صورت نیاز به تغییر نام یک سازمان می توان از این تابع استفاده نمود.

پارامترهای ورودی

شناسه سازمانی که باید نام آن تغییر یابد

orgname

نام جدید سازمان

خروجی ها: یک شیء که یکی از دو ویژگی زیر را دارا است.

error

پیغام خطا در صورت وجود خطا

success

پیغام موفقیت آمیز بودن عملیات

ماژول Organization تابع getAllUsers

نام ماژول

Organization

نام تابع

getAllUsers

این تابع لیست همه کاربران را در خروجی بر می گرداند. البته این لیست محدود به پارامترهای ورودی می باشد که توضیح داده شده اند. همچنین در هر بار تنها ۱۸ عدد از کاربران برگردانده می شوند و برای دریافت مابقی کاربران باید درخواست با پارامترهای مناسب مجددا فراخوانی شود.

پارامترهای ورودی

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

page

شماره صفحه ای از نتایج که باید لیست آن برگردانده شود. در هر صفحه تنها ۱۸ عدد از نتایج بازگردانده می شوند و در اولین فراخوانی باید شماره صفحه ۰ ارسال شود. شماره صفحات نیز از ۰ شروع می شود.

filter

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

خروجی ها

count

تعداد کل نتایجی که با شرایط ورودی ها همخوانی دارند. به عبارتی ممکن است این متغیر برابر ۲۰۰ باشد. به این معنی است که کل نتایج مورد نظر ۲۰۰ عدد هستند. اما تنها ۱۸ عدد از آن ها براساس مقدار page بازگردانده می شود. تاکید می شود در این شرایط مقدار count برابر ۲۰۰ خواهد بود و نه ۱۸.

data

یک آرایه است که هر یک از اعضاء آن دارای ویژگی های زیر می باشد

شناسه کاربر

FirstName

نام

LastName

نام خانوادگی

UserName

نام کاربری

Gender

جنسیت (۱: مرد ۲: زن)

BirthDate

تاریخ تولد با قالب هجری شمسی

Cell

شماره همراه

IsEnable

وضعیت فعال بودن کاربر (۰: غیرفعال ۱: فعال)

SpecialAccess

وضعیت دارا بودن دسترسی های ویژه (۰: فاقد دسترسی ویژه ۱: دارای دسترسی ویژه)

ماژول Organization تابع postUser

نام ماژول

Organization

نام تابع

postUser

با استفاده از این سرویس امکان درج و یا ویرایش کاربران وجود خواهد داشت

پارامترهای ورودی

شناسه سازمانی که این کاربر در آن قرار دارد

userid

در صورتی که قصد ویرایش یک کاربر را دارید شناسه کاربر است. در صورت ثبت کاربر جدید این پارامتر باید ۰ ارسال شود

firstname

نام

lastname

نام خانوادگی

username

نام کاربری که نباید بیش از ۱۶ کاراکتر باشد

gender

جنسیت (۱: مرد ۲:زن)

specialaccess

وضعیت دارا بودن دسترسی های ویژه (۰: فاقد دسترسی ویژه ۱: دارای دسترسی ویژه)

isenable

وضعیت فعال بودن کاربر (۰: غیرفعال ۱: فعال)

birthdate

تاریخ تولد با قالب هجری شمسی

cell

شماره همراه

password

کلمه عبور

خروجی ها

در صورتی که موفقیت آمیز باشد هیچ خروجی باز نمی گرداند در غیر این صورت یک مؤلفه error بازگردانده می شود.

مستندات برای توسعه دهندگان

نام کاربری ثبت شده در سامانه register.abrish.ir

کلید درهم سازی

نحوه تولید یک درخواست

رایگان ثبت نام کنید