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

e-KYC PWA Documents

نسخه 1.1.1 - 05/01/2024

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

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

۱. مقدمه

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

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

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

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

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

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

۱.۳. ایجاد URL

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

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

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

Field	Type	Kind	Description
request_business_id	string	Required	شناسه کسب‌و‌کار یا BusinessID (توسط یوآیدی در اختیار شما قرار می‌گیرد)
metaData	string	Optional	تگ یونیک کاربر*
phoneNumber	string	Optional	تلفن همراه کاربر با فرمت ۰۹xxxxxxxxx – در صورتی که این پارامتر مقدار داشته باشد، فیلد تلفن همراه در گام اول احراز هویت به صورت Auto-fill و غیرقابل ویرایش تکمیل می‌شود.*

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

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

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

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

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

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

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

				
					BUSINESS_REDIRECT_URL/?clientToken=CLIENT_TOKEN&metaData=METADATA&status=STATUS

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

Field	Type	Description
clientToken	string	شناسه‌ای که توسط یوآیدی به کاربر پذیرنده اختصاص داده می‌شود. در صورتی که مقدار نداشته باشد، یعنی احراز هویت کامل نشده، و درصورتی که مقدار داشته باشد، یعنی مراحل به اتمام رسیده است.
status	Int	وضعیت احراز هویت کاربر (مطابق جدول زیر)

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

Result	Value	Description
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 روند احراز هویت را مشاهده میکنید:

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

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

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

				
					POST - https://api-crypto.uid.ir/business/login


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

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

Field	Type	Kind	Description
id	string	Required	شناسه کسب و کار یا BusinessID (توسط یوآیدی در اختیار شما قرار می‌گیرد)
secretKey	string	Required	توسط یوآیدی در اختیار شما قرار می‌گیرد

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

				
					{
    "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://api-crypto.uid.ir/getUserInfo

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

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

Field	Type	Description
clientToken	string	شناسه‌ای که توسط یوآیدی به کاربر پذیرنده اختصاص داده می‌شود.

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

				
					"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"

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

Field	Type	Description
status	string – 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
metaData	string	تگ یونیک کاربر*

این تگ در هنگام فراخوانی 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://api-crypto.uid.ir/clientToken/{nationalCode}

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

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

Field	Type	Description
nationalCode	string	کد ملی کاربر جهت نمایش توکن

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

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

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

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

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

e-KYC PWA Documents

فهرست مطالب

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

۱. مقدمه

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

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

۱.۳. ایجاد URL

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

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

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

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

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

۱. مقدمه

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

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

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

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

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

۴. سرویس getUserInfo

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

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

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

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

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

۵. سرویس clientToken

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

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

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

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

همکاری خود را با یوآیدی شروع کنید

English

فارسی

English

فارسی

یوآیدی در فضای مجازی

تمامی حقوق برای شرکت بینش هوشمند نسل پیشرو محفوظ است ۱۴۰۲©