1. مقدمه

تمامی وب‌ سرویس‌های توضیح داده شده در این مستندات به صورت RESTful هستند و طبق همین چهارچوب باید با آنها ارتباط برقرار کرد.
جهت رفع هرگونه مشکل و یا پرسش با پشتیبانی در تماس باشید.

2. روند احراز هویت در سرویس یوآیدی

همانطور که میدانید یوآید یک سیستم احراز هویت مبتنی بر خود اظهاری کاربر میباشد به این معنا که اطالاعات دریافتی شما از این سرویس توسط شخص کاربر ارایه شده است و صحت این اطلاعات و عواقب آن برعهده ی کاربر میباشد!
حال به بررسی اجمالی روند احراز هویت در این سرویس میپردازیم:
لیست اکتور های سیستم:
۱. کمپانی : که در‌واقع شما که در حال حاضر در حال خواندن این مستندات هستید یکی از این کمپانی های سرویس گیرنده در یوآیدی هستید.
۲. کاربر: که همان کاربری است که قصد دارد در سیستم شما احراز هویت (ورود یا ثبت نام) کند.
۳. یوآیدی: که همان سرویس حال حاضر است
روند احراز هویت در سرویس یوآیدی:
۱. سیستم شما یک درخواست مبتنی برا گرفتن یک Qrcode به سرویس یوآیدی داده و Qrcode را در وب سایت خود به نمایش میگذارید.
۲. حال یوزر با اپلیکیشن یوآیدی این کد را اسکن میکند
۳. با توجه به انتخابی که شما در هنگام ثبت نام در سرویس یوآیدی ما دو فرآیند در ارسال اطلاعات یوزر به سیستم شما داریم. ‏(Webhook, Long pulling)‏ و ما اطلاعات لازم برای شما برای احراز هویت یوزر در سیستم شما را به شما تأمین میکنیم.
در ادامه Sequnce diagram این روند را مشاهده میکنید:
squence

3. توضیحات تکمیلی برای تمام سرویس‌ها

برای فراخوانی سرویس‌های صفحه‌بندی (pagination) اگر پارامتر ورودی ارسال نشود شما با خطا مواجه خواهید شد، که باید به صورت پارامتر در انتهای درخواست مشخص شود در صورت نیاز به بارگزاری تمام آیتم‌های یک سرویس به صورت یکجا با ایمیل به بخش پشتیبانی در تماس باشید.

4. پروتکل احراز هویت

برای احراز هویت در سرویس های یوآیدی باید از توکنی که به ایمیل شما فرستاده شده است استفاده کنید و در header درخواست های خود با کلید Authorization ارایه دهید.

5. گرفتن QRcode از سرویس UID

این سرویس به شما یک لینک دانلود عکس و یک lid میدهد که شما باید عکس را در سیستم خود نمایش دهید و همینطور lid را در سمت خود نگه دارید.

5.1. توجهات

Table 1. /business/{businessId}/generateQrCode
Parameter Description

businessId

ای دی شرکت شما که به شما داده شده.

Parameter Description

size

سایز عکسی که میخواهید از سرویس یوآید دریافت کنید این سایز به پیکسل است و بین ۱۵۰ تا ۵۰۰ مجاز است.

Header parameters

Name Description

Authorization

توکن شرکت شما که به شما داده شده است.

version

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/generateQrCode?size=500' -i -X GET \
    -H 'Authorization: $BUSINESS_TOKEN' \
    -H 'version: 1.1.0'

6. گرفتن اطلاعات کاربر از سرویس UID ‏‎(Long pooling)‎

وقتی که شما QRcode را در سیستم خود نمایش دادید در صورتی که WEBHOOK را پیاده سازی نکرده باشید باید به صورت بازه ای این اندپوینت را فراخوانی کنید و در صورتی که کاربر QRcode را اسکن کرده باشد شما اطلاعات کاربر را دریافت خواهید کرد اما اگر کاربر هنوز به عمل اسکن را انجام نداده باشد شما با کد 202 مواجه خواهید شد که بیانگر این است که درخواست شما در حال انجام است.

6.1. توجهات

Path Type Description

lid

String

ال آیدی که در مرحله ی قبل گرفته اید.

Table 2. /business/{businessId}/user
Parameter Description

businessId

ای دی شرکت شما که به شما داده شده.

Header parameters

Name Description

Authorization

توکن شرکت شما که به شما داده شده است.

version

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

lid

String

ال آیدی که در مرحله ی قبل گرفته اید.

Header parameters

Name Description

Authorization

توکن شرکت شما که به شما داده شده است.

version

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

$ curl 'https://core.uid.ir/link/getAllBusinessLink' -i -X POST \
    -H 'Content-Type: application/json' \
    -H 'Authorization: $BUSINESS_TOKEN' \
    -H 'version: 1.1.0' \
    -d '{
  "lid" : "LEWNV14ZAH9MUVDFLYMZGAXO8WQFAOVUATPBIJLVAZFWGMRYQJZMBVUHXDFVA78O"
}'

8. دانلود مدارک

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

9. گرفتن اطلاعات کاربر از سرویس UID ‏‎(WEBHOOK)‎

اگر در هنگام ثبت نام در سرویس درخواست WEBHOOK را داده باشید سرویس یوآیدی به محض اسکن توسط کاربر شما را از اسکن مطلع خواهد کرد!

در هنگام ثبت نام در سرویس یوآیدی در صورتی که شما CallBackURL را داده باشید سرویس یوآیدی به محض ورود کاربر به وسیله اسکن رمزینه یک درخواست GET به سرویس شما میدهد و شما باید بعد از دریافت این درخواست دقیقاً به همان صورتی که در بخش LongPolling توضیح داده شده از سرویس یوآيدی درخواست اطلاعات کاربر را بکنید.
این درخواست به عنوان مثال به شکل زیر روی سرویس شما فراخوانی خواهد شد:
www.yourcompany.com/callme?lid=avacm124LKD

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

توجه : تفاوت این پیاده با پیاده‌سازی LongPolling در این است که نیازی به درخواست های متعدد به سرویس یوآیدی نمیباشد و صرفاً وقتی که یوآیدی سیستم شما را فراخوانی کرد شما به سرویس یوآیدی درخواست میزنید!