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

e-KYC API Documents

نسخه 1.0.1 - 11/22/2025

بخش اول: (RESTful) فراخوانی API

۱. مقدمه

این بخش مربوط به هدایت کاربر به سرویس احراز هویت آنلاین یوآیدی می‌باشد. فرآیند احراز هویت با استفاده از API دارای ۲ مرحله است. در مرحله اول اطلاعات دریافتی از کاربر توسط پذیرنده به UID ارسال می‌گردد. در ادامه و پس از احراز هویت کاربر، UID آدرس بازگشت اعلامی پذیرنده (callback_url) را با پارامتر‌های مربوطه فراخوانی کرده و نتیجه را به اطلاع پذیرنده می‌رساند.

۲. روند احراز هویت در API یوآیدی

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

برای استفاده از API لازم است پارامترهای مورد نیاز را از طریق فراخوانی سرویس زیر یوآیدی ارسال نمائید.

۳. فراخوانی سرویس authenticate-user-info

برای استفاده از سرویس API یوآیدی می‌بایست سرویس زیر با پارامتر‌های درخواستی فراخوانی نمائید. این سرویس با دریافت مشخصات، عکس مرجع و ویدئوی کاربر، احراز هویت آنلاین را انجام می‌دهد و در پاسخ، sessionId کاربر را به پذیرنده باز می‌گرداند.

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

نمونه‌ی درخواست به شرح زیر است:

				
					POST https://api-bff.uid.ir/api/v3.1/simplified/authentication

Content-Type: application/json;charset=UTF-8
{
  "businessId": "<business_id>",
  "businessToken": "<business_token>",
  "nationalId": "<national_id>",
  "gender": "<GENDER_UNDEFINED>-or-<GENDER_MALE>-or-<GENDER_FEMALE>",
  "birthDate": "<yyyy/mm/dd>",
  "downloadLink": "<VIDEO_DOWNLOAD_LINK>",
  "imageBase64":"<IMAGE_BASE_64>",
  "asrText":"<ASR_TEXT>"
}

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

Field	Type	Kind	Description
businessId	string	Required	شناسه کسب‌و‌کار (توسط یوآیدی در اختیار قرار می‌گیرد)
businessToken	string	Required	توکن کسب‌و‌کار (توسط یوآیدی در اختیار قرار می‌گیرد)
nationalId	string	Required	کد ملی کاربر
gender	string – ENUM	Required	جنسیت GENDER_FEMALE \| GENDER_MALE \| GENDER_UNDEFINED
birthDate	string	Required	تاریخ تولد کاربر با فرمت <yyyy/mm/dd>
downloadLink	string – URL	Required	لینک ویدئوی سلفی کاربر جهت احراز هویت**
imageBase64	string	Required	عکس مرجع بصورت base64
asrText	string	Required	متن خوانده شده در ویدیو

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

* فرمت ویدئو مورد پذیرش در این بخش mp4 و webm می‌باشد.

* فرمت عکس مرجع میبایست base64 باشد.

* متن ASR فعلا تطبیق داده نمیشود

۳.۳. نمونه پاسخ

				
					{
  "sessionId": USER_SESSION_ID,
  "error": ERROR
}

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

Field	Type	Kind	Description
sessionId	string	Required	شناسه سشن ایجاد شده برای کاربر در UID*
error	string	Required	توضیحات خطا

* توجه: sessionId یک مقدار یونیک است که یوآیدی به هر کاربر اختصاص می‌دهد.

۴. فراخوانی کال‌بک پذیرنده توسط UID

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

۱.۴. نمونه فراخوانی کال‌بک

کال‌بک پذیرنده با آبجکت زیر و متد POST فراخوانی می‌شود:

				
					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,
        "birthDate": BIRTH_DATE,
        "gender": GENDER,
    },
    "authenticationStatus" : {
        "finalAuthenticationResult": FinalAuthenticationResult,
        "finalAuthenticationResultReason": FinalAuthenticationResultReason
    },
}

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

Field	Type	Description
sessionId	string	شناسه سشن کاربر در UID
code	string	کد وضعیت درخواست
message	string	متن مربوط به وضعیت خطای / موفقیت احراز هویت کاربر
nationalId	string	کد ملی کاربر
birthDate	string	تاریخ تولد کاربر با فرمت <yyyy/mm/dd>
gender	string – ENUM	جنسیت GENDER_FEMALE \| GENDER_MALE \| GENDER_UNDEFINED
finalAuthenticationResult	string – ENUM	در انتظار: FINAL_AUTHENTICATION_RESULT_UNDEFINED تایید شده: FINAL_AUTHENTICATION_RESULT_ACCEPTED رد شده: FINAL_AUTHENTICATION_RESULT_REJECTED
finalAuthenticationResultReason	string – ENUM	توضیحات وضعیت (مطابق جدول زیر)

۳.۴. جداول توضیحات وضعیت (finalAuthenticationResultReason)

Value	Result	Description
FINAL_AUTHENTICATION_RESULT_REASON_UNDEFINED	UNDEFINED	در حال انتظار
FINAL_AUTHENTICATION_RESULT_REASON_ACCEPT	ACCEPTED	تایید شده
FINAL_AUTHENTICATION_RESULT_REASON_REJECT_FACE_NOT_MATCH_IMAGE_ID	REJECTED	عدم تطبیق چهره با ثبت احوال
FINAL_AUTHENTICATION_RESULT_REASON_REJECT_VIDEO_NOT_LIVE		زنده نبودن ویدئو ارسالی
FINAL_AUTHENTICATION_RESULT_REASON_REJECT_VIDEO_BAD_LIGHT		نور نامناسب
FINAL_AUTHENTICATION_RESULT_REASON_REJECT_INCOMPATIBLE_HEJAB		حجاب نامناسب
FINAL_AUTHENTICATION_RESULT_REASON_REJECT_INCOMPATIBLE_ANGLE_CAMERA		زاویه نامناسب دوربین
FINAL_AUTHENTICATION_RESULT_REASON_REJECT_INCOMPATIBLE_BACKGROUND		پس زمینه نامناسب
FINAL_AUTHENTICATION_RESULT_REASON_REJECT_INCOMPATIBLE_LOOK_CAMERA		عدم نگاه کردن به دوربین
FINAL_AUTHENTICATION_RESULT_REASON_REJECT_VIDEO_BAD_QUALITY		عدم وضوح تصویر
FINAL_AUTHENTICATION_RESULT_REASON_REJECT_PERSON_TOO_FAR_AWAY		فاصله بیش از حد با دوربین
FINAL_AUTHENTICATION_RESULT_REASON_REJECT_MORE_THAN_ONE_PERSON		وجود چند چهره
FINAL_AUTHENTICATION_RESULT_REASON_REJECT_NO_PERSON_DETECTED		عدم وجود چهره
FINAL_AUTHENTICATION_RESULT_REASON_REJECT_FAKE_VIDEO		ویدیو فیک / کیفیت پایین ویدیو
FINAL_AUTHENTICATION_RESULT_REASON_REJECT_INVALID_SIGNATURE		مغایرت امضا
FINAL_AUTHENTICATION_RESULT_REASON_REJECT_USER_DID_NOT_SPEAK_REQUIRED_TEXT		مغایرت متن ارسالی و متن بازگوشده کاربر