شماره تلفن ثابت را چطور بنویسیم تا استعلام قبض پذیرفته شود؟

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

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

قالب درست

یازده رقم: صفر، کد شهر بدون صفر، شمارهٔ مشترک. مثلاً برای تهران با 021 شروع می‌شود و شمارهٔ هشت‌رقمی بعدش می‌آید:

02188776655

سرویس استعلام قبض تلفن ثابت این قالب را تنها قالب نهایی می‌داند و بقیه را به آن تبدیل می‌کند.

چه نوشتن‌هایی خودکار درست می‌شوند

برای راحتی کاربر، این‌ها همه به همان یازده رقم تبدیل می‌شوند:

• ارقام فارسی: ۰۲۱۸۸۷۷۶۶۵۵
• فاصله و خط تیره: 021-8877 6655
• پیش‌شمارهٔ کشور با علامت جمع: +982188776655
• پیش‌شمارهٔ کشور با دو صفر: 00982188776655

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

چه چیزهایی رد می‌شوند

سه حالت رایج:

شمارهٔ موبایل. شماره‌ای که با 09 شروع می‌شود تلفن ثابت نیست. قاعدهٔ ورودی ارقام اول را بررسی می‌کند: بعد از صفر، رقم باید بین یک تا هشت باشد، پس 09 رد می‌شود.

شمارهٔ بدون کد شهر. یک شمارهٔ هشت‌رقمی مثل 88776655 را کاربران محلی از حفظ دارند، ولی بدون کد شهر این شماره یکتا نیست. سرویس آن را نمی‌پذیرد.

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

پیام خطا به کاربر می‌گوید شماره را با کد شهر و یازده رقم وارد کند. در پاسخ API این به صورت invalid_input با HTTP ۴۰۰ می‌آید و فیلد fields نام فیلد مشکل‌دار را دارد. چنین پاسخی هزینه ندارد.

یک نکته که اعتبارسنجی نمی‌گیرد

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

برای اینکه ببینید بعد از آن چه می‌آید، راهنمای فنی API انواع پاسخ را شرح داده است. به‌طور خاص not_found با HTTP ۲۰۰ می‌آید و هزینه دارد، چون سرویس مرجع پرسیده شده است.

یک عبارت منظم برای فرم شما

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

^0[1-8]\d{9}$

این را روی رقم‌های لاتینِ پاک‌سازی‌شده اجرا کنید. اول فاصله و خط تیره را بردارید و ارقام فارسی را به لاتین ببرید. اگر پیش‌شمارهٔ کشور دارید، 0098 یا 98 را به 0 تبدیل کنید. بعد الگو را بزنید.

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

داخلی و شمارهٔ چندخطی

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

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

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

یک فرم خوب چه شکلی است

سه تصمیم کوچک در طراحی فرم، بخش بزرگی از خطاها را از بین می‌برد.

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

کنترل در لحظهٔ تایپ. شمارنده‌ای نشان دهد «۷ از ۱۱ رقم». کاربر وقتی می‌بیند ناقص است، پیش از ارسال اصلاح می‌کند. این از فرستادن شمارهٔ ده‌رقمی جلوگیری می‌کند.

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

چند خط در یک استعلام

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

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

خطاهایی که از شماره نیستند

اگر شماره‌تان درست است ولی نتیجه نگرفتید، خطا از جای دیگری است:

• unauthorized یعنی کلید نیست یا باطل شده.
• insufficient_funds یعنی موجودی حساب API تمام شده.
• rate_limited یعنی از سقف نرخ گذشته‌اید.
• temporarily_unavailable یعنی سرویس مرجع در دسترس نبوده و باید بعداً تلاش کنید.

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

مثال کامل یک درخواست

bash curl -X POST 'https://example.com/api/v1/bill-landline/' \ -H 'Authorization: Bearer melli_live_…' \ -H 'Content-Type: application/json' \ -d '{"phoneNumber":"021-8877 6655"}'

کلید ورودی phoneNumber است، نه mobile. اگر کدتان از الگوی قبض موبایل کپی شده و هنوز mobile می‌فرستد، به‌جای پاسخ، invalid_input می‌گیرید. نشانی و کلید در این نمونه جای‌نگهدارند.

اگر عجله دارید

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