شناسه فراگیر اتباع خارجی چیست و چه فرقی با کد ملی دارد؟
شناسه فراگیر اتباع شماره‌ای است که برای مقیمان غیرایرانی جای کد ملی را می‌گیرد، با قالبی متفاوت، و استعلامش هویت می‌دهد نه وضعیت اقامت.
شناسهٔ فراگیر اتباع جای کد ملی را برای مقیمان غیرایرانی می‌گیرد، و قالبش با کد ملی ایرانی یکی نیست. اگر فرم شما فقط کد ملی ایرانی می‌پذیرد، این گروه از همان کادر اول بیرون می‌ماند.
این نوشته برای کسی است که می‌خواهد بفهمد این شناسه چیست، با کد ملی کجا فرق دارد، و چه چیزی را نمی‌شود از آن درآورد. اگر دنبال استعلام برنامه‌نویسی‌اش هستید، استعلام هویت اتباع خارجی همین کار را با یک فراخوان انجام می‌دهد.
شناسهٔ فراگیر چیست و کجا دیده می‌شود
شناسه‌ای است که برای اتباع خارجی مقیم صادر می‌شود تا در بانک، معاملات و خدمات اداری بتوانند به‌جای کد ملی از آن استفاده کنند. در فرم ما توضیح کادرش این است: شماره اختصاصی اتباع که روی کارت یا برگهٔ هویتی آمده.
منابع فارسی که این موضوع را شرح داده‌اند، دربارهٔ طول و محل چاپ شماره یک‌دست نیستند: بعضی عدد ۱۲ رقمی می‌گویند و ما در مستند سرویس بازهٔ دیگری می‌بینیم. به همین دلیل ما در اعتبارسنجی ورودی عدد ثابتی را فرض نکرده‌ایم و بازهٔ ده تا شانزده رقم را می‌پذیریم. اگر بخواهید فرم خودتان را بنویسید، همین سخت‌نگرفتن را الگو کنید.
یک چیز دیگر که منابع اشاره می‌کنند: اگر شماره گم شود، راهی برای بازیابی آن در سامانهٔ صدورش وجود دارد. ما این مسیر را بررسی نکرده‌ایم و جزئیاتش را اینجا نمی‌نویسیم؛ به کاربر بگویید از مرجع صدور پیگیری کند.
چهار فرق عملی با کد ملی
پیش از جزئیات، صفحهٔ سرویس استعلام اتباع فهرست ورودی و خروجی را کنار هم دارد؛ اینجا فقط فرق‌های عملی را می‌گوییم.
طول و الگو
کد ملی ایرانی همیشه ده رقم است و رقم آخرش کنترلی است. شناسهٔ فراگیر این ساختار را به ما نشان نمی‌دهد. مستندی که الگوریتم رقم کنترلی آن را بگوید در دست نداریم، و ساختن قاعده‌ای که مستند نگفته یعنی ممکن است شناسهٔ معتبر را رد کنیم. پس سمت ما فقط طول و رقم بودن بررسی می‌شود و درستی را مرجع می‌گوید.
چیزی به نام تاریخ تولد در ورودی نیست
برخلاف بیشتر استعلام‌های هویتی ایرانی که کد ملی را با تاریخ تولد می‌گیرند، این سرویس فقط شناسه را می‌خواهد. ورودی یک کادر است.
خروجی فیلد بیشتری دارد
نام، نام خانوادگی، نام پدر، نام جد، تاریخ تولد، جنسیت، ملیت و استان. جنسیت به فارسی برمی‌گردد (مرد یا زن)، نه به شکل کد. نام جد معادل مستقیم در هویت ایرانی ندارد؛ آن را به نام پدر نگاشت نکنید.
نتیجه هویت است، نه اجازه
این مهم‌ترین فرق است و بحث بعدی دربارهٔ آن است.
هویت چیزی است و وضعیت اقامت چیز دیگر
استعلام می‌گوید این شناسه به چه شخصی تعلق دارد. نمی‌گوید اقامتش معتبر است، پروانهٔ کار دارد یا اجازهٔ فلان فعالیت را دارد. فرض کنید یک پلتفرم خدمات مالی شناسه‌ای را استعلام می‌کند و اطلاعات برمی‌گردد. اگر پلتفرم از همین نتیجه نتیجه بگیرد «پس مجاز است»، اشتباه کرده است. هویت شرط لازم است، نه کافی.
اگر کسب‌وکار شما به وضعیت اقامت یا پروانه حساس است (مثلاً استخدام)، این سرویس بخشی از پاسخ است نه همه‌اش. بخش دیگر را باید از مدرک و فرایند خودتان بگیرید.
چرا ملیت و استان را نباید پیش‌فرض بگیرید
در خروجی فیلدهای ملیت و استان هست، ولی هر پاسخی همه‌شان را ندارد. فیلدی که خالی است در پاسخ نمی‌آید. در کدتان وجود هر فیلد را مشروط بخوانید. تصور کنید جدول مشتری شما ستون ملیت را اجباری کرده باشد؛ اولین پاسخی که آن را ندارد ثبت‌نام را می‌شکند.
یک نمونهٔ فراخوان
bash curl -X POST 'https://example.com/api/v1/foreigner-identity/' \ -H 'Authorization: Bearer YOUR_KEY' \ -H 'Content-Type: application/json' \ -d '{"fida":"0123456789"}'
نشانی و کلید را با مقدار خودتان عوض کنید؛ ساختار پاسخ و خطاها در مستندات API آمده است. توجه کنید که «رکوردی نیست» هم پاسخ معتبری است که هزینه دارد، پس پیش از ارسال طول و رقم‌بودن را خودتان بسنجید.
آنچه این استعلام نمی‌کند
- وضعیت اقامت، پروانهٔ کار و اعتبار مدرک را نشان نمی‌دهد.
- اطلاعات را با ادعای کاربر مقایسه نمی‌کند؛ این مقایسه سمت شماست.
- عکس نمی‌دهد و نمی‌گوید شخص پشت صفحه همان صاحب شناسه است. برای آن احراز زنده و بیومتریک مسیر دیگری است.
پرسش‌هایی که معمولاً پیش می‌آید
آیا می‌شود شناسه را بدون تاریخ تولد استعلام کرد؟
بله، ورودی سرویس فقط شناسه است. این برخلاف استعلام‌های کد ملی ایرانی است که معمولاً تاریخ تولد هم می‌خواهند. نتیجه‌اش این است که فرم شما نباید از اتباع تاریخ تولد را فقط برای استعلام بپرسد؛ اگر برای کار دیگری لازم است بپرسید، ولی بدانید این سرویس به آن نیاز ندارد.
اگر کاربر شناسه را اشتباه وارد کند چه می‌شود؟
دو حالت داریم. اگر طول یا کاراکتر نامعتبر باشد، پیش از ارسال و بدون هزینه رد می‌شود. اگر شکل درست داشته باشد ولی رکوردی نباشد، پاسخ «رکوردی نیست» می‌گیرید که پاسخ معتبری است و هزینه دارد. به همین دلیل خوب است کاربر قبل از ارسال شناسه‌اش را در یک مرحلهٔ تأیید دوباره ببیند.
جنسیت و فیلدهای دیگر چطور برمی‌گردند؟
جنسیت به فارسی (مرد یا زن) می‌آید، پس جدول نگاشت نمی‌خواهید. نام‌ها همان‌طور که ثبت شده‌اند می‌آیند. فیلدی که مقدار نداشته باشد در پاسخ نمی‌آید، پس خواندنشان را مشروط بنویسید.
چه کسانی از این استعلام سود می‌برند
سه نوع محصول را تصور کنید: یک سرویس مالی که می‌خواهد برای مقیمان غیرایرانی حساب بگشاید، یک پلتفرم خدمات که می‌خواهد پروندهٔ مشتری را کامل کند، و یک کسب‌وکار که ثبت‌نام را خودکار می‌کند. هر سه یک چیز مشترک دارند: بدون این مسیر، یا کاربر را رد می‌کنند یا مدارک را دستی بررسی می‌کنند. مسیر خودکار فقط هویت را می‌دهد و باقی کنترل‌ها همچنان با شماست.
چند نکتهٔ طراحی برای نمایش شناسه
شناسه را به کاربر کامل نشان ندهید. در سرویس ما هم شناسه در خلاصهٔ سفارش به شکل ماسک‌شده می‌آید (فقط چهار رقم آخر). همین الگو را در رابط خودتان بگیرید، چون در رسید و ایمیل و لاگ، شناسهٔ کامل مشکل ایجاد می‌کند.
ارقام را در رابط فارسی با ارقام فارسی نشان بدهید، ولی در داده و در ارسال به API همان لاتین بمانند. اگر کاربر فارسی تایپ کند، پیش از اعتبارسنجی به لاتین ببرید؛ این کار را یک تابع ساده انجام می‌دهد و از رد بی‌دلیل جلوگیری می‌کند.
خلاصه برای مرور بعدی
شناسهٔ فراگیر یک ورودی دوم در فرم شماست، نه نسخهٔ دیگری از کد ملی. اعتبارسنجی‌اش را سخت‌گیرانه ننویسید، فیلدهای خروجی را اختیاری بخوانید، و هویت را با مجوز اشتباه نگیرید. طراحی فرم را در نوشتهٔ ثبت‌نام اتباع ادامه داده‌ایم.
راهنماهای مرتبط
پرسش و تجربه کاربران
اگر این راهنما جوابتان را نداد، همین‌جا بپرسید. پرسش‌ها را تیمملی ای‌پی‌آی پاسخ می‌دهد و هر نظر پیش از انتشار بررسی می‌شود.
هنوز پرسشی ثبت نشده، اولین نفر باشید.