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