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