سرویس «استعلام قبض» در دسته استعلام قبض فینوتک با گرفتن نوع قبض و شناسه مربوط به آن، مبلغ قبض، شناسه قبض، شناسه پرداخت و مهلت پرداخت را برمیگرداند. با این سرویس میتوانید بدهی آب، برق، گاز، تلفن ثابت و تلفن همراه را همان لحظه داخل محصول خود نشان دهید و تصمیم بگیرید چه مبلغی و تا چه تاریخی باید تسویه شود.
استعلام قبض چه مشکلی را حل میکند؟
کاربر ایرانی برای دانستن مبلغ قبض خود یا منتظر رسید کاغذی میماند، یا باید سراغ سامانه جداگانه هر سازمان خدماتی برود و شناسه قبض را دستی وارد کند. در سمت کسبوکار هم وضع بهتر نیست: تیم پشتیبانی برای پاسخ به «بدهی من چقدر است؟» به دادهای دسترسی ندارد، مبلغها با تاخیر و از منابع پراکنده جمع میشود و کاربر گاهی مبلغی را دستی وارد میکند که با بدهی واقعی او نمیخواند؛ نتیجه، مغایرت و پیگیری پس از رخداد است.
این سرویس همان بررسی را به یک فراخوانی API تبدیل میکند: نوع قبض و شناسه مربوط به آن را میفرستید و مبلغ، شناسه قبض، شناسه پرداخت و مهلت پرداخت را بهصورت داده ساختیافته میگیرید. خروجی مستقیم به تصمیمهای محصول شما وصل میشود: نمایش مبلغ دقیق به کاربر پیش از هر اقدام، فعال یا غیرفعال کردن دکمه تسویه بر پایه وجود بدهی، یادآوری نزدیکشدن مهلت پرداخت و ارجاع کاربر به مسیر پرداختی که خودتان در اختیار دارید. توجه کنید که نقش این سرویس فقط استعلام است و قبض را پرداخت نمیکند.
کاربردهای استعلام قبض
- کیف پول و اپلیکیشنهای پرداخت — کاربر شناسه قبض یا شماره اشتراک را یکبار ذخیره میکند و در هر ورود، مبلغ روز بدهی او در صفحه اصلی نمایش داده میشود.
- سوپراپهای خدمات شهری و ارتباطی — مبلغ آب، برق، گاز، تلفن ثابت و تلفن همراه در یک صفحه کنار هم میآید و کاربر برای هر سازمان سراغ سامانه جداگانه نمیرود.
- مدیریت هزینه املاک و ساختمان — پلتفرمهای مدیریت ساختمان و اجاره، بدهی قبوض هر واحد را پیش از تسویه ماهانه یا تحویل ملک استعلام میکنند.
- واحد مالی و پشتیبانی سازمانها — تیم مالی بدهی قبوض شعب، انبارها و دفاتر را از یک نقطه میبیند و برای هر مکان پرونده هزینه میبندد.
- باشگاه مشتریان و خدمات اشتراکی — پیش از ارائه تخفیف یا اعتبار مربوط به قبض، وجود قبض و مبلغ آن راستیآزمایی میشود.
- پنل خدمات مشترکین تلفن همراه و ثابت — بدهی پایان دوره یا بدهی تا همین لحظه، بسته به نیاز صفحه، خوانده و به کاربر نشان داده میشود.
مزایای استعلام قبض
- پوشش گسترده انواع قبض در یک سرویس — آب، برق (بههمراه مسیر پشتیبان)، گاز بر اساس شماره اشتراک یا شماره قبض، تلفن ثابت و تلفن همراه با یک الگوی فراخوانی یکسان.
- حذف ورود دستی مبلغ — مبلغ از خروجی سرویس خوانده میشود، نه از تایپ کاربر؛ بنابراین جای خطای انسانی در رقم بدهی بسته میشود.
- مهلت پرداخت در همان پاسخ — میتوانید یادآوری و اولویتبندی صف تسویه را بر پایه تاریخ مهلت بچینید.
- انتخاب بین بدهی بروز و پایان دوره — برای قبوض تلفن، نوع قبض را بر اساس اینکه صفحه شما بدهی دورهای میخواهد یا بدهی لحظهای، انتخاب میکنید.
- شروع بدون دخالت کاربر — یک درخواست با توکن Client Credential کافی است و رضایت پیامکی لازم نیست.
چه چیزی از استعلام قبض دریافت میکنید؟
جزئیات ورودی، خروجی و نمونه پاسخ در مستندات فنی آمده است.
جریان کار استعلام قبض
- ۱. ساخت کلاینت و گرفتن توکن — با اسکوپ
billing:cc-inquiry:getتوکن Client Credential بگیرید. - ۲. تعیین نوع قبض — بر اساس خدمتی که کاربر انتخاب کرده، نوع قبض را مشخص کنید تا معنای مقدار ورودی روشن باشد.
- ۳. ارسال شناسه قبض یا اشتراک — مقدار متناظر همان نوع قبض را همراه یک
trackIdیکتا بفرستید. - ۴. خواندن پاسخ — مبلغ قبض، شناسه قبض، شناسه پرداخت و مهلت پرداخت را از پاسخ بردارید و به کاربر نشان دهید.
- ۵. نگهداری نتیجه — مبلغ استعلامشده و
trackIdرا برای مغایرتگیری و پیگیری بعدی ذخیره کنید.
نحوه شروع استعلام قبض
این سرویس با رویکرد Client Credential (بدون رضایت پیامکی) فراخوانی میشود. اسکوپ مورد نیاز: billing:cc-inquiry:get. ابتدا کلاینت بسازید و توکن بگیرید: راهنمای شروع. سپس از مستندات فنی برای پیادهسازی استفاده کنید.
محدودیتها و نکات استعلام قبض
- این سرویس فقط استعلام میکند و قبض را پرداخت نمیکند؛ پرداخت باید در مسیرهای پرداخت خودتان انجام شود.
- معنای مقدار ورودی به نوع قبض بستگی دارد: برای آب و برق شناسه قبض، برای گاز شماره اشتراک یا شماره قبض، برای تلفن ثابت شماره تلفن به همراه کد و برای تلفن همراه شماره موبایل.
- برای قبوض اپراتورهای ایرانسل و رایتل، ارسال پارامتر دوم (
secondParameter) اجباری است؛ اگر محصول شما این اپراتورها را پوشش میدهد، این ورودی را در فرم پیشبینی کنید. - پوشش آب، برق و گاز سراسری است؛ برای بقیه انواع قبض، رفتار سرویس را در محیط آزمایشی خود بسنجید.
- پاسخ، تصویری از همان لحظه است؛ اگر فاصله بین نمایش مبلغ و تسویه طولانی شد، استعلام را تازه کنید.
- برای هر فراخوانی
trackIdیکتا بفرستید تا هر استعلام در گزارشها و پیگیریهای بعدی قابل ردیابی باشد.
سوالات متداول استعلام قبض
استعلام قبض چیست؟
سرویسی است که با دریافت نوع قبض و شناسه مربوط به آن، اطلاعات قبض شامل مبلغ، شناسه قبض، شناسه پرداخت و مهلت پرداخت را بهصورت داده ساختیافته برمیگرداند.
آیا این سرویس قبض را پرداخت میکند؟
خیر. نقش این سرویس فقط استعلام اطلاعات قبض است؛ عمل پرداخت در این سرویس انجام نمیشود.
چه نوع قبضهایی پشتیبانی میشود؟
آب، برق (با مسیر پشتیبان)، گاز بر اساس شماره اشتراک یا شماره قبض، تلفن ثابت و تلفن همراه، هرکدام در دو حالت پایان دوره و بروز برای قبوض تلفن. فهرست دقیق مقادیر در مستندات فنی آمده است.
تفاوت این سرویس با استعلام قبوض با جزئیات چیست؟
این سرویس دامنه گستردهتری از انواع قبض را پوشش میدهد؛ اگر به جزئیات قبض آب، برق یا گاز نیاز دارید، از استعلام قبوض با جزئیات استفاده کنید.
مستندات فنی این سرویس کجاست؟
صفحه مشخصات API شامل endpoint، پارامترها و نمونه پاسخ است.
چه نوع احراز هویتی لازم است؟
Grant type: client_credentials. جزئیات در راهنمای توکن.
آیا رضایت پیامکی کاربر لازم است؟
خیر. این سرویس با Client Credential و بدون رضایت پیامکی قابل فراخوانی است.
مستندات فنی استعلام قبض
مشاهده مستندات فنی «استعلام قبض» — endpoint، پارامترها، نمونه درخواست و پاسخ.