نحوه استفاده از API سامانه نوبت دهی آسا

سامانه نوبت دهی آسا این امکان را برای توسعه دهندگان فراهم نموده است تا از طریق API های REST مبتنی بر HTTP بتوانند ارتباط بین نرم افزارهای خود و سامانه آسا را میسر سازند. استفاده از پروتکل HTTP این قابلیت را به توسعه دهندگان خواهد داد تا مستقل از پلتفرم نرم افزار خود (مثل برنامه های مبتنی بر دسکتاپ یا وب و موبایل) و بدون در نظر گرفتن زبان برنامه نویسی و تکنولوژی استفاده شده (مثل .NET Framework – PHP و …) قادر به تعامل با API های سامانه آسا باشند. به عنوان مثال اگر شما توسعه دهنده یک نرم افزار مدیریت مراکز درمانی هستید که با زبان دلفی و مبتنی بر دسکتاپ تولید شده است می توانید با استفاده از این API ها، نرم افزار خود را با سامانه آسا ارتباط داده و از داده های ثبت شده در آن در نرم افزار خود استفاده نمایید.

دید کلی:

به شکل کلی، برای برقراری این ارتباط، شما در ابتدا باید یک کلید (API Key) تهیه نمایید که مختص شما خواهد بود و کلیه درخواست های شما به سامانه آسا با استفاد از آن شناسایی و اعتبار سنجی خواهد شد.

پس از دریافت کلید، با استفاده از لیست دستورات API موجود، دستور مورد نظر خود را به صورت یک درخواست HTTP به سرور آسا ارسال خواهید کرد و سرور آسا پس از پردازش درخواست شما، نتیجه را در قالب یک پاسخ HTTP از سرور آسا دریافت خواهید کرد.

دریافت کلید:

اولین قدم در برقراری ارتباط با سامانه آسا، دریافت کلید API است. هر مرکز درمانی یک کلید منحصر به فرد خواهد داشت که به منزله شماره شناسایی آن مرکز خواهد بود و به همراه همه درخواست های مرکز به سرور آسا ارسال خواهد شد تا مشخص شود این درخواست از جانب کدام مرکز بوده است بنابراین در نگهداری این کلید کوشا باشید و از افشا کردن آن خودداری نمایید.

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

ارسال درخواست به سرور آسا

پس از دریافت کلید API می توانید درخواست های مورد نیاز خود را به سرور آسا ارسال نمایید. درخواست های ارسالی باید مبتنی بر پروتکل HTTP باشند. به عبارت دیگر توسعه دهندگان عزیز باید HTTP Request هایی با ساختار مشخص ایجاد کرده و آن را به سرور آسا ارسال نمایند. بدیهی است نحوه تولید HTTP Request ممکن است در هر زبان برنامه نویسی متفاوت باشد.

نکته: پارامترهای ارسالی به همراه هر Request   باید با فرمت JSON باشد.

پس از تولید و ارسال HTTP Request، سرور آسا درخواست را دریافت کرده و مقدار کلید آن را اعتبارسنجی خواهد کرد و در صورت صحت کلید ارسالی، درخواست اصلی را پردازش کرده و نتیجه را با فرمت JSON به درخواست کننده پاسخ خواهد داد.

نمونه کد ساخت و ارسال HTTP Request با استفاده از PHP:

$apiKey = 'bs5qnpqc73snv88e';
$url = self::$apiUrl . 'api/doctorSchedule/GetSpecialtys?clinicId=' . self::$clinicId . '&shiftid=' . self::$shiftId . '&apikey=' . $apiKey;

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_TIMEOUT, 30);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/json'));
$file = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ((int)$httpCode !== 200) {
    switch ($httpCode) {
        case '500' :
            $message = 'خطای سرور داخلی (خطا با کد 500) رخ داده است';
            $parameters = 'HTTP Header Code: 500' . ';';
            $parameters .= 'URL: ' . $url;
            break;

        case '404' :
            $message = 'آدرس URL مورد نظر پیدا نشد';
            $parameters = 'HTTP Header Code: 404' . ';';
            $parameters .= 'URL: ' . $url;
            break;

        case '400' :
            $message = 'درخواست بد (Bad Request)';
            $parameters = 'HTTP Header Code: 400' . ';';
            $parameters .= 'URL: ' . $url;
            break;

        case '0' :
            $message = 'مهلت زمانی درخواست به پایان رسیده است';
            $parameters = 'HTTP Status Code: 0' . ';';
            $parameters .= 'Request TimeOut' . ';';
            $parameters .= 'URL: ' . $url;
            break;

        default :
            $message = 'HTTP Header: ' . $httpCode;
            $parameters = 'HTTP Header: ' . $httpCode . ';';
            $parameters .= 'URL: ' . $url;
            break;
    }
    die($message . ' ' . $parameters);
}

$json = json_decode($file, true);

لیست دستورات موجود:

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