API و وب سرویس استعلام شاهکار

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

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

پیش از فراخوان چه چیزی را یکدست کنیم

شمارهٔ موبایل را همان‌جا که از کاربر می‌گیرید تمیز کنید. صورت‌های 09123456789 و +989123456789 و ارقام فارسی را اعتبارسنجی به یک شکل می‌رساند، اما شمارهٔ ناممکن با خطای invalid_input برمی‌گردد. آن خطا هزینه ندارد، ولی کاربر شما یک رفت‌وبرگشت بی‌دلیل را می‌بیند. کد ملی هم باید ده رقم و دارای رقم کنترل درست باشد.

چه وقت پاسخ منفی بی‌گناه است

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

با نتیجه چه کنیم

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

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

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