مستندات سرویس API احراز هویت آنلاین
e-KYC API Documents
نسخه 1.1.0 - 08/20/2023
فهرست مطالب
بخش اول: (RESTful) فراخوانی API
۱. مقدمه
این بخش مربوط به هدایت کاربر به سرویس احراز هویت آنلاین یوآیدی می‌باشد. فرآیند احراز هویت با استفاده از API دارای ۲ مرحله است. در مرحله اول اطلاعات دریافتی از کاربر توسط پذیرنده به UID ارسال می‌گردد. در ادامه و پس از احراز هویت کاربر، UID آدرس بازگشت اعلامی پذیرنده (callback_url) را با پارامترهای مربوطه فراخوانی کرده و نتیجه را به اطلاع پذیرنده می‌رساند.
۲. روند احراز هویت در API یوآیدی
همانطور که می‌دانید یوآیدی یک سیستم احراز هویت آنلاین بوده و اطلاعات دریافتی شما از این سرویس توسط شخص کاربر ارائه شده و صحت این اطلاعات و عواقب آن برعهده‌ی کاربر است.
برای استفاده از API لازم است پارامترهای مورد نیاز را از طریق فراخوانی سرویس زیر یوآیدی ارسال نمائید.
۳. فراخوانی سرویس authenticate-user-info
برای استفاده از سرویس API یوآیدی می‌بایست سرویس زیر با پارامترهای درخواستی فراخوانی نمائید. این سرویس با دریافت مشخصات و ویدئوی کاربر، احراز هویت آنلاین را انجام می‌دهد و در پاسخ، sessionId کاربر را به پذیرنده باز می‌گرداند.
۱.۳. نمونه درخواست
نمونه‌ی درخواست به شرح زیر است:
POST - https://internal-auth-api.uid.ir/v2/authenticate-user-info
Content-Type: application/json;charset=UTF-8
{
"businessId" : "<business_id>",
"businessToken" : "<business_token>",
"nationalId" : "<national_id>",
"gender" : "<SEX_MALE>-or-<SEX_FEMALE>",
"birthDate" : "<yyyy/mm/dd>",
"downloadLink" : "<VIDEO_DOWNLOAD_LINK>"
}
۲.۳. توضیح پارامترهای درخواست
| Field | Type | Kind | Description |
| businessId | string | Required | شناسه کسب‌و‌کار (توسط یوآیدی در اختیار قرار می‌گیرد) |
| businessToken | string | Required | توکن کسب‌و‌کار (توسط یوآیدی در اختیار قرار می‌گیرد) |
| nationalId | string | Required | کد ملی کاربر |
| gender | string – ENUM | Required | جنسیت SEX_MALE | SEX_FEMALE |
| birthDate | string | Required | تاریخ تولد کاربر با فرمت <yyyy/mm/dd> |
| downloadLink | string – URL | Required | لینک ویدئوی سلفی کاربر جهت احراز هویت** |
* ویدئوی سلفی احراز هویت کاربر توسط پذیرنده دریافت و لینک آن جهت احراز هویت به یوآیدی ارسال می‌شود. توجه داشته باشید رعایت جوانب امنیتی در ایجاد این لینک بسیار حائز اهمیت است. پیشنهاد می‌شود علاوه بر این، مدت زمان اعتبار لینک نیز محدود گردد.
* فرمت ویدئو مورد پذیرش در این بخش mp4 و webm می‌باشد.
۳.۳. نمونه پاسخ
{
"sessionId": USER_SESSION_ID,
"error": ERROR
}
۴.۳. توضیح پارامترهای پاسخ
| Field | Type | Kind | Description |
| sessionId | string | Required | شناسه سشن ایجاد شده برای کاربر در UID* |
| error | string | Required | توضیحات خطا |
* توجه: sessionId یک مقدار یونیک است که یوآیدی به هر کاربر اختصاص می‌دهد.
۴. فراخوانی کال‌بک پذیرنده توسط UID
۱.۴. نمونه فراخوانی کال‌بک
POST - BUSINESS_CALLBACK_URL eg: <https://uid-business.com/uid-callback>
Content-Type: application/json;charset=UTF-8
{
"sessionId" : USER_SESSION_ID,
"status": {
code: CODE,
message: MESSAGE
},
"userInformation" : {
"nationalId": NATIONAL_ID,
"date": DATE,
"sex": SEX
},
"authenticationStatus" : {
"state": STATE,
"reason": REASON
},
}
۲.۴. توضیح پارامترهای ارسالی
| Field | Type | Description |
| sessionId | string | شناسه سشن کاربر در UID |
| code | string | کد وضعیت درخواست |
| message | string | متن مربوط به وضعیت خطای / موفقیت احراز هویت کاربر |
| nationalId | string | کد ملی کاربر |
| date | string | تاریخ تولد کاربر با فرمت <yyyy/mm/dd> |
| sex | string – ENUM | جنسیت SEX_MALE | SEX_FEMALE |
| state | string – ENUM | در انتظار: AUTHENTICATION_STATE_UNDEFINED تایید شده: AUTHENTICATION_STATE_ACCEPTED رد شده: AUTHENTICATION_STATE_REJECTED |
| reason | string – ENUM | توضیحات وضعیت (مطابق جدول زیر) |
۳.۴. جداول توضیحات وضعیت (reason)
| Value | Result | Description |
| AUTHENTICATION_RESPONSE_REASON_UNDEFINED | UNDEFINED | در حال انتظار |
| AUTHENTICATION_RESPONSE_REASON_ACCEPT | ACCEPTED | تایید شده |
| AUTHENTICATION_RESPONSE_REASON_REJECT_FACE_NOT_MATCH_ID | REJECTED | عدم تطبیق چهره با ثبت احوال |
| AUTHENTICATION_RESPONSE_REASON_REJECT_VIDEO_NOT_LIVE | زنده نبودن ویدئو ارسالی | |
| AUTHENTICATION_RESPONSE_REASON_REJECT_VIDEO_BAD_LIGHT | نور نامناسب | |
| AUTHENTICATION_RESPONSE_REASON_REJECT_VIDEO_BAD_QUALITY | عدم وضوح تصویر | |
| AUTHENTICATION_RESPONSE_REASON_REJECT_PERSON_TOO_FAR_AWAY | فاصله بیش از حد با دوربین | |
| AUTHENTICATION_RESPONSE_REASON_REJECT_MORE_THAN_ONE_PERSON | وجود چند چهره | |
| AUTHENTICATION_RESPONSE_REASON_REJECT_NO_PERSON_DETECTED | عدم وجود چهره |
بخش دوم: (gRPC) فراخوانی API
۱. مقدمه
امکان استفاده از API احراز هویت آنلاین UID بر gRPC نیز میسر است.
