مستندات رابط نرم افزاری
API Documentations
نسخه 1.0.0 - 27/08/2018
فهرست مطالب
1. مقدمه
تمامی وب سرویس‌های توضیح داده شده در این مستندات به صورت RESTful هستند و طبق همین چهارچوب باید با آنها ارتباط برقرار کرد.
جهت رفع هرگونه مشکل و یا پرسش با پشتیبانی در تماس باشید.
2. روند احراز هویت در سرویس یوآیدی
همانطور که میدانید یوآیدی یک سیستم احراز هویت مبتنی بر خود ظهاری کاربر میباشد. به این معنا که اطالاعات دریافتی شما از این سرویس توسط شخص کاربر ارایه شده است و صحت این اطلاعات و عواقب آن برعهده ی کاربر میباشد!
حال به بررسی اجمالی روند احراز هویت در این سرویس میپردازیم:
لیست اکتورهای سیستم:
۱. کمپانی: که در‌واقع شما که در حال حاضر در حال خواندن این مستندات هستید یکی از این کمپانی های سرویس گیرنده در یوآیدی هستید.
۲. کاربر: که همان کاربری است که قصد دارد در سیستم شما احراز هویت (ورود یا ثبت نام) کند.
۳. یوآیدی: که همان سرویس حال حاضر است
روند احراز هویت در سرویس یوآیدی:
۱. سیستم شما یک درخواست مبتنی برا گرفتن یک Qrcode به سرویس یوآیدی داده و Qrcode را در وب سایت خود به نمایش میگذارید.
۲. حال یوزر با اپلیکیشن یوآیدی این کد را اسکن میکند
۳. با توجه به انتخابی که شما در هنگام ثبت نام در سرویس یوآیدی ما دو فرآیند در ارسال اطلاعات یوزر به سیستم شما داریم. (CallBackURL, Long pulling) و ما اطلاعات لازم برای شما برای احراز هویت یوزر در سیستم شما را به شما تامین میکنیم.
در ادامه Sequnce diagram این روند را مشاهده میکنید:
3. توضیحات تکمیلی برای تمام سرویس‌ها
برای فراخوانی سرویس‌های صفحه‌بندی (pagination) اگر پارامتر ورودی ارسال نشود شما با خطا مواجه خواهید شد، که باید به صورت پارامتر در انتهای درخواست مشخص شود در صورت نیاز به بارگزاری تمام آیتم‌های یک سرویس به صورت یکجا با ایمیل به بخش پشتیبانی در تماس باشید.
4. پروتکل احراز هویت
برای احراز هویت در سرویس های یوآیدی باید از توکنی که به ایمیل شما فرستاده شده است استفاده کنید و در header درخواست های خود با کلید Authorization ارایه دهید.
5. گرفتن QRcode از سرویس UID
این سرویس به شما یک لینک دانلود عکس و یک lid میدهد که شما باید عکس را در سیستم خود نمایش دهید و همینطور lid را در سمت خود نگه دارید.
5.1. توجهات
Table 1. /business/{businessId}/generateQrCode
| Parameter | Description |
|---|---|
| ای دی شرکت شما که به شما داده شده. |
| Parameter | Description |
|---|---|
| سایز عکسی که میخواهید از سرویس یوآید دریافت کنید این سایز به پیکسل است و بین ۱۵۰ تا ۵۰۰ مجاز است. |
Header parameters
| Name | Description |
|---|---|
| توکن شرکت شما که به شما داده شده است. |
| 1.1.0 |
5.2. نمونه ی درخواست
GET /business/$BUSINESS_ID/generateQrCode?size=500 HTTP/1.1
Authorization: s
version: 1.1.0
Host: core.uid.ir
5.3. نمونه ی پاسخ دریافتی
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 343
{
"timestamp" : "2019-01-07T07:26:58.677+0000",
"status" : 200,
"error" : "OK",
"message" : {
"lid" : "WIN5IGJOGBOWXYPOAWWI2TDFR9GJTVP3TTQCSS4FQYGYIOFALBQYE1H3CLLVHJGN",
"link" : "https://fs.uid.ir/qrCode/$BUSINESS_ID/5FFNIIJM8KB3I832MXBC54A0BSMHYDO8FMDTLX9NYXTG6R713WRXU5IAQ8NNWP0V"
},
"path" : "/business/$BUSINESS_ID/generateQrCode"
}
5.4. نمونه ی درخواست با CURL
$ curl 'https://core.uid.ir/business/$BUSINESS_ID/user' -i -X POST \
-H 'Content-Type: application/json' \
-H 'Authorization: $BUSINESS_TOKEN' \
-H 'version: 1.1.0' \
6. گرفتن اطلاعات کاربر از سرویس UID (Long pooling)
وقتی که شما QRcode را در سیستم خود نمایش دادید در صورتی که CallBackURL را پیاده سازی نکرده باشید باید به صورت بازه ای این اندپوینت را فراخوانی کنید و در صورتی که کاربر QRcode را اسکن کرده باشد شما اطلاعات کاربر را دریافت خواهید کرد اما اگر کاربر هنوز به عمل اسکن را انجام نداده باشد شما با کد 202 مواجه خواهید شد که بیانگر این است که درخواست شما در حال انجام است.
6.1. توجهات
| Path | Type | Description |
|---|---|---|
|
| ال آیدی که در مرحله ی قبل گرفته اید. |
Table 2. /business/{businessId}/user
| Parameter | Description |
|---|---|
| ای دی شرکت شما که به شما داده شده. |
Header parameters
| Name | Description |
|---|---|
| توکن شرکت شما که به شما داده شده است. |
| 1.1.0 |
6.2. نمونه ی درخواست
POST /business/$BUSINESS_ID/user HTTP/1.1
Content-Type: application/json
Authorization: s
version: 1.1.0
Host: core.uid.ir
Content-Length: 80
{
"lid" : "RU9PLHNMYGN15R1MJNZQGC1DO5XFDECZKLE3NBTNDXGABLZSEOZSTJV7YTQNJLVP"
}
6.3. نمونه ی پاسخ دریافتی
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 472
{
"timestamp" : "2019-01-07T07:26:59.799+0000",
"status" : 200,
"error" : "OK",
"message" : {
"createdAt" : "2019-01-07T07:26:35.443+0000",
"updatedAt" : "2019-01-07T07:26:35.443+0000",
"locked" : false,
"profile" : {
"userId" : 100000001,
"name" : "علی",
"family" : "علیان",
"address" : { }
},
"getFilesUrl" : "https://fs.uid.ir/link/getAllBusinessLink"
},
"path" : "/business/getUser"
}
6.4. نمونه ی درخواست با CURL
$ curl 'https://core.uid.ir/business/$BUSINESS_ID/user' -i -X POST \
-H 'Content-Type: application/json' \
-H 'Authorization: $BUSINESS_TOKEN' \
-H 'version: 1.1.0' \
-d '{
"lid" : "RU9PLHNMYGN15R1MJNZQGC1DO5XFDECZKLE3NBTNDXGABLZSEOZSTJV7YTQNJLVP"
}'
7. گرفتن لینک دانلود مدارک کاربر از سرویس یوآیدی
سیستم در درخواست قبلی که اطلاعات یوزر را به شما میدهد یک لینک هم برای دریافت کل لینک های دانلود مدارک کاربر به شما میدهد شما با درخواست زدن به لینک داده شده آرایه ای از تمام لینک ها دریافت میکنید.
7.1. توجهات
| Path | Type | Description |
|---|---|---|
|
| ال آیدی که در مرحله ی قبل گرفته اید. |
Header parameters
| Name | Description |
|---|---|
| توکن شرکت شما که به شما داده شده است. |
| 1.1.0 |
7.2. نمونه ی درخواست
POST /link/getAllBusinessLink HTTP/1.1
Content-Type: application/json
Authorization: s
version: 1.1.0
Host: core.uid.ir
Content-Length: 80
{
"lid" : "LEWNV14ZAH9MUVDFLYMZGAXO8WQFAOVUATPBIJLVAZFWGMRYQJZMBVUHXDFVA78O"
}
7.3. نمونه ی پاسخ دریافتی
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Content-Length: 659
{
"timestamp" : "2019-01-07T07:26:59.198+0000",
"status" : 200,
"error" : "OK",
"message" : [ {
"link" : "https://fs.uid.ir/business/$BUSINESS_ID/users/100000351/1NRY9FA2TF44HRHPZKPXOCQGXVEI4A0ZNRJNHDLNBG1NRQTZL5XLLAKS0KIVJLOK",
"type" : 4,
"page" : 2
}, {
"link" : "https://fs.uid.ir/business/$BUSINESS_ID/users/100000351/6GZQOQWPOQ7EUCB7ER2OOTOG45NOLCACSVN3MJVZASPIY3A5MM7RF7Y6L6MICGVU",
"type" : 8,
"page" : 1
}, {
"link" : "https://fs.uid.ir/business/$BUSINESS_ID/users/100000351/GWFRJXP6E9GUHJUPSXGN5JKCOLZ4XMMCPCC7YENO4RC4MLCADSGQLDMGR2QM24UO",
"type" : 3,
"page" : 1
} ],
"path" : "/link/getAllBusinessLink"
}
7.4. نمونه ی درخواست با CURL
-H 'Content-Type: application/json' \
-H 'Authorization: $BUSINESS_TOKEN' \
-H 'version: 1.1.0' \
-d '{
"lid" : "LEWNV14ZAH9MUVDFLYMZGAXO8WQFAOVUATPBIJLVAZFWGMRYQJZMBVUHXDFVA78O"
}'
8. دانلود مدارک
برای دانلود مدارک به URL داده شده با هدرهای احراز هویت شماره ی صفحه و نوع مدرک که در درخواست قبل با هر لینک به شما داده شده است، درخواست بزنید. توجه داشته باشید که با هر لینک شما یک بار میتوانید عملیات دانلود را انجام دهید.
9. گرفتن اطلاعات کاربر از سرویس UID (CallBackURL)
اگر در هنگام ثبت نام در سرویس درخواست CallBackURL را داده باشید سرویس یوآیدی به محض اسکن توسط کاربر شما را از اسکن مطلع خواهد کرد!
در هنگام ثبت نام در سرویس یوآیدی در صورتی که شما CallBackURL را داده باشید سرویس یوآیدی به محض ورود کاربر به وسیله اسکن رمزینه یک درخواست GET به سرویس شما میدهد و شما باید بعد از دریافت این درخواست دقیقاً به همان صورتی که در بخش LongPolling توضیح داده شده از سرویس یوآیدی درخواست اطلاعات کاربر را بکنید.
این درخواست به عنوان مثال به شکل زیر روی سرویس شما فراخوانی خواهد شد:
www.yourcompany.com/callme?lid=avacm124LKD
توجه: عبارت قبل از علامت سوال مختص به سرویس شما است و تعریف شده توسط شما خواهد بود اما توجه داشته باشید که lid را در پارامتر URL خود دریافت کنید.
توجه: تفاوت این پیاده با پیاده‌سازی LongPolling در این است که نیازی به درخواست های متعدد به سرویس یوآیدی نمیباشد و صرفا وقتی که یوآیدی سیستم شما را فراخوانی کرد، شما به سرویس یوآیدی درخواست میزنید!
