سرویس «استعلام کد ملی (Client Credential)» در دسته احراز هویت و شناخت مشتری فینوتک با گرفتن کد ملی و تاریخ تولد، اطلاعات ثبت احوال شخص — از جمله نام، نام خانوادگی، نام پدر و وضعیت حیات — را برمیگرداند. با این سرویس میتوانید بدون نیاز به تایید پیامکی کاربر، درستی هویت اعلامشده در فرمها و پایگاه داده خود را بسنجید.
استعلام کد ملی (Client Credential) چه مشکلی را حل میکند؟
نام و کد ملی، کلید اتصال یک پرونده به یک انسان واقعی است، اما در عمل هر دو دستنویس وارد میشوند: کاربر نام خود را با غلط تایپی مینویسد، کد ملی را یک رقم اشتباه میزند یا کد ملی شخص دیگری را ثبت میکند. تشخیص این خطاها بهصورت سنتی یعنی درخواست تصویر شناسنامه یا کارت ملی، انتظار برای پاسخ مشتری و بازبینی دستی کارشناس؛ فرآیندی که هم روزها طول میکشد و هم به قضاوت انسانی وابسته است. در پروندههای انبوه — مثل فهرست مشتریان قدیمی یا فهرست ذینفعان یک پرداخت گروهی — این روش عملاً قابل اجرا نیست.
این سرویس همان بررسی را به یک فراخوانی سمت سرور تبدیل میکند: کد ملی و تاریخ تولد را میفرستید و اطلاعات ثبت احوال متناظر را میگیرید. خروجی به دو تصمیم وصل میشود؛ اول تطبیق نام اعلامشده کاربر با نام ثبتاحوالی او برای ادامه یا توقف پرونده، و دوم استفاده از وضعیت حیات برای جلوگیری از ادامه فرآیند روی پروندهای که دیگر صاحب زنده ندارد. چون فراخوانی با توکن Client Credential انجام میشود، میتوانید آن را در پردازشهای پشتصحنه و بدون حضور کاربر هم اجرا کنید.
کاربردهای استعلام کد ملی (Client Credential)
- اعتبارسنجی فرم ثبتنام پیش از ساخت پرونده — نام و نام خانوادگی واردشده با اطلاعات ثبت احوال مقایسه میشود تا پرونده با هویت غلط ساخته نشود.
- پاکسازی پایگاه داده مشتریان موجود — پروندههای قدیمی که در دورههای کاغذی ثبت شدهاند، بهصورت دستهای بازبینی و هویتهای مخدوش علامتگذاری میشوند.
- کنترل فهرست ذینفعان پیش از پرداخت گروهی — در پرداخت خسارت بیمه، پورسانت، حقوق و دستمزد یا جایزه، هویت افراد فهرست پیش از صدور دستور پرداخت بررسی میشود.
- پروندهسازی اعتباری در لیزینگ و خرید اقساطی — هویت متقاضی و ضامن پیش از تنظیم قرارداد تایید میشود.
- بازبینی خودکار پرونده بازمانده و وراث — وضعیت حیات بهعنوان یکی از سیگنالهای بستن یا انتقال پرونده در سامانه شما استفاده میشود.
- کاهش تقلب در برنامههای تشویقی — پیش از اعطای امتیاز یا اعتبار هدیه، هویتهای ساختگی و تکراری غربال میشوند.
مزایای استعلام کد ملی (Client Credential)
- اجرای بدون حضور کاربر — فراخوانی به تایید پیامکی مشتری در همان لحظه گره نمیخورد و در پردازشهای زمانبندیشده هم قابل استفاده است.
- پاسخ ساختیافته برای تصمیم خودکار — خروجی مستقیم به قاعدههای تایید، رد یا ارسال به بررسی دستی وصل میشود.
- پوشش وضعیت حیات در همان فراخوانی — لازم نیست برای این سیگنال درخواست جداگانهای طراحی کنید.
- در دسترس بودن در تمام ساعات شبانهروز — بر اساس مشخصات سرویس، این استعلام در تمامی ساعات شبانهروز فعال است و به بازه زمانی محدود نمیشود.
- نسخه پیامکی هم موجود است — اگر جریان کاری شما باید رضایت صریح کاربر را ثبت کند، استعلام کد ملی (Authorization SMS) همان خروجی را با تایید پیامکی میدهد.
چه چیزی از استعلام کد ملی (Client Credential) دریافت میکنید؟
جزئیات ورودی، خروجی و نمونه پاسخ در مستندات فنی آمده است.
جریان کار استعلام کد ملی (Client Credential)
- ۱. ساخت کلاینت و گرفتن توکن — با اسکوپ
facility:cc-nid-inquiry:getتوکن Client Credential بگیرید. - ۲. ارسال کد ملی و تاریخ تولد — درخواست را همراه شناسه پیگیری بفرستید تا فراخوانی قابل ردیابی باشد.
- ۳. خواندن اطلاعات هویتی — نام، نام خانوادگی، نام پدر، تاریخ تولد و وضعیت حیات را از پاسخ بردارید.
- ۴. اعمال قاعده کسبوکاری — نام بازگشتی را با نام اعلامشده کاربر تطبیق دهید و بر اساس نتیجه و وضعیت حیات، پرونده را تایید، رد یا به بررسی دستی بفرستید.
- ۵. ثبت نتیجه برای ممیزی — نتیجه استعلام و شناسه پیگیری را در سابقه پرونده ذخیره کنید.
نحوه شروع استعلام کد ملی (Client Credential)
این سرویس با رویکرد Client Credential (بدون رضایت پیامکی) فراخوانی میشود. اسکوپ مورد نیاز: facility:cc-nid-inquiry:get. ابتدا کلاینت بسازید و توکن بگیرید: راهنمای شروع. سپس از مستندات فنی برای پیادهسازی استفاده کنید.
محدودیتها و نکات استعلام کد ملی (Client Credential)
- تاریخ تولد ورودی اجباری است و باید در قالب
yyyy/mm/ddفرستاده شود؛ اگر با کد ملی همخوان نباشد، استعلام به نتیجه نمیرسد، پس تبدیل قالب ورودی کاربر را در سمت خود انجام دهید. - در تطبیق نام، تفاوتهای نگارشی مانند نیمفاصله، «ي» و «ك» عربی و فاصلههای اضافه را پیش از مقایسه نرمالسازی کنید تا تطبیقهای درست، اشتباهاً رد نشوند.
- شناسه پیگیری اختیاری است، اما ارسال مقدار یکتا برای هر فراخوانی پیگیری خطاها و رسیدگی به اختلافها را ساده میکند.
- نتیجه استعلام تصویری از همان لحظه است؛ برای تصمیمهای بعدی، بهویژه در پروندههای بلندمدت، استعلام را تکرار کنید.
- این سرویس هویت شخص را تایید میکند، نه مالکیت شماره موبایل یا حساب بانکی او؛ برای آن سیگنالها به سرویسهای تطبیق جداگانه نیاز دارید.
- دادههای ثبت احوال، داده شخصی است؛ فقط برای همان هدف کسبوکاری نگه دارید و دسترسی به آن را محدود کنید.
سوالات متداول استعلام کد ملی (Client Credential)
استعلام کد ملی (Client Credential) چیست؟
سرویسی است که با دریافت کد ملی و تاریخ تولد، اطلاعات ثبت احوال شخص — نام، نام خانوادگی، نام پدر، تاریخ تولد و وضعیت حیات — را بهصورت داده ساختیافته برمیگرداند تا هویت اعلامشده مشتری سنجیده شود.
تفاوت این سرویس با نسخه Authorization SMS چیست؟
خروجی یکی است، مسیر دسترسی متفاوت: این نسخه با توکن Client Credential و بدون تایید پیامکی فراخوانی میشود و برای پردازشهای سمت سرور و بازبینی انبوه مناسب است؛ اگر جریان کاری شما باید رضایت خود شخص را ثبت کند، استعلام کد ملی (Authorization SMS) را انتخاب کنید.
آیا این سرویس فقط اعتبار کد ملی را بررسی میکند؟
نه؛ علاوه بر صحت کد ملی، اطلاعات هویتی متناظر آن هم بازگردانده میشود و میتوانید آن را با اطلاعات مشتری در سامانه خود تطبیق دهید.
تفاوت این سرویس با استعلام وضعیت حیات چیست؟
اگر تنها به وضعیت حیات نیاز دارید، استعلام وضعیت حیات پاسخ متمرکزتری میدهد؛ این سرویس وضعیت حیات را در کنار مجموعه کاملتری از اطلاعات هویتی برمیگرداند.
مستندات فنی این سرویس کجاست؟
صفحه مشخصات API شامل endpoint، پارامترها و نمونه پاسخ است.
چه نوع احراز هویتی لازم است؟
Grant type: client_credentials. جزئیات در راهنمای توکن.
آیا رضایت پیامکی کاربر لازم است؟
خیر. این سرویس با Client Credential و بدون رضایت پیامکی قابل فراخوانی است.
مستندات فنی استعلام کد ملی (Client Credential)
مشاهده مستندات فنی «استعلام کد ملی (Client Credential)» — endpoint، پارامترها، نمونه درخواست و پاسخ.