دسته «استعلام قبض» فینوتک پنج API دارد که مبلغ، مهلت و شناسههای قبض آب، برق، گاز، تلفن ثابت و تلفن همراه را برمیگردانند و هیچکدام پرداخت انجام نمیدهند. سه سرویس پاسخ را در همان فراخوانی میدهند و دو سرویس دیگر یک مسیر ناهمگام دومرحلهای میسازند. هر پنج سرویس با توکن Client Credential کار میکنند.
درباره دسته استعلام قبض
در مسیر همگام، درخواست و پاسخ در یک رفتوبرگشت تمام میشود. استعلام قبض گستردهترین پوشش نوع قبض را دارد و آب، برق، گاز، تلفن ثابت و تلفن همراه را میپذیرد؛ برای هر نوع، شناسه متناسب همان نوع را میفرستید — شناسه قبض، شماره اشتراک یا شماره تلفن — و مبلغ، شناسه قبض، شناسه پرداخت و مهلت پرداخت را میگیرید. استعلام قبوض با جزئیات همین کار را برای آب و برق و گاز انجام میدهد و در صورت وجود، جزئیات بیشتری از قبض را هم به پاسخ اضافه میکند. استعلام تاریخچه قبض بهجای دوره جاری، سابقه قبضهای برق یا گاز یک شناسه را برمیگرداند و برای دیدن روند به کار میآید.
مسیر ناهمگام برای حجم بالای درخواست یا زمانی است که نمیخواهید نخ برنامه منتظر پاسخ بماند: در ثبت درخواست استعلام قبض نوع و شناسه قبض را میفرستید و یک شناسه درخواست میگیرید، سپس در دریافت نتیجه استعلام قبض با همان شناسه، وضعیت را میخوانید تا از حالت در صف پردازش به موفق یا ناموفق برسد. مرز این دسته را همینجا روشن کنیم: کار این APIها استعلام است و پرداخت قبض در هیچکدام انجام نمیشود. شناسه قبض و شناسه پرداخت در پاسخ میآید تا پرداخت را با درگاه خودتان انجام دهید؛ تسویه، صدور رسید و ابطال قبض بیرون از این دسته است.
کاربردهای کسبوکاری استعلام قبض
- کیف پول و اپلیکیشن پرداخت — پیش از آنکه کاربر دکمه پرداخت را بزند، مبلغ و مهلت قبض با استعلام قبض به او نشان داده میشود.
- سوپراپ و خدمات مشترکان — قبض تلفن ثابت و همراه هم به شکل پایان دوره و هم به شکل بروز قابل استعلام است و در یک صفحه به کاربر ارائه میشود.
- مدیریت ساختمان و مستغلات — قبض آب و برق و گاز چند واحد در یک پنل جمع میشود و مسئول ساختمان لازم نیست جداگانه سراغ هر قبض برود.
- حسابداری و کنترل هزینه سازمان — روند مصرف شعبهها و انبارها با استعلام تاریخچه قبض دنبال و با بودجه مقایسه میشود.
- پردازش دستهای و گزارشهای زمانبندیشده — وقتی صدها استعلام در یک بازه اجرا میشود، مسیر ناهمگام پاسخگیری را از لحظه درخواست جدا میکند.
- پشتیبانی مشتری — کارشناس بدون خروج از پنل داخلی، وضعیت قبض مشترک را میبیند و به سؤال او پاسخ میدهد.
انتخاب سرویس مناسب در استعلام قبض
- «فقط مبلغ و مهلت قبض را میخواهم» — استعلام قبض سبکترین انتخاب است و بیشترین انواع قبض را پوشش میدهد.
- «قبض تلفن ثابت یا تلفن همراه هم باید پشتیبانی شود» — در این دسته فقط استعلام قبض این انواع را میپذیرد؛ برای قبوض بعضی اپراتورها ارسال یک پارامتر دوم الزامی است که در مستندات فنی مشخص شده است.
- «به جزئیات بیشتری از قبض نیاز دارم» — استعلام قبوض با جزئیات را انتخاب کنید؛ دامنه آن به آب و برق و گاز محدود است.
- «سابقه قبضهای قبلی را میخواهم، نه قبض جاری را» — استعلام تاریخچه قبض برای برق و گاز همین کار را میکند.
- «نمیخواهم درخواست من منتظر پاسخ بماند» — با ثبت درخواست استعلام قبض شروع کنید و شناسه درخواست را نگه دارید.
- «چطور بفهمم استعلام ناهمگام تمام شده است؟» — دریافت نتیجه استعلام قبض وضعیت جاری را میگوید و تا وقتی وضعیت در صف پردازش است، نتیجه هنوز آماده نیست.
شروع کار با استعلام قبض
پیش از نخستین فراخوانی، کلاینت خود را بسازید و اسکوپ سرویسی را که لازم دارید روی آن فعال کنید؛ مراحل ساخت کلاینت و گرفتن توکن در راهنمای شروع توضیح داده شده است. هر پنج سرویس این دسته با رویکرد Client Credential صدا زده میشوند و به تأیید پیامکی مشترک نیازی ندارند.
اگر بین مسیر همگام و ناهمگام مردد هستید، با همگام شروع کنید و تنها وقتی حجم یا زمان پاسخ برایتان مسئله شد سراغ مسیر دومرحلهای بروید. برای هر سرویس، صفحه کسبوکاری آن در فهرست پایین همین صفحه به مستندات فنی همان عملیات لینک میدهد و انواع مجاز قبض، شناسه متناظر هر نوع و نمونه پاسخ در آنجا آمده است.
سوالات متداول استعلام قبض
آیا این دسته پرداخت قبض هم انجام میدهد؟
خیر. سرویسهای این دسته فقط اطلاعات قبض را برمیگردانند. برای پرداخت باید از شناسه قبض و شناسه پرداخت در سامانه پرداخت خودتان استفاده کنید.
چه نوع توکنی برای این سرویسها لازم است؟
همه سرویسها با توکن Client Credential فراخوانی میشوند و رضایت پیامکی مشترک لازم نیست. جزئیات در راهنمای شروع آمده است.
تفاوت مسیر همگام و ناهمگام چیست؟
در مسیر همگام نتیجه در همان فراخوانی برمیگردد. در مسیر ناهمگام ابتدا درخواست ثبت میشود و یک شناسه میگیرید، سپس نتیجه را با آن شناسه در مرحله دوم میخوانید.
کدام انواع قبض پوشش داده میشوند؟
پوشش آب و برق و گاز سراسری است و قبض تلفن ثابت و تلفن همراه هم پشتیبانی میشود. فهرست دقیق انواع مجاز هر سرویس در مستندات فنی همان سرویس آمده است.
نتیجه استعلام را چقدر میتوانم ذخیره کنم؟
مبلغ و مهلت قبض با گذشت زمان تغییر میکند؛ پاسخ را بهعنوان تصویری از یک لحظه مشخص همراه زمان استعلام نگه دارید و پیش از نمایش دوباره به کاربر، استعلام تازه بگیرید.
مشخصات فنی هر سرویس را کجا ببینم؟
از فهرست پایین همین صفحه وارد صفحه هر سرویس شوید؛ آنجا لینک مستقیم به مستندات فنی با پارامترها و نمونه درخواست و پاسخ وجود دارد.
فهرست سرویسهای استعلام قبض
- استعلام تاریخچه قبض — با تعیین نوع قبض (Electricity یا Gas) و شناسه قبض/اشتراک (parameter)، تاریخچه قبض برگردانده میشود. (مستندات فنی)
- استعلام قبض — سرویس استعلام قبض با گرفتن نوع قبض و شناسه مربوط به آن، اطلاعات قبض را در اختیار کاربر قرار میدهد. (مستندات فنی)
- استعلام قبض ناهمگام (مرحله ۱) — ثبت درخواست — در این مرحله اطلاعات قبض وارد میشود و شناسه درخواست (requestId) به عنوان پاسخ برگردانده میشود. (مستندات فنی)
- استعلام قبض ناهمگام (مرحله ۲) — دریافت نتیجه — با ورود شناسه درخواست (requestId) از مرحله ثبت درخواست، نتیجه استعلام قبض برگردانده میشود. (مستندات فنی)
- استعلام قبوض با جزئیات — سرویس استعلام قبض با جزئیات؛ با گرفتن نوع قبض و شناسه مربوط به آن، اطلاعات قبض به همراه جزئیات را در اختیار کاربر قرار میدهد. (مستندات فنی)