API استعلام قبض برق
با شناسه قبض یک انشعاب برق، مبلغ، شناسه پرداخت، مهلت پرداخت، نوع اشتراک، نام مالک و نشانی واحد را برمی‌گرداند.
این سرویس چه می‌کند
فرض کنید شرکتی ده شعبه دارد و هر ماه یک نفر باید قبض برق همه‌شان را از روی عکس کاغذها تایپ کند و ببیند کدام سررسید نزدیک است. این سرویس همان کار را به یک فراخوان تبدیل می‌کند: شناسهٔ قبض هر انشعاب را میفرستید و بدهی جاری آن را میگیرید.
ورودی فقط یک فیلد است: شناسهٔ قبض، شش تا سیزده رقم. رقم‌های فارسی و فاصله پیش از اعتبارسنجی یکدست می‌شوند، پس نیازی به پاک‌سازی دستی نیست. در پاسخ مبلغ، شناسهٔ پرداخت، مهلت پرداخت، نوع اشتراک، نام مالک، نشانی واحد و دو تاریخ قرائت می‌آید.
کدام شناسه ثابت است و کدام عوض میشود
شناسهٔ قبض به انشعاب وصل است و دوره‌به‌دوره عوض نمی‌شود، پس می‌توانید آن را یک‌بار در پایگاه داده‌تان ذخیره کنید. شناسهٔ پرداخت برعکس به صورتحساب همان دوره تعلق دارد. اگر شناسهٔ پرداخت قدیمی را نگه دارید، پرداخت با آن به صورتحساب اشتباه می‌رود؛ هر بار از پاسخ تازه بخوانیدش.
وقتی مبلغ صفر برمی‌گردد
مبلغ صفر خطا نیست و همچنان یک پاسخ معتبر است. یعنی برای آن لحظه بدهیای ثبت نشده: یا پرداخت شده، یا قبض دورهٔ جدید هنوز صادر نشده. منطق یادآوری شما نباید صفر را «استعلام ناموفق» حساب کند.
مهلت پرداخت را چطور مقایسه کنیم
تاریخ‌ها شمسی و به‌شکل رشته‌اند. مقایسهٔ رشته‌ای در حوالی تغییر سال شمسی غلط درمی‌آید، پس پیش از هر شرط زمانی آن را به تاریخ میلادی ببرید.
آنچه این سرویس نمیکند
پرداخت انجام نمی‌دهد و بدهی را هم از حساب کسی برنمی‌دارد. مصرف به کیلووات‌ساعت را نمی‌دهد و عددی از کنتور در پاسخ نیست. با کد ملی یا نام مالک هم جست‌وجو نمیکند؛ بدون شناسهٔ قبض سفارشی ثبت نمی‌شود.
حریم خصوصی
نام مالک و نشانی در پاسخ هست. اگر برای مستأجر یا مشتری نمایش می‌دهید، فقط همان‌قدر که لازم است نشان بدهید و در لاگ‌هایتان کامل ذخیره نکنید.
کجا به کار می‌آید
- زنجیرهٔ فروشگاه‌ها و شعبه‌های بانکیواحد مالی هر هفته شناسهٔ ثابت همهٔ شعبه‌ها را می‌فرستد و فهرست سررسیدهای نزدیک را بدون تایپ دستی میگیرد.
- شرکت مدیریت املاک و اجارهپیش از تحویل کلید، بدهی برق واحد با شناسهٔ همان انشعاب بررسی میشود و مالک و مستأجر سر تسویه بحث نمی‌کنند.
- اپلیکیشن پرداخت و یادآور قبضکاربر شناسه را یک‌بار ثبت می‌کند و اپ هر دوره شناسهٔ پرداخت تازه را میگیرد و پیش از مهلت اعلان می‌فرستد.
ورودی و خروجی
ورودی
billIdstringشناسهٔ قبضشش تا سیزده رقم.خروجی
account_typestringخانگیaddressstringآدرس کامل واحد استعلام شدهamountnumberbill_idstringxxxxxxxxxxxxcurrent_datestring14xx/xx/xxfull_namestringنام مالکpayment_datestring14xx/xx/xxpayment_idstringxprevious_datestring14xx/xx/xxقیمت و شرط پرداخت
قیمت هر فراخوان API استعلام قبض برق ۵۰۰ تومان است.
| تعداد استعلام در ماه | قیمت هر استعلام |
|---|---|
| همهٔ فراخوان‌ها | ۵۰۰ تومان |
آخرین تغییر قیمت:
مبلغ پیش از تماس با سرویس مرجع از موجودی پنل قفل میشود و اگر پاسخی نیاید، آزاد میشود. ورودی نامعتبر، در دسترس نبودن سرویس مرجع و عبور از سقف نرخ هزینهای ندارند. «رکوردی یافت نشد» یک پاسخ معتبر است و هزینه دارد.
کمترین مبلغ شارژ پنل: ۵۰۰٬۰۰۰ تومان
پرسش‌های متداول
شناسهٔ قبض برق با هر دوره عوض میشود؟
خیر، شناسهٔ قبض به انشعاب وصل است و با میزان مصرف تغییر نمیکند. چیزی که هر دوره عوض میشود شناسهٔ پرداخت است و آن را از پاسخ همین استعلام میگیرید.
اگر قبض کاغذی نداشته باشم شناسه را از کجا بیاورم؟
شناسه روی قبضهای قبلی، پیامک شرکت توزیع و سامانهٔ برق من هست؛ در آنجا با شمارهٔ بدنهٔ کنتور هم میشود آن را گرفت. این سرویس خودش شناسه پیدا نمیکند و فقط با شناسهای که میفرستید استعلام میگیرد.
آیا میشود قبض برق را با کد ملی استعلام کرد؟
در این سرویس نه. ورودی فقط شناسهٔ قبض است و فیلدی برای کد ملی یا نام مالک ندارد. اگر کد ملی بفرستید، درخواست پیش از هر کسر هزینه با خطای ورودی رد میشود.
چرا بعد از پرداخت هنوز بدهی دیده میشود؟
ثبت پرداخت در سامانهٔ شرکت برق و واسطها همیشه همان لحظه نیست و گاهی چند ساعت طول میکشد. رسید و کد پیگیری را نگه دارید و بعد از مدتی دوباره استعلام بگیرید.
مبلغ صفر در پاسخ یعنی چه؟
یعنی در لحظهٔ استعلام بدهیای ثبت نشده است، چه پرداخت شده باشد چه قبض دورهٔ تازه هنوز نیامده باشد. صفر پاسخ معتبر است و هزینهٔ استعلام برای آن کسر میشود.
آیا مستأجر هم می‌تواند بدهی برق خانه را ببیند؟
بله، فقط شناسهٔ قبض لازم است و مالک بودن شرط نیست. به همین دلیل پاسخ نشانی و نام مالک را هم دارد و باید با احتیاط به کاربر نمایش داده شود.
اگر شناسه را اشتباه بفرستم هزینه کسر میشود؟
اگر شناسه کمتر از شش یا بیشتر از سیزده رقم باشد، درخواست با خطای ورودی رد میشود و هزینهای ندارد. اما شناسهٔ درست‌ساختاری که به هیچ انشعابی نرسد، یک استعلام انجام‌شده است و نتیجهٔ «رکوردی نیست» هزینه دارد.
از این سرویس برای پرداخت هم میشود استفاده کرد؟
خیر. فقط شناسهٔ قبض و شناسهٔ پرداخت را میدهد و پرداخت از درگاه خودتان انجام میشود.
چند فراخوان در دقیقه مجاز است؟
سقف پیشفرض برای هر سرویس در مستندات API نوشته شده است. عبور از آن پاسخ ۴۲۹ با هدر Retry-After میگیرد و هزینهای ندارد.