مستندات سرویس PWA احراز هویت آنلاین

e-KYC PWA Documents

نسخه 1.1.0 - 08/20/2023

فهرست مطالب

بخش اول: فراخوانی PWA

این بخش مربوط به هدایت کاربر به سرویس احراز هویت آنلاین یوآیدی می‌باشد.

۱. مقدمه

تمام مواردی که در مستندات ذکر شده است مربوط به راه اندازی PWA یوآیدی می‌باشد.

۲. روند احراز هویت در وب اپلیکیشن یوآیدی

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

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

۳. فراخوانی PWA احراز هویت یوآیدی

برای استفاده از سرویس PWA یوآیدی لینک وب اپلیکیشن را با پارامترهای مشخص در اپلیکیشن خود ایجاد کنید.

۱.۳. ایجاد URL

آدرس زیر را با استفاده از پارامتر‌ها ایجاد و توسط کلاینت کاربر فراخوانی نمائید:‌

				
					https://cloud.uid.ir/crypto/?requestBusinessId=UID_BUSINESS_ID&metaData=METADATA&phoneNumber=PHONE_NUMBER

				
			

۲.۳. پارامترها

FieldTypeKindDescription
request_business_idstringRequired

شناسه کسب‌و‌کار یا BusinessID

(توسط یوآیدی در اختیار شما قرار می‌گیرد)

metaDatastringOptionalتگ یونیک کاربر*
phoneNumberstringOptionalتلفن همراه کاربر با فرمت ۰۹xxxxxxxxx – در صورتی که این پارامتر مقدار داشته باشد، فیلد تلفن همراه در گام اول احراز هویت به صورت Auto-fill و غیرقابل ویرایش تکمیل می‌شود.*

* مقدار metaData در واقع یک تگ منحصر به فرد برای کاربر است که توسط پذیرنده به یوآیدی ارسال می‌شود. یوآیدی آن را ذخیره نموده و در سرویس‌های واکشی اطلاعات کاربر، این مقدار را در کنار سایر اطلاعات به پذیرنده بر می‌گرداند. به عنوان مثال، پذیرنده می‌تواند با ارسال شناسه کاربر خود (user_id) در تگ metaData، در فراخوانی‌های آتی، این کاربر را تگ گذاری کند.

* توجه داشته باشید که پارامتر phoneNumber محدود کننده نیست و صرفا تسهیل‌گر است و کاربر از طریق ویرایش URL می‌تواند آن‌ را تغییر دهد.

۴. احراز هویت و بازگشت به وبسایت پذیرنده

پس از خاتمه فرآیند احراز هویت آنلاین کاربر، یوآیدی کاربر را به آدرسی که قبلا توسط پذیرنده اعلام شده است هدایت می‌کند. 

۱.۴. نمونه لینک برگشت به وب سایت پذیرنده

در کد زیر، BUSINESS_REDIRECT_URL آدرسی است که قبلا توسط پذیرنده به یوآیدی اعلام شده است. به عنوان مثال:

https://business.com/uid-redirect/

				
					BUSINESS_REDIRECT_URL/?clientToken=CLIENT_TOKEN&status=STATUS
				
			

۲.۴. پارامترهای ارسالی در بازگشت

FieldTypeDescription
clientTokenstringشناسه‌ای که توسط یوآیدی به کاربر پذیرنده اختصاص داده می‌شود. در صورتی که مقدار نداشته باشد، یعنی احراز هویت کامل نشده، و درصورتی که مقدار داشته باشد، یعنی مراحل به اتمام رسیده است.
statusIntوضعیت احراز هویت کاربر (مطابق جدول زیر)

۳.۴. جدول مقادیر Status احراز هویت

ResultValueDescription
SUCCESS۱احراز هویت با موفقیت به پایان رسید
RESULT_CAMERA_NOT_SUPPORTED۲دوربین پشتیبانی نمی‌شود
RESULT_PERMISSIONS_NOT_GRANTED۳دسترسی دوربین به PWA داده نشد
RESULT_UNKNOWN_ERROR۴خطای ناشناخته
RESULT_INVALID_PARAMETERS۵ورودی‌های PWA نامعتبر است
RESULT_SABTE_AHVAAL_UNAVAILABLE۶ثبت احوال در دسترس نیست
RESULT_ALREADY_APPROVED۷کاربر قبلا فرایند را طی کرده است
RESULT_MAX_TRY_EXCEEDED۸درخواست بیش از حد مجاز
RESULT_SIGNATURE۹کاربر در مرحله‌ی تصویر امضا، فرایند را لغو کرده
RESULT_LIVENESS۱۰در مرحله‌ی ویدیوی سلفی، فرایند ناموفق به پایان رسید
RESULT_FACE_MATCHING۱۱عدم تطابق اطلاعات کاربر و ثبت احوال

توجه: وضعیت‌های فوق که در پاسخ ارسال می‌شوند مربوط به «فرآیند احراز هویت» می‌باشند و نه نتیجه‌ی آن. جهت اطلاع از نتیجه احراز هویت کاربر می‌بایست با یک فاصله زمانی، سرویس getUserInfo فراخوانی شود.

بخش دوم: مدیریت اطلاعات

 

۱. مقدمه

تمامی وب‌ سرویس‌های توضیح داده شده در این مستندات به صورت RESTful هستند و طبق همین چهارچوب باید با آنها ارتباط برقرار کرد.

جهت رفع هرگونه مشکل و یا پرسش با پشتیبانی در تماس باشید.

۲. احراز هویت و ورود از طریق یوآیدی

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

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

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

توجه داشته باشید به دلیل محدودیت های اداره ثبت احوال گرفتن اطلاعات کاربر پس از حداقل ۱۰ دقیقه امکان پذیر می باشد.

در ادامه Sequence diagram روند احراز هویت را مشاهده میکنید:

Sequence

۳. ورود پذیرنده

جهت دسترسی به اطلاعات کاربر، ابتدا با استفاده از id, secrectKey (توسط یوآیدی در اختیار پذیرنده قرار داده می‌شود) وارد سیستم شوید و access_token دریافت نمایید.

۱.۳. نمونه‌ی درخواست

				
					POST - https://cloud.uid.ir/cryptocore/business/login


Content-Type: application/json;charset=UTF-8
{
  "id": <UID_BUSINESS_ID>,
  "secretKey": <UID_SECRET_KEY>
}

				
			

۲.۳. توضیح پارامترهای درخواستی

FieldTypeKindDescription
idstringRequiredشناسه کسب و کار یا BusinessID (توسط یوآیدی در اختیار شما قرار می‌گیرد)
secretKeystringRequiredتوسط یوآیدی در اختیار شما قرار می‌گیرد

۳.۳. نمونه پاسخ دریافتی

				
					{
    "status": status,
    "error": "error",
    "message": {
        "oauthInformation": {
        "access_token": ACCESS_TOKEN,
        "refresh_token": REFRESH_TOKEN,
        "token_type": TOKEN_TYPE_BEARER,
        "scope": "[read, write]",
        "expires_in": <EXPIRES_IN>
    }
}
				
			

۴. سرویس getUserInfo

بعد از اتمام مراحل احراز هویت clientToken از طریق PWA به redirect_url اعلامی توسط پذیرنده ارسال می‌شود. با استفاده از این توکن، پذیرنده می‌تواند اطلاعات کاربر را دریافت نماید.

۱.۴. نمونه ی درخواست

				
					POST - https://cloud.uid.ir/cryptocore/getUserInfo

Authorization: bearer access_token
Content-Type: application/json;charset=UTF-8
{
   "clientToken": <CLIENT_TOKEN>
}

				
			

۲.۴. توضیح پارامترهای درخواستی

FieldTypeDescription
clientTokenstringشناسه‌ای که توسط یوآیدی به کاربر پذیرنده اختصاص داده می‌شود.

۳.۴. نمونه‌ی پاسخ دریافتی

				
					"status":<REQUEST_STATUS>,
"lastStep": <LAST_STEP>
"error": "error",
"message": {
    "status": STATUS_OF_AUTH
    "name": FIRST_NAME,
    "family": LAST_NAME,
    "nationalCode": NATIONAL_CODE,
    "mobileNumber": MOBILE_NUMBER,
    "birthDate": BIRTH_DATE,
    "metaData": METADATA,
    "bankInfo": {
        "id": id,
        "shabaNumber": SHEBA_NUMBER,
        "bankName": BANK_NAME,
        "cardNumber": CARD_NUMBER,
        "accountNumber": ACCOUNT_NUMBER
    },
    "addressInfo": [
        {
            "state": STATE,
            "city": CITY,
            "userAaddress": ADDRESS,
            "postalCode": POSTAL_CODE
        }
    ]
},
"path": "/getUserInfo"

				
			

۴.۴. توضیح پاسخ های دریافتی

FieldTypeDescription
statusstring – ENUM

موفقیت آمیز: SUCCESS

رد شده: FAILED

در انتظار: سایر مقادیر

lastStep
 string – ENUM

MOBILE_NUMBER_PAGE

CONFIRM_MOBILE_NUMBER_PAGE

IDENTITY_INFORMATION_PAGE

ADDRESS_INFO_PAGE

PHONE_NUMBER_PAGE

CONFIRM_PHONE_NUMBER_PAGE

BANK_INFO_PAGE

NATIONAL_CARD_SERIAL_PAGE

LETTER_OF_COMMITMENT_PAGE

SUCCESS_PAGE

CHECKING_INFORMATION_PAGE

metaDatastringتگ یونیک کاربر*

* مقدار metaData در واقع یک تگ منحصر به فرد برای کاربر است که توسط پذیرنده به یوآیدی ارسال می‌شود. یوآیدی آن را ذخیره نموده و در سرویس‌های واکشی اطلاعات کاربر، این مقدار را در کنار سایر اطلاعات به پذیرنده بر می‌گرداند. به عنوان مثال، پذیرنده می‌تواند با ارسال شناسه کاربر خود (user_id) در تگ metaData، در فراخوانی‌های آتی، این کاربر را تگ گذاری کند.

این تگ در هنگام فراخوانی PWA دریافت می‌گردد (مراجعه به بخش فراخوانی PWA)

۵.۴. سرویس getUserInfo/bulk

این سرویس با دریافت آرایه ای از clientToken ها که شامل تعداد دو یا بیشتر clientToken میشود. پاسخ مشابه نمونه ۳.۴. میباشد.

نمونه درخواست getUserInfo/bulk:

				
					Request:
{ 
  "clientTokens": [CLIENT_TOKEN1, CLIENT_TOKEN2, CLIENT_TOKEN3, …] 
}
				
			

۵. سرویس clientToken

پس از پایان مراحل احراز هویت، برای کاربر توکن با نام clientToken ایجاد و در دیتابیس ذخیره می‌شود. در این سرویس پذیرنده می‌تواند با وارد کردن کد ملی کاربر clientToken مربوط به کاربر را دریافت نماید.

توجه: این سرویس Authenticated بوده و برای فراخوانی آن نیاز است که access_token دریافتی از سرویس لاگین در header ریکوئست قرار داده شود.

۱.۵. نمونه ی درخواست

				
					GET - https://cloud.uid.ir/cryptocore/clientToken/{nationalCode}

Authorization: bearer access_token
Content-Type: application/json;charset=UTF-8
{
   "nationalCode": <NATIONAL_CODE>
}

				
			

۲.۵. توضیح پارامترهای درخواستی

FieldTypeDescription

nationalCode

stringکد ملی کاربر جهت نمایش توکن

۳.۵. نمونه پاسخ دریافتی

				
					"timestamp": "2021-10-30T12:02:53.931+00:00",
"status": 200,
"error": "OK",
"message": <CLIENT_TOKEN>,
"path": "/clientToken/xxxxxxxxxx"

				
			

۶. خطاهای دریافتی

CodeDescription
۴۲۹درخواست بیش از حد مجاز
۴۰۰درخواست نامعتبر
۵۰۰خطای داخلی سرور
۴۰۹شما قبلا احراز هویت شده اید
۴۰۴پذیرنده مورد نظر یافت نشد
۴۰۴کاربر مورد نظر یافت نشد
۵۰۳سرویس در دسترس نمی باشد
۴۱۷ویدیو نامعتبر
۴۰۳دسترسی غیر مجاز به سرویس
مشاوره رایگان