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