تاریخ قرائت و مهلت پرداخت در قبض برق را چطور بخوانیم؟

پاسخ استعلام قبض برق سه تاریخ دارد و هیچ‌کدامشان «امروز» نیست: هر سه را شرکت توزیع ثبت کرده و شما فقط می‌خوانیدشان. اگر آن‌ها را مثل تاریخ‌های خودتان در کد بگذارید، گزارش‌تان بی‌صدا غلط درمی‌آید.

این راهنما فقط دربارهٔ همین سه تاریخ است: هر کدام چه می‌گوید، چطور از رویشان بفهمید قبضی که دیده‌اید تازه است یا کهنه، و کجا مقایسهٔ تاریخ در کد شکست می‌خورد. اگر هنوز نمی‌دانید ورودی کدام عدد است، اول استعلام قبض برق با شناسه قبض را ببینید و برگردید.

سه تاریخ در پاسخ

در نمونهٔ پاسخ این سرویس سه فیلد تاریخ هست:

• previous_date: تاریخ دورهٔ قبل
• current_date: تاریخ دورهٔ جاری
• payment_date: تاریخ پرداخت، که در صفحهٔ سرویس به‌عنوان مهلت پرداخت معرفی شده

هر سه رشتهٔ شمسی به شکل سال/ماه/روز هستند. در این پاسخ هیچ تاریخ میلادی و هیچ زمان ساعتی نیست. تنها زمان ساعتی در کل پاسخ، فیلد fetchedAt در بخش source است که مال خود ما است و به UTC و با قالب ISO می‌آید. یعنی در یک پاسخ دو دنیای متفاوت تاریخ کنار هم نشسته‌اند و اولین باگ معمول همین‌جا است.

یک نمونهٔ فرضی و کوتاه‌شده از بخش مهم data:

json { "amount": 0, "previous_date": "1404/03/30", "current_date": "1404/05/30", "payment_date": "1404/06/15" }

اعداد این نمونه ساختگی‌اند و فقط شکل را نشان می‌دهند.

«قرائت» چه ربطی به تاریخ قبض دارد

دو تاریخ previous_date و current_date دو سر یک بازه‌اند: بازه‌ای که شرکت توزیع بین دو ثبت مصرف گذاشته است. از فاصلهٔ این دو می‌شود طول دوره را درآورد، و طول دوره ثابت نیست. فرض کنید در کدتان نوشته‌اید «هر قبض شصت روز است». اولین ملکی که دوره‌اش کوتاه یا بلندتر ثبت شده باشد، نمودار مصرف روزانهٔ شما را کج می‌کند.

راه درست ساده است: طول بازه را هر بار از همان دو تاریخ حساب کنید و عدد ثابت در کد نگذارید.

عدد کنتور در پاسخ نیست. دو تاریخ می‌گویند بازه کجا شروع و کجا تمام شده، ولی نمی‌گویند در این بازه چند کیلووات‌ساعت خرج شده. اگر نمودار مصرف می‌خواهید، این سرویس آن را نمی‌دهد.

قبض کهنه را چطور تشخیص بدهیم

بعد از پرداخت یا در ابتدای یک دورهٔ تازه، ممکن است چیزی که می‌بینید هنوز قبض دورهٔ قبل باشد. نشانه‌اش current_date است. اگر تاریخ جاری ثبت‌شده از امروز خیلی عقب است، یعنی هنوز دورهٔ تازه‌ای در رکورد نیامده و مبلغی که دارید مال همان قبض قدیمی است.

«خیلی عقب» را خودتان تعریف کنید و به قاعدهٔ منطقی تکیه کنید: مثلاً اگر از current_date بیش از یک دورهٔ کامل گذشته (که طولش را از دو تاریخ بالا دارید)، پیام «این قبض ممکن است قدیمی باشد» بگذارید. به نظر من نمایش یک هشدار نرم بهتر از قضاوت قطعی است، چون شما نمی‌دانید شرکت توزیع آن ملک را کی قرائت می‌کند.

اینکه چرا بعد از پرداخت هنوز بدهی دیده می‌شود، ماجرای جداگانه‌ای است که در قبض را پرداخت کردم ولی هنوز بدهی نشان می‌دهد آمده. اینجا فقط یادتان باشد که تاریخ قرائت یکی از سرنخ‌های آن تشخیص است.

جای شکستن مقایسهٔ تاریخ

چهار گیر رایج:

1. رقم فارسی و لاتین. رشتهٔ 1404/06/15 با ۱۴۰۴/۰۶/۱۵ مساوی نیست، حتی اگر برای چشم یکی باشند. پیش از هر مقایسه، یک شکل را برگزینید و همه‌چیز را به آن ببرید.

1. صفرِ ابتدای ماه و روز. مقایسهٔ رشته‌ای فقط وقتی درست است که هر دو طرف دقیقاً هم‌عرض باشند. 1404/6/5 و 1404/06/15 را رشته‌ای مقایسه نکنید. بهتر است هر رشته را به سه عدد بشکنید و تاپل مقایسه کنید.

1. مخلوط‌کردن با fetchedAt. fetchedAt میلادی و ISO است و payment_date شمسی. نمی‌شود این دو را بدون تبدیل کم کرد. اگر می‌خواهید بپرسید «چند روز تا مهلت مانده؟»، payment_date را با کتابخانهٔ تقویم به میلادی ببرید و با تاریخ امروز مقایسه کنید.

1. سال کبیسه و اسفند. تبدیل دستی تاریخ شمسی با ضرب و تقسیم، دقیقاً همان جاهایی خطا می‌دهد که سال کبیسه است. از کتابخانهٔ تقویم استفاده کنید و تبدیل را خودتان ننویسید.

مهلت پرداخت یعنی چه، و چه نمی‌گوید

payment_date را به‌عنوان مهلت پرداخت می‌خوانیم. اما همین‌جا مرز ادعا را نگه دارید. پاسخ نمی‌گوید بعد از این تاریخ چه می‌شود: نه جریمه‌ای را نشان می‌دهد، نه تاریخ قطع را، نه اینکه مبلغ بعد از مهلت چقدر می‌شود. هر منطق «چند روز تا قطع» که روی این فیلد بسازید، حدس شماست و نه داده.

پیشنهاد من برای یادآور این است: به کاربر بگویید «مهلت پرداخت ثبت‌شده در قبض: تاریخ فلان» و از قطع و جریمه حرف نزنید.

یک جدول برای نمایش

آنچه این پاسخ نمی‌کند

• میزان مصرف برنمی‌گرداند.
• تاریخ قطع یا جریمهٔ دیرکرد نمی‌دهد.
• پیش‌بینی نمی‌کند قبض بعدی کی صادر می‌شود.
• تاریخ را میلادی نمی‌کند؛ تبدیل با شماست.

اگر فهمیدن اینها برایتان کافی است، راهنمای فنی API شکل کامل پاسخ و خطاها را نشان می‌دهد.

نمونهٔ منطق نمایش

سه حالت برای نمایش به کاربر کافی است و بیشتر از این پیچیدگی اضافی می‌آورد:

• عادی: current_date در دورهٔ اخیر است و مبلغ غیرصفر. نمایش: مبلغ، مهلت پرداخت ثبت‌شده و دکمهٔ پرداخت.
• تسویه: مبلغ صفر. نمایش: «در رکورد شرکت توزیع بدهی ثبت نشده» به‌همراه تاریخ آخرین قرائت.
• مشکوک به کهنگی: current_date از یک دورهٔ کامل عقب‌تر است. نمایش: همان مبلغ، با یک جملهٔ هشدار که ممکن است دورهٔ تازه‌ای هنوز ثبت نشده باشد.

در هیچ‌کدام نیازی نیست از payment_date برای نتیجه‌گیری دربارهٔ وضعیت اشتراک استفاده کنید. همین‌که تاریخ را نشان بدهید و تفسیر را به شرکت بسپارید، هم صادقانه‌تر است هم کم‌ریسک‌تر. اگر می‌خواهید جزئیات هر فیلد پاسخ را ببینید، صفحهٔ سرویس قبض برق فهرست را دارد.

نکتهٔ آخر

سه تاریخ را سه چیز متفاوت بدانید: دو سر بازه و یک مهلت. طول بازه را از خود تاریخ‌ها بگیرید، برای مقایسه رشته را به عدد بشکنید، و هیچ‌وقت از این‌ها قطع یا جریمه نتیجه نگیرید.