صفحهٔ پرداخت قبض تلفن ثابت در اپ شما: دو صورتحساب، دو پرداخت

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

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

وضعیت هر صورتحساب جداست

پاسخ دو بخش دارد، mid_term و final_term، و هر کدام مبلغ، شناسه قبض و شناسه پرداخت خودش را دارد. در نمونهٔ مشخصات، هر بخش فقط همین سه چیز را دارد، بدون نام مشترک و بدون نشانی و بدون تاریخ. پس برای هر بخش شما سه داده دارید و باید خودتان وضعیت را اضافه کنید:

• نیاز به پرداخت: مبلغ بزرگ‌تر از صفر
• بدون بدهی: مبلغ صفر
• در حال پرداخت: کاربر به درگاه رفته
• پرداخت‌شده در سیستم شما: درگاه موفقیت برگردانده

وضعیت را بر پایهٔ شناسه پرداخت هر بخش نگه دارید، نه بر پایهٔ شماره تلفن. شماره تلفن دو صورتحساب دارد؛ شناسه پرداخت یکی را.

دو دکمه، نه یکی

دو بخش را در دو کارت جدا نشان دهید و هر کارت دکمهٔ خودش را داشته باشد. دکمهٔ «پرداخت همه» را فقط وقتی بگذارید که بتوانید دو پرداخت مجزا را به شکل قابل‌پیگیری انجام دهید. رابط‌هایی که یک مبلغ جمع‌شده نشان می‌دهند و یک پرداخت می‌گیرند، معمولاً اولین بار که کاربر فقط یکی از دو قبض را می‌خواهد بپردازد، گیر می‌کنند.

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

بلافاصله بعد از پرداخت استعلام نزنید

وسوسهٔ طبیعی این است که بعد از موفقیت درگاه، دوباره استعلام بزنید تا مبلغ صفر ببینید و به کاربر «قبض تسویه شد» نشان دهید. دو مانع دارد.

اولی کش است. پاسخ قبوض در کش مشترک فعلاً یک ساعت تازه می‌ماند، پس استعلام فوری ممکن است همان مبلغ قبل از پرداخت را با source.cached: true برگرداند. دومی تأخیر ثبت پرداخت در سامانهٔ مبدأ است: ثبت پرداخت و به‌روز شدن بدهی لحظه‌ای نیست، و این در قبض را پرداخت کردم ولی هنوز بدهی نشان می‌دهد شرح داده شده.

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

جلوگیری از پرداخت دوباره

ساده‌ترین محافظ: برای هر شناسه پرداخت یک رکورد پرداخت نگه دارید و اگر پرداخت موفق دارد، دکمهٔ آن بخش را برای چند ساعت غیرفعال کنید و بنویسید «پرداخت شما در انتظار ثبت است». نمی‌دانم چند ساعت درست است و عدد را به قاعدهٔ سرویس مرجع نسبت نمی‌دهم؛ مقدارش را در تنظیمات بگذارید و با داده‌ای که خودتان جمع می‌کنید تنظیم کنید.

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

زمان و برچسب تازگی

هر مبلغی را با زمان استعلام نشان دهید. source.fetchedAt همین را می‌دهد، و اگر stale درست بود (یعنی سرویس مرجع در دسترس نبود و آخرین پاسخ معتبر آمده)، بنویسید «آخرین اطلاعات معتبر، مال فلان زمان». کاربر پیش از پرداخت باید بداند مبلغ را کی می‌بیند.

برای کاربر پشتیبانی هم requestId پاسخ را کنار هر تلاش ذخیره کنید. وقتی کسی بگوید «پرداخت کردم ولی هنوز بدهکار نشان می‌دهد»، با آن می‌توانید همان استعلام را پیدا کنید.

خطاها در این صفحه

• ورودی نامعتبر (invalid_input): شماره را اصلاح کنید؛ بدون هزینه.
• not_found: خط شناخته نشد؛ با HTTP ۲۰۰ می‌آید و هزینه دارد. پیشنهاد «شماره را بررسی کنید» بدهید.
• temporarily_unavailable و provider_failed_retryable: بدون هزینه، بعداً تلاش کنید.
• insufficient_funds: موجودی حساب شما در API تمام شده؛ این برای کاربر نباید «خطای شما» ظاهر شود.

جدول کامل و هدرهای نرخ در مستندات فنی API آمده است.

آنچه این سرویس نمی‌کند

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

نمونهٔ ساختار داده

برای سادگی، یک رکورد به ازای هر شناسه پرداخت کافی است:

json { "paymentId": "…", "term": "final_term", "amount": 0, "state": "needs_payment", "fetchedAt": "2026-09-23T10:00:00.000Z", "requestId": "req_…" }

فیلدها نمونه‌اند و دلخواه شما می‌توانند باشند. نکتهٔ اصلی این است که paymentId کلید است، term فقط برچسب نمایش، و state را شما مدیریت می‌کنید، نه پاسخ API. وقتی استعلام بعدی آمد، رکورد را با شناسه پرداخت پیدا کنید و فقط مبلغ و زمان را به‌روز کنید. اگر شناسهٔ جدیدی ظاهر شد (دوره‌ای تازه)، رکورد تازه بسازید و قبلی را بایگانی کنید.

برای دیدن شکل پاسخ در صفحهٔ سرویس قبض تلفن ثابت نمونه‌ها را ببینید.

وقتی یکی از دو بخش نیست

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

در یک نگاه

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