تشخیص اسناد هویتی
خدمت‌دهنده
گروه هوش مصنوعی بارای
مقدمه
مجموعه سرویس تشخیص اسناد هویتی شامل کارت ملی قدیم و کارت ملی جدید و شناسنامه قدیم و شناسنامه جدید و شناسنامه زیر 15 سال میباشد، به صورتی که تصویر مربوط به سند را دریافت کرده و نوع مدرک را مشخص می نماید.
همچنین قادر است در با دریافت تصویر کارت ملی جدید (پشت و رو) مشخصات روی کارت شامل نام و نام خانوادگی ، سریال کارت ، نام پدر و تاریخ انقضاء کارت و نیز تصویر صاحب کارت ملی را استخراج و در خروجی نمایش دهد.
علاوه بر آن قادر است با ارسال اطلاعات تصویر امضاء اشخاص بر اساس میزان حساسیت دلخواه میزان تطابق تصویر دریافتی با امضاء را تشخیص دهد.
پیش از شروع
آدرس فراخوانی سرویس ها
https://api.pod.ir/srv/sc/nzh/doServiceCall
تمامی درخواست ها با متد Post ارسال می شود
Header درخواست ها
پارامترهای زیر در Header تمام درخواست ها ثابت است
| پارامتر | توضیحات |
| _token_ | API token دریافتی از پنل کسب و کاری |
| _token_issuer_ | این پارامتر دارای مقدار ثابت "1" می باشد |
| Content-Type | مقدار ثابت application/x-www-form-urlencoded |
به UnderLine قبل و بعد از نام پارامترها دقت نمایید
Body درخواست ها
همچنین پارامترهای زیر در Body درخواست ها نیز ثابت است
| پارامتر | توضیحات |
| ScProductId | شناسه سرویس |
| ScApiKey | API Key دریافتی برای سرویس مورد نظر از پنل کسب و کاری
|
برای دریافت API KEY از طریق پنل کاربری پادیوم اقدام نمایید.
ارسال درخواست فعالسازی از سایت پادیوم و دریافت کلید از طریق پنل کسب وکار
توجه داشته باشید که درخواست از سایت ، برای سرویسهایی است که در حال حاضر در بازارچه موجود می باشند
-
دریافت نوع سند هویتی
این سرویس مربوط به اسناد هویتی شامل کارت ملی قدیم و کارت ملی جدید و شناسنامه قدیم و شناسنامه جدید و شناسنامه زیر 15 سال میباشد، به صورتی که تصویر مربوط به سند را دریافت کرده و نوع مدرک را طبق جدول شماره 6 مشخص می نماید.
همچنین قادر است میزان زاویه چرخش تصویر مدرک را نیز بر حسب درجه از 0 تا 270 و مطابق جدول شماره 7 مشخص نماید.
نکته مهم :
تصویر مدرک باید حاوی اطلاعات کد شده به صورت base64 ارسال گردد.
- شناسه سرویس : 1336224
- پارامتر ورودی سرویس
| نام پارامتر | نوع | اختیاری / اجباری | توضیحات |
| image_base64 | String | اجباری | اطلاعات base64 تصویر مدرک |
جدول 3 : پارامترهایی که باید ارسال گردد.
- پارامتر های خروجی :
| نام پارامتر | نوع | توضیحات |
| hasError | bool | نشان دهنده ی این است که آیا سرویس با موفقیت از روی پلتفرم پاد فراخوانی شده است یا خیر. |
| messageId | int | پارامتر درون پلتفرمی ای که با توجه به این سرویس خاص موضوعیت ندارد. |
| referenceNumber | string | شناسه ی درخواست در پلتفرم پاد. |
| errorCode | int | کد ارور پلتفرمی. |
| Count | int | پارامتر درون پلتفرمی ای که با توجه به این سرویس خاص موضوعیت ندارد. |
| Ott | string | پارامتر درون پلتفرمی ای که با توجه به این سرویس خاص موضوعیت ندارد. |
| Result | object | نتیجه ی فراخوانی سرویس در این آبجکت نمایش داده می شود که در ادامه شرح داده خواهد شد. |
جدول 4 : پاسخی که از وب سرویس دریافت خواهید کرد.
نکته: طبق موارد مطرح شده، پاسخ مد نظر سرویس دریافت اطلاعات اسناد هویتی در فیلد result موجود است.
به صورت دقیق تر، بدنه ی پاسخ را میتوان در فیلد result مشاهده کرد که دارای ساختار زیر است:
- پارامتر های پاسخ سرویس در Result :
| نام پارامتر | نوع | توضیحات |
| doc_type | String | نوع مدرک بر اساس یکی از مقادیر جدول زیر مشخص می گردد. |
| doc_type_id | int | شناسه مدرک بر اساس جدول زیر مشخص می گردد. |
| doc_rotation | int | میزان چرخش تصویر مدرک از0 تا270 درجه مشخص می گردد. |
جدول 5 : پاسخ نتیجه اطلاعات تصویر ارسالی
هر کدام از فیلدهای بالا مقادیر مختلفی میتوانند داشته باشند. در جداول زیر مقادیر ممکن هر فیلد مشخص شده است:
- مقادیر مختلف مدرک (doc_type):
| توضیح | Doc_type | Doc_type_id |
| کارت ملی هوشمند – جلو | National-card | 0 |
| کارت ملی هوشمند - پشت | National-card-back | 1 |
| کارت ملی قدیم – جلو | Old-national-card | 2 |
| کارت ملی قدیم – پشت | Old-national-card-back | 3 |
| شناسنامه جدید | Birth-certificate | 4 |
| شناسنامه جدید زیر 15 سال | Birth-certificate-u15 | 5 |
| شناسنامه قدیم | Birth-certificate-old | 6 |
| دیگر مدارک | Other | 7 |
| نامعتبر | Invalid | 8 |
جدول 6 : انواع مدارک قابل شناسایی در این سرویس
نکته :
مقادیر فیلدهایdoc_type و doc_type_id مستقل از هم نیست. یعنی هر مقدار فیلد doc_type یک مقدار مشخص و معینی برای doc_type_id دارد.
- مقادیر زاویه چرخش مدرک (doc_rotaion):
| توضیح | Doc_type |
| بدون چرخش | 0 |
| 90 درجه ساعت گرد | 90 |
| 90 درجه پاد ساعت گرد | 270 |
| 180 درجه چرخش | 180 |
جدول 7 : انواع زوایای قابل تشخیص در این سرویس
-
دریافت اطلاعات کارت ملی جدید (پشت و رو)
این سرویس مربوط به کارت ملی جدید می باشد، به صورتی که تصویر مربوط به کارت ملی جدید (روی کارت ملی یا پشت کارت ملی ) را دریافت کرده و اطلاعات موجود روی کارت ملی شامل : کدملی – نام – نام خانوادگی – نام پدر – تاریخ تولد – تاریخ انقضاء کارت و همچنین سریال پشت کارت ملی (در صورت ارسال اطلاعات تصویر پشت کارت ملی جدید) را در پاسخ سرویس نمایش می دهد.
همچنین قادر است اطلاعات تصویر فرد روی کارت ملی را در پاسخ سرویس به صورت base64 ارسال کرده و نیز میزان زاویه چرخش تصویر را بر حسب درجه از 0 تا 270 و مطابق جدول شماره 11 مشخص نماید.
نکته مهم :
صرفا باید تصویر کارت ملی جدید و حاوی اطلاعات کد شده به صورت base64 ارسال گردد.
- شناسه سرویس : 1353772
- پارامتر ورودی سرویس
| نام پارامتر | نوع | اختیاری / اجباری | توضیحات |
| image_base64 | String | اجباری | اطلاعات base64 تصویر مدرک |
| doc_type | String | اجباری | متناسب با درخواست، برای خواندن اطلاعات کارت ملی |
| return_face | Bool | اختیاری | خواندن اطلاعات تصویر فرد روی کارت ملی |
جدول 3 : پارامترهایی که باید ارسال گردد.
نکات :
1- فیلد type_doc را متناسب با درخواست روی کارت ملی (national-card) یا پشت کارت ملی هوشمند (national-card-back) و یا حالت خودکار (auto) تکمیل نمایید.
توجه: مقدار auto در type_doc به معنای تشخیص خودکار نوع مدرک و چرخش آن خواهد بود.
2- فیلد base64_image باید حاوی اطلاعات کد شده ی base64 مربوط به تصویر باشد.
3- فیلد return_face اختیاری است و مقدار پیشفرض آن برابر false است و در صورتی که true ارسال گردد تصویر فرد روی کارت ملی به صورت base64 در پاسخ سرویس ارسال می شود.
4- ارسال سایر پارامتر های مربوط به کسب و کار و شناسه سرویس اجباری میباشد.
5- درصورتی که هریک از فیلد های اجباری به صورت صحیح ارسال نگردد سرویس خطای مربوطه را به در پاسخ (پارامتر result )نمایش خواهد داد.
- پارامتر های خروجی :
| نام پارامتر | نوع | توضیحات |
| hasError | bool | نشان دهنده ی این است که آیا سرویس با موفقیت از روی پلتفرم پاد فراخوانی شده است یا خیر. |
| messageId | int | پارامتر درون پلتفرمی ای که با توجه به این سرویس خاص موضوعیت ندارد. |
| referenceNumber | string | شناسه ی درخواست در پلتفرم پاد. |
| errorCode | int | کد ارور پلتفرمی. |
| Count | int | پارامتر درون پلتفرمی ای که با توجه به این سرویس خاص موضوعیت ندارد. |
| Ott | string | پارامتر درون پلتفرمی ای که با توجه به این سرویس خاص موضوعیت ندارد. |
| Result | object | نتیجه ی فراخوانی سرویس در این آبجکت نمایش داده می شود که در ادامه شرح داده خواهد شد. |
جدول 4 : پاسخی که از وب سرویس دریافت خواهید کرد.
نکته: طبق موارد مطرح شده، پاسخ سرویس دریافت اطلاعات کارت ملی در فیلد result موجود است.
به صورت دقیق تر، بدنه ی پاسخ را میتوان در فیلد result مشاهده کرد که دارای ساختار زیر است:
- پارامتر های پاسخ سرویس در Result :
- اگر درخواست مربوط به تصویر روی کارت ملی هوشمند باشد، پاسخ به شکل زیر خواهد بود:
| نام پارامتر | نوع | توضیحات |
| uid | String | شناسه منحصر به فرد |
| doc_type | String | نوع کارت یا مدرک هویتی |
| Data | Json | اطلاعات استخراج شده از کارت ملی (جدول شماره 6) |
| detection_data | Json | اطلاعات مربوط به تصویر کارت ملی (جداول شماره 9) |
| face_crop_image | String | اطلاعات base64 تصویر فرد (درصورتی که فیلد مربوطه ارسال شود) |
| is_face_detected | Bool | پاسخی که در صورتی که تصویر فرد روی کارت ملی تشخیص داده شود. |
جدول 5 : پاسخ نتیجه اطلاعات تصویر روی کارت ملی
هر کدام از فیلدهای بالا مقادیر مختلفی میتوانند داشته باشند. در جداول زیر مقادیر ممکن هر فیلد مشخص شده است:
- مقادیر مختلف در پاسخ سرویس مربوط به پارامتر (Data):
| نام پارامتر | توضیح |
| code_id | کد ملی |
| name_last | نام خانوادگی |
| expiration_date | تاریض انقضاء کارت |
| birth_date | تاریخ تولد |
| first_name | نام |
| Fathers_name | نام پدر |
جدول 6 : مقادیر پارامتر Data در خروجی پاسخ سرویس
- اگر درخواست مربوط به تصویر روی کارت ملی هوشمند باشد، پاسخ به شکل زیر خواهد بود:
| نام پارامتر | نوع | توضیحات |
| uid | String | شناسه منحصر به فرد |
| doc_type | String | نوع کارت یا مدرک هویتی |
| Data | Json | اطلاعات استخراج شده از کارت ملی (جدول شماره 8) |
| detection_data | Json | اطلاعات مربوط به تصویر کارت ملی (جداول شماره 10 و 11) |
جدول 7: پاسخ نتیجه اطلاعات تصویر پشت کارت ملی
هر کدام از فیلدهای بالا مقادیر مختلفی میتوانند داشته باشند. در جداول زیر مقادیر ممکن هر فیلد مشخص شده است:
- مقادیر مختلف در پاسخ سرویس مربوط به پارامتر (Data):
| نام پارامتر | توضیح |
| serial | شامل سریال پشت کارت ملی |
جدول 8 : مقادیر پارامتر Data در خروجی پاسخ سرویس
- مقادیر مختلف در پاسخ سرویس مربوط به پارامتر (Detection_data):
| نام پارامتر | توضیح |
| doc_type | نوع کارت ملی (جدول شماره 10) |
| doc_type_id | شناسه کارت ملی (جدول شماره 10) |
| doc_rotaion | زاویه چرخش تصویر (جدول شماره 11) |
جدول 9 : مقادیر پارامتر Detection_data در خروجی پاسخ سرویس
- مقادیر مختلف مدرک (doc_type):
| توضیح | Doc_type | Doc_type_id |
| کارت ملی هوشمند – جلو | National-card | 0 |
| کارت ملی هوشمند - پشت | National-card-back | 1 |
| کارت ملی قدیم – جلو | Old-national-card | 2 |
| کارت ملی قدیم – پشت | Old-national-card-back | 3 |
| شناسنامه جدید | Birth-certificate | 4 |
| شناسنامه جدید زیر 15 سال | Birth-certificate-u15 | 5 |
| شناسنامه قدیم | Birth-certificate-old | 6 |
| دیگر مدارک | Other | 7 |
| نامعتبر | Invalid | 8 |
جدول 10: انواع مدارک قابل شناسایی در این سرویس
نکته : هر مقدار فیلد doc_type یک مقدار مشخص و معینی برای doc_type_id دارد.
- مقادیر زاویه چرخش مدرک (doc_rotaion):
| توضیح | Doc_type |
| بدون چرخش | 0 |
| 90 درجه ساعت گرد | 90 |
| 90 درجه پاد ساعت گرد | 270 |
| 180 درجه چرخش | 180 |
جدول 11 : انواع زوایای قابل تشخیص در این سرویس
نکات:
• در صورتی که گزینه ی auto انتخاب شود، ابتدا تشخیص نوع مدرک و زاویه چرخش انجام شده و در صورتی که از نوع کارت ملی جدید باشد، اطلاعات آن خوانده میشود. در خروجی نیز فیلد data_detection اضافه میشود و خروجی آن همانند سرویس تشخیص مدرک است.
• اگر مدرک تشخیص داده شده غیر از کارت ملی جدید (رو یا پشت) باشد، فقط فیلد data_detection در خروجی مشاهده میشود
• در صورتی که در درخواست، face_return برابر با true باشد فیلدهای زیر در پاسخ اضافه میشود.
• در صورتی که چهره ی فرد در کارت ملی شناسایی شود، مقدار detected_face_is برابر با true میشود و در غیر این صورت برابر false میشود.
• در صورت true بودن مقدار detected_face_is ،خروجی image_crop_face ،قطعه تصویر قرار گرفته در کارت ملی به فرمت base64 قرار داده میشود.
-
تشخیص امضاء
این سرویس اطلاعات تصویر امضاء و همچنین میزان حساسیت را دریافت و براساس امتیاز که برابر با میزان شباهات به امضا میباشد میتواند در پاسخ سرویس امضا بودن یا نبودن تصویر را نمایش دهد.
نکته مهم :
تصویر مدرک باید حاوی اطلاعات کد شده به صورت base64 ارسال گردد.
- شناسه سرویس : 1353850
- پارامتر ورودی سرویس
| نام پارامتر | نوع | اختیاری / اجباری | توضیحات |
| image_base64 | String | اجباری | اطلاعات base64 تصویر امضاء |
| threshold | Float | اختیاری | میزان حساسیت بین 0 تا 1 |
جدول 3 : پارامترهایی که باید ارسال گردد.
نکات:
• فیلد base64_image باید حاوی اطلاعات کد شدهی base64 مربوط به تصویر باشد.
• فیلد threshold برای تعیین میزان حساس بودن به امضا در نظر گرفته شده است و به صورت پیش فرض برابر با 0.5 می باشد.
- پارامتر های خروجی :
| نام پارامتر | نوع | توضیحات |
| hasError | bool | نشان دهنده ی این است که آیا سرویس با موفقیت از روی پلتفرم پاد فراخوانی شده است یا خیر. |
| messageId | int | پارامتر درون پلتفرمی ای که با توجه به این سرویس خاص موضوعیت ندارد. |
| referenceNumber | string | شناسه ی درخواست در پلتفرم پاد. |
| errorCode | int | کد ارور پلتفرمی. |
| Count | int | پارامتر درون پلتفرمی ای که با توجه به این سرویس خاص موضوعیت ندارد. |
| Ott | string | پارامتر درون پلتفرمی ای که با توجه به این سرویس خاص موضوعیت ندارد. |
| Result | object | نتیجه ی فراخوانی سرویس در این آبجکت نمایش داده می شود که در ادامه شرح داده خواهد شد. |
جدول 4 : پاسخی که از وب سرویس دریافت خواهید کرد.
نکته: طبق موارد مطرح شده، پاسخ مد نظر سرویس تشخیص امضاء در فیلد result موجود است.
به صورت دقیق تر، بدنه ی پاسخ را میتوان در فیلد result مشاهده کرد که دارای ساختار زیر است:
- پارامتر های پاسخ سرویس در Result :
| نام پارامتر | نوع | توضیحات |
| Uid | String | شناسه منحصر به فرد سرویس |
| Score | Float | میزان شباهت تصویر به امضاء |
| is_signature | Boot | مقایسه پارامتر threshold و score |
جدول 5 : پاسخ نتیجه اطلاعات تصویر ارسالی
نکات
• مقدار score برابر با میزان شباهت تصویر به امضا است و مقداری بین ۰ تا ۱ دارد.
• مقدار خروجی is_signature بر اساس مقدار score و در مقایسه با threshold مقدار true یا false به خود میگیرد.
