دریافت اطلاعات چک از روی تصویر
خدمتدهنده
بازارچه پادیوم
مقدمه
سرویس Check Detection یا سرویس تشخیص چک ، یک سرویس کاملا Asynchronous می باشد ، که با دریافت تصویر یک برگه چک ، ابتدا شناسیی میکند که تصویر واقعا مربوط به چک می باشد یا خیر ، سپس موارد زیر را به عنوان خروجی ارسال می نماید :
- nationalId: کد ملی دارنده چک
- shebaCode: کد شبای حساب دارنده چک
- branchCode: کد شعبه حساب دارنده چک
- checkSerialNumber: سریال چک
- sayadID: شناسه صیاد چک
از آنجایی که ماهیت این سرویس Asynch بوده ، در نتیجه با فراخوانی سرویس دریافت کننده درخواستهای کاربران ، این درخواستها در یک صف پردازش قرار داده میشود ، و به کاربران اطلاع دریافت درخواست داده خواهد شد .
سپس بعد از پردازش هر درخواست ، نتیجه پردازش به Callback URL یی که در زمان ارسال درخواست ، وارد شده است ، ارسال میشود .
همچنین نتیجه پردازش در دیتابیس مربوط به سرویس ذخیره میگردد ، و در نتیجه با استفاده از سرویس دریافت وضعیت درخواست ، میتوان از لحظه ی دریافت درخواست ، وضعیت پیشرفت پردازش درخواست را پایش نمود .
تشریح نحوه فراخوانی این سرویس و مشخصات پاسخ آن در ادامه آورده شده است
توجه داشته باشید که سرویس تشخیص چک با دو روش قابل فراخوانی است که برای هر کدام یک سرویس وجود دارد:
- روش اول: تصویر چک ابتدا باید در پاد اسپیس اپلود شودو سپس URL تصویر در سرویس ارسال شود
- روش دوم: محتوای تصویر چک به صورت BASE64 در سرویس ارسال میشود .
فعالسازی سرویس
ارسال درخواست در سایت پادیوم www.podium.ir:
ابتدا وارد سایت پادیوم شده، سپس در بازارچهی API، سرویسهای مورد نظر خود را انتخاب و درخواست استفاده از آن مجموعه سرویس را ارسال کنید.
درخواست شما توسط کارشناسان پادیوم، بررسی شده و بعد از تایید آن میتوانید از طربق پنل کسب و کار خود اقدام به دریافت کلید اتصال مربوط به آن سرویس نمایید.
منو: پنل کسب و کار – منوی میزکار سرویس گیرنده – درخواستهای ارسالی – در بخش مربوط به سرویس مورد نظر با کلیک بر روی "جزئیات درخواست"
درلیست باز شده با کلیک بر روی تصویر کلید سمت چپ هر سطر جدول میتوانید ApiKey مربوط به آن سرویس را دریافت و ذخیره کنید.
لینک پنل کسب و کار https://panel.pod.ir/Businesses/Requestwebservices
نکته : این کلید در تمام درخواستهای ارسالی از آن سرویس ، ثابت است تا زمانی که کلید جدیدی برای آن سرویس دریافت نشود و به محض دریافت مقدار جدید برای سرویس مورد نظر, کلید قبلی منقضی خواهد شد.
-این کلید در فیلد scApiKey در بخش body درخواست HTTP ، استفاده می شود.
دریافت کلیدهای سرویس یک (دسته/مجموعه) سرویس در قالب یک فایل:
بعداز فشردن دکمه ی تایید سرویس در پنجره باز شده بالا ، برای تمامی سرویسهای موجود در پنل میتوانید از گزینه "دریافت فایل خروجی"، لیست کاملی از سرویسها و کلیدهای scApiKey متناظر با هر یک را دریافت کنید.
نحوه صحیح ارسال تصاویر
نمونه تصاویر ارسالی:
به منظور استفاده صحیح از سرویس در راستای دستیابی به دقت موردنظر ، می بایست تصاویر ارسالی از استانداردهای زیر برخوردا باشد:
- تصویر فقط شامل روی اصلی یک برگ چک باشد
- کیفیت تصویر مناسب بوده و QR و اطلاعات دیگر چک به خوبی خوانا باشد .
- زاویه تصویر چک میتواند یکی از زوایای 0 و 90 و 180 و 270 درجه باشد .
نمونه هایی از تصاویر مناسب از روی چک در زیر آورده شده است:
دریافت اطلاعات چک (Cheque OCR) با استفاده از نشانی اینترنتی
-
شناسه سرویس: 3881056
- پارامتر ورودی سرویس:
نام پارامتر | نوع | اختیاری / اجباری | توضیحات |
imageUrl | string | اجباری | آدرس URL تصویر گذرنامه بارگذاري شده در پاداسپیس |
پارامتر های خروجی:
نام پارامتر | نوع | توضیحات |
hasError | bool | نشان دهنده ی این است که آیا سرویس با موفقیت از روی پلتفرم پاد فراخوانی شده است یا خیر. |
messageId | int | پارامتر درون پلتفرمی ای که با توجه به این سرویس خاص موضوعیت ندارد. |
referenceNumber | string | شناسه ی درخواست در پلتفرم پاد. |
errorCode | int | کد ارور پلتفرمی. |
Count | int | پارامتر درون پلتفرمی ای که با توجه به این سرویس خاص موضوعیت ندارد. |
Ott | string | پارامتر درون پلتفرمی ای که با توجه به این سرویس خاص موضوعیت ندارد. |
Result | object | نتیجه ی فراخوانی سرویس در این آبجکت نمایش داده می شود که در ادامه شرح داده خواهد شد. |
نکته: طبق موارد مطرح شده، پاسخ مد نظر سرویس دریافت اطلاعات آدرس در فیلد result موجود است.
به صورت دقیق تر، بدنه ی پاسخ را میتوان در فیلد result مشاهده کرد که دارای ساختار زیر است:
- نمونه پاسخ سرویس در Result :
- نمونه پاسخ موفق سرویس در Result.result:
- نمونه پاسخ نا موفق سرویس در . result Result:
نکته مهم: پس از فراخونی سرویس لازم است scTrackerId در پاسخ سرویس جهت دریافت پاسخ پردازش نگهداری گردد.
- پارامتر های موجود در Result:
نام پارامتر | نوع | توضیحات |
requestID | String | شناسه درخواست پردازش |
hasError | boolean | وضعیت فراخوانی سرویس |
Message | String | پیام سرویس |
statusCode | Integer | کد فراخوانی سرویس در صورت موفقیت آمیز بودن 200 خواهد بود |
نکته: در صورتی که درخواست به هر دلیلی قابل دریافت نباشد فیلد hasError برابر با True خواهد شد.
همچنین در پارامتر message دلیل بروز خطا توضـــیح داده میشـــود.
در جدول کدهای خطای سرویس مقادیر مربوط به statusCode به همراه مثالهایی از خطاهاي احتمالی بیان شده است.
سرویس دریافت اطلاعات چک (Cheque OCR) با استفاده از کد Base64 تصویر
نکته: این سرویس فقط براي تصاویر با حجم کمتر از KB 500 قابل استفاده است. براي تصاویر با حجم بالاتر میتوان از سرویس Passport OCR با استفاده از ادرس اینترنتی تصویر استفاده نمود.
- شناسه سرویس: 3881171
- پارامتر ورودی سرویس:
نام پارامتر | نوع | اختیاری / اجباری | توضیحات |
imageContent | string | اجباری | کد تصویر چک به صورت Base64 |
پارامتر های خروجی:
نام پارامتر | نوع | توضیحات |
hasError | bool | نشان دهنده ی این است که آیا سرویس با موفقیت از روی پلتفرم پاد فراخوانی شده است یا خیر. |
messageId | int | پارامتر درون پلتفرمی ای که با توجه به این سرویس خاص موضوعیت ندارد. |
referenceNumber | string | شناسه ی درخواست در پلتفرم پاد. |
errorCode | int | کد ارور پلتفرمی. |
Count | int | پارامتر درون پلتفرمی ای که با توجه به این سرویس خاص موضوعیت ندارد. |
Ott | string | پارامتر درون پلتفرمی ای که با توجه به این سرویس خاص موضوعیت ندارد. |
Result | object | نتیجه ی فراخوانی سرویس در این آبجکت نمایش داده می شود که در ادامه شرح داده خواهد شد. |
نکته: طبق موارد مطرح شده، پاسخ مد نظر سرویس دریافت اطلاعات آدرس در فیلد result موجود است.
به صورت دقیق تر، بدنه ی پاسخ را میتوان در فیلد result مشاهده کرد که دارای ساختار زیر است:
- نمونه پاسخ موفق سرویس در Result:
نمونه پاسخ نا موفق سرویس در Result:
پارامتر های موجود در Result:
نام پارامتر | نوع | توضیحات |
requestID | String | شناسه درخواست پردازش |
hasError | boolean | وضعیت فراخوانی سرویس |
Message | String | پیام سرویس |
statusCode | Integer | کد فراخوانی سرویس در صورت موفقیت آمیز بودن 200 خواهد بود |
نکته: در صورتی که درخواست به هر دلیلی قابل دریافت نباشد فیلد hasError برابر با True خواهد شد.
همچنین در پارامترmessage دلیل بروز خطا توضـــیح داده میشـــود.
در جدول کدهای خطای سرویس مقادیر مربوط به statusCode به همراه مثالهایی از خطاهاي احتمالی بیان شده است.
استعلام وضعیت درخواست
همانطور که در بخش مقدمه اشاره شد، به محض دریافت صحیح یک درخواست، و ضعیت پردازش آن در پایگاه داده مرتبط ذخیره میگردد، ســپس با پردازش و تغییر وضــعیت درخواســت، رکورد مربوط به آن در پایگاه داده بروزرســانی میگردد. در نهایت این سرویس وضعیت درخواستهاي سرویس دریافت اطلاعات چک که در پایگاه داده مربوطه ذخیره شده اند را اعلام میکند.
- شناسه سرویس: 3882771
- پارامتر ورودی سرویس:
نام پارامتر | نوع | اختیاری / اجباری | توضیحات |
trackerId | string | اجباری | شناسه scTrackerId دریافت شده در پاسخ سرویس اصلی |
پارامتر های خروجی:
پاســخ درخواســت اســتعلام یک JSON اســت که در ســطح اول حاوي پارامترهاي hasError ،statusCode ، statusText ،و version می باشد. همچنین در صورت ارسال صحیح درخواست، پارامتر result که حاوي وضعیت و یا نتایج پردازش هست نیز به همراه پارامترهاي فوق دریافت میشوند.
نام پارامتر | نوع | توضیحات |
hasError | bool | نشان دهنده ی این است که آیا سرویس با موفقیت از روی پلتفرم پاد فراخوانی شده است یا خیر. |
messageId | int | پارامتر درون پلتفرمی ای که با توجه به این سرویس خاص موضوعیت ندارد. |
referenceNumber | string | شناسه ی درخواست در پلتفرم پاد. |
errorCode | int | کد ارور پلتفرمی. |
Count | int | پارامتر درون پلتفرمی ای که با توجه به این سرویس خاص موضوعیت ندارد. |
Ott | string | پارامتر درون پلتفرمی ای که با توجه به این سرویس خاص موضوعیت ندارد. |
Result | object | نتیجه ی فراخوانی سرویس در این آبجکت نمایش داده می شود که در ادامه شرح داده خواهد شد. |
نکته: طبق موارد مطرح شده، پاسخ مد نظر سرویس دریافت اطلاعات آدرس در فیلد result موجود است.
به صورت دقیق تر، بدنه ی پاسخ را میتوان در فیلد result مشاهده کرد که دارای ساختار زیر است:
- نمونه پاسخ موفق سرویس در Result:
در صورت عدم وجود خطا در سرویس استعلام بنا به و ضعیت پردازش درخواست ارسالی،پارامتر result نیز ارسال خواهد شد.
- نمونه پاسخ ناموفق سرویس در Result:
- پارامتر های موجود در Result:
نام پارامتر | نوع | توضیحات | ||||||||||||||||||||||||||||||
hasError |
| در صورت وقوع خطا در فراخوانی سرویس true خواهد بود | ||||||||||||||||||||||||||||||
result |
|
| ||||||||||||||||||||||||||||||
statusCode |
|
| ||||||||||||||||||||||||||||||
statusText |
|
| ||||||||||||||||||||||||||||||
version |
|
|
نکته: در صورتی که پردازش به اتمام رسیده باشد، زمان اتمام پردازش را نمایش میدهد. در غیراین صورت این پارامتر null خواهد بود.
- پارامتر های موجود در requestStatusCode:
requestStatusCode | requestStatusText |
Reject request | درخواست رد شده است |
AI Await | درخواست به درستی دریافت شده و در صف پردازش قرار گرفته است |
Done | پردازش درخواست و ارسال نتیجه آن با موفقیت انجام شده است |
Sendresponse Failed ! | پردازش درخواست با موفقیت انجام شده ولی ارسال نتیجه به ادرس بازگشت کالبک با خطا مواجه شده است . |
دریافت پاسخ سرویس
جهت دریافت پاسخ سرویس کال بک، از طریق کد زیر شناسه ی ترکر مورد نظر و ارسالی خود را در سرویس فراخوانی سرویس ارسال می نماید.
- شناسه سرویس: 6232569
- پارامتر ورودی سرویس:
نام پارامتر | نوع | اختیاری / اجباری | توضیحات |
trackerId | string | اجباری | شناسه scTrackerId دریافت شده در پاسخ سرویس اصلی |
- پارامتر های خروجی:
نام پارامتر | نوع | توضیحات |
hasError | bool | نشان دهنده ی این است که آیا سرویس با موفقیت از روی پلتفرم پاد فراخوانی شده است یا خیر. |
messageId | int | پارامتر درون پلتفرمی ای که با توجه به این سرویس خاص موضوعیت ندارد. |
referenceNumber | string | شناسه ی درخواست در پلتفرم پاد. |
errorCode | int | کد ارور پلتفرمی. |
Count | int | پارامتر درون پلتفرمی ای که با توجه به این سرویس خاص موضوعیت ندارد. |
Ott | string | پارامتر درون پلتفرمی ای که با توجه به این سرویس خاص موضوعیت ندارد. |
Result | object | نتیجه ی فراخوانی سرویس در این آبجکت نمایش داده می شود که در ادامه شرح داده خواهد شد. |
نکته: طبق موارد مطرح شده، پاسخ مد نظر سرویس دریافت اطلاعات آدرس در فیلد result موجود است.
به صورت دقیق تر، بدنهی پاسخ را میتوان در فیلد result مشاهده کرد که دارای ساختار زیر است:
- نمونه پاسخ موفق سرویس در Result :
- نمونه پاسخ ناموفق سرویس در Result :
پس از دریافت درخواست و پردازش آن ، نتیجه پردازش به CallbackUrl ایی که به عنوان ورودی از فراخواننده سرویس دریافت شده بود ارسال میگردد .
در خروجی فوق در صورتی که تمامی مراحل پردازش به درستی طی شده باشد ، پارامتر hasError برابر false و statusCode برابر با 200 خواهد بود . در این حالت مقادیر استخراج شده از چک به قرار زیر به عنوان خروجی ارسال خواهد شد :
پارامتر message پیامی در مورد وضعیت پردازشی درخواست است ، و بقیه پارامترها همان پارامترهای ارسالی به سرویس می باشند ، که برای پیگیری درخواستها و ... توسط فراخوننده ارسال شده بودند. البته اگر سرویس checkDetectionByContent فراخوانی شده باشد ، imageContentUse:true خواهد بود و در غیر این صورت false می باشد .
در صورت بروز هر گونه مشکل در فرایند پردازش تصویر ، براساس نوع خطای رخداده ، کدهای خانواده 400 و 500 در statusCode اورده خواهد شد و پیغام مناسب برای تشریح خطای مورد نظر در پارامتر message آورده میشود .
- پارامتر های موجود در Result:
نام پارامتر | نوع | توضیحات |
isCheck | Integer | این فیلد مشخص میکند که تصویر متعلق به روی یک چک بانکی هست یا خیر . |
qrExist | String | این پارامتر مشخص میکند که QR Code بر روی چک وجود دارد یا خیر . |
checkDetectionConfidence | String | این پارامتر میزان اعتقاد به تشخیص اینکه تصویر متعلق به چک است را مشخص میکند . |
nationalID | Integer | کد ملی دارنده چک |
shebaCode | Integer | کد شبای حساب دارنده چک |
checkSerialNumber | Integer | سریال چک |
sayadID | Integer | شناسه صیاد چک |
کدهای خطای سرویس
کد خطا | عنوان | توضیحات |
200 | request found | درخواســـت اســـتعلام با موفق یت در یا فت شـــده و شناسه درخواست مورد نظر نیز یافت شده است. |
404 | request not found | درخواســت مورد نظر یافت نشد |
400 | missing arguments | عدم ارسال پارامترهاي مورد نیاز در درخوا ست به همراه نام آن. |
500 |
| خطا در سرور |