تکمیل خودکار آدرس با کد پستی در فرم سفارش

بهترین جای کد پستی در فرم سفارش، بالاتر از نشانی است، نه بعد از آن. کاربر ده رقم را تایپ می‌کند، فرم استان و شهر و خیابان را پر می‌کند و او فقط پلاک و واحد را می‌نویسد. ایده ساده است؛ جزئیاتش است که فرم را خوب یا آزاردهنده می‌کند.

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

فراخوان را کِی بزنیم

وقتی دقیقاً ده رقم کامل شد، نه زودتر. فرستادن درخواست روی هر کاراکتر یعنی نُه فراخوان بی‌معنا برای هر کاربر، و هر فراخوانی که به سرویس برسد حساب می‌شود.

الگوی ساده این است:

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

نمونه درخواست، از سمت سرور شما (کلید هرگز در مرورگر نباشد):

bash curl -X POST 'https://<دامنه-ما>/api/v1/address-lookup/' \ -H 'Authorization: Bearer melli_live_…' \ -H 'Content-Type: application/json' \ -d '{"postalCode":"1312345678"}'

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

با فیلدهای برگشتی چه کنیم

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

سه قاعدهٔ کوچک که بعداً جلوی باگ را می‌گیرد:

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

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

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

فیلدهای پرشده را قفل نکنید

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

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

وقتی نتیجه نیامد

سه حالت متفاوت را متفاوت نشان بدهید:

• ورودی نامعتبر (invalid_input): کاربر ده رقم نزده یا چیز دیگری وارد کرده. پیام کوتاه و همان‌جا. این حالت هزینه ندارد.
• نشانی پیدا نشد (not_found): استعلام انجام شده و جوابش «نیست» بوده. این پاسخ معتبر است و هزینه دارد، پس فرم را طوری بنویسید که کاربر مدام همان کد را دوباره نزند. به او اجازه بدهید نشانی را دستی بنویسد.
• خطای گذرا (provider_failed_retryable یا temporarily_unavailable): تقصیر کاربر نیست. فرم باید بدون پیام ترسناک به حالت دستی برگردد، و شما یک بار بعداً تلاش کنید.

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

کش و تکرار

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

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

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

مختصات جغرافیایی هم در این پاسخ نیست؛ برای نقشه و فاصله سرویس جدا لازم دارید. و فراموش نکنید که مسیر برعکس (نشانی به کد پستی) وجود ندارد: اگر مشتری کد پستی‌اش را نمی‌داند، فرم باید راه دیگری برایش بگذارد.

یک آزمایش پیش از انتشار

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

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

خلاصه برای مرور بعدی

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