مستندات API تبدیل کد پستی به آدرس

مستندات API تبدیل کد پستی به آدرس | راهنمای کامل استفاده

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

📝 توضیحات سرویس

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

🏷️ CURL

📡 POST api/v2/postal_code

curl --location --request POST 'https://shabanic.ir/api/v2/postal_code' \
--header 'SHABANIC-API-KEY: {YOUR_SHABANIC_TOKEN}' \
--form 'postalCode="YOUR_POSTAL_CODE"'

📌 ورودی های سرویس

🗂️ JSON Inputs

{
postalCode : "YOUR_POSTAL_CODE"
}

📤 خروجی سرویس

🧾 JSON Response

{
  "success": true,
  "trackId": "shabanic-6a2adff213bee8.63314666",
  "message": null,
  "result": {
    "city": "تهران",
    "province": "تهران",
    "township": "تهران",
    "locality": "جاهدشهر",
    "avenue": "خیابان جاهد [میثاق 2]",
    "stopStreet": "خیابان شهید کاظمی 2",
    "no": "0",
    "floor": "3",
    "zone": "مرکزی",
    "localityType": "شهر",
    "village": "null",
    "sideFloor": "10",
    "buildingName": "ماهان 1"
  },
  "statusCode": 200
}

{
	"success": false,
	"error_code": "FN-BRFH-50000040816",
	"message": "پیغام مرتبط با خطا",
	"trackId": "shabanic-699dcc859daf40.50355751"
}
برای پیگیری خطا کافیست مقدار trackId را به پشتیبانی شبانیک بدهید.

ℹ️ توضیحات سرویس تبدیل کد پستی به آدرس

این سرویس برای تبدیل کد پستی به آدرس استفاده می‌شود. در ادامه مشخصات کامل درخواست و پاسخ را مشاهده می‌کنید.

ورودی‌ها (Parameters)

  • postalCode — کد پستی ده رقمی

خروجی‌ها (Response)

  • success — وضعیت کلی درخواست (true / false)
  • trackId — شناسه پیگیری درخواست
  • city — شهر
  • province — استان
  • township — شهرستان
  • locality — محله
  • avenue — معبر اول
  • stopStreet — معبر آخر
  • no — پلاک
  • floor — طبقه
  • zone — منطقه شهری
  • localityType — نوع منطقه
  • village — دهستان
  • sideFloor — واحد
  • buildingName — نام ساختمان

کاربرد های این Api

  • احراز آدرس —تکمیل خودکار آدرس کاربران با کد پستی 10 رقمی
  • فروشگاه اینترنتی —کاهش خطای ثبت آدرس در سفارش‌های آنلاین
  • ارسال مرسوله — افزایش دقت تحویل کالا با تبدیل کد پستی به آدرس
  • اعتبارسنجی مکانی —بررسی صحت آدرس مشتری پیش از ثبت نهایی
  • فرم ثبت‌نام —ساده‌سازی تکمیل فرم‌های آدرس در سایت و اپلیکیشن
  • پشتیبانی لجستیک —استخراج جزئیات مکانی برای سیستم‌های حمل‌ونقل
  • سامانه پستی — بازیابی دقیق استان، شهر و محله از روی کد پستی
  • تکمیل آدرس —تبدیل سریع کد پستی به آدرس کامل در فرم‌های ثبت‌نام
  • ثبت سفارش —کاهش خطای ورود آدرس در فروشگاه‌های اینترنتی
  • پیک و حمل‌ونقل —مسیردهی بهتر برای ناوگان توزیع و تحویل کالا
  • املاک و مستغلات —استخراج جزئیات مکانی ملک از روی کد پستی
  • تحلیل منطقه‌ای —دسته‌بندی کاربران بر اساس شهر، محله و منطقه جغرافیایی

نکات مهم

  • فعال‌سازی API شبانیک — برای شروع استفاده از APIهای شبانیک، ابتدا پروفایل خود را تکمیل کنید (مشاهده پروفایل) و سپس با پشتیبانی مستقیم شبانیک (09156012679) برای صدور مجوز و دریافت توکن اقدام نمایید.
  • توکن شبانیک — پس از دریافت مجوز، توکن خود را به‌عنوان Bearer در هدر درخواست‌ها قرار دهید.

🎬 ویدئوی آموزشی API تبدیل کد پستی به آدرس

در این ویدئو نحوه فراخوانی API تبدیل کد پستی به آدرس از سامانه شبانیک توضیح داده شده است.

_

💻 دانلود نمونه کدهای API تبدیل کد پستی به آدرس

در این بخش می‌توانید نمونه کدهای آماده برای فراخوانی API تبدیل کد پستی به آدرس شبانیک به زبان‌های PHP (Laravel)، JavaScript (Node.js)، Python، Java، Kotlin، C# (.NET) و cURL را دانلود کرده و مستقیماً در پروژه خود استفاده کنید.

نمونه کد PHP (Laravel) برای فراخوانی API تبدیل کد پستی به آدرس

دانلود فایل PHP

نمونه کد JavaScript (Node.js) برای استفاده از API تبدیل کد پستی به آدرس

دانلود فایل JavaScript

نمونه کد Python برای اتصال به API تبدیل کد پستی به آدرس شبانیک

دانلود فایل Python

نمونه کد Java (اندروید) برای فراخوانی API تبدیل کد پستی به آدرس

دانلود فایل Java

نمونه کد Kotlin برای استفاده از API تبدیل کد پستی به آدرس در اپلیکیشن موبایل

دانلود فایل Kotlin

نمونه کد C# (.NET) برای اتصال به API تبدیل کد پستی به آدرس

دانلود فایل C#

نمونه درخواست cURL برای تست API تبدیل کد پستی به آدرس

دانلود فایل cURL
دانلود همه نمونه کدهای API این سرویس به صورت (ZIP)

❓ سوالات متداول (FAQ)

پاسخ به سوالات رایج در استفاده از سرویس تبدیل کد پستی به آدرس.

بله، این سرویس جزئیات کامل شامل شماره پلاک، طبقه و واحد (sideFloor) را در صورت موجود بودن در پایگاه داده پستی بازمی‌گرداند تا فرآیند ثبت دقیق آدرس به صورت خودکار انجام شود.

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

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

درخواست آدرس متنی از کاربر باعث ایجاد “داده‌های کثیف” و غلط املایی می‌شود. استفاده از کد پستی، ضمن افزایش سرعت تکمیل فرم توسط کاربر (به دلیل کمتر تایپ کردن)، اعتبار و دقت آدرس ثبت شده در پایگاه داده شما را تضمین می‌کند.

سیستم به صورت هوشمند کد پستی را اعتبارسنجی می‌کند. در صورتی که کد پستی در دیتابیس وجود نداشته باشد، پاسخ مناسب (status: false) دریافت می‌کنید که می‌توانید با استفاده از آن به کاربر پیام خطا نشان دهید تا کد را اصلاح کند.

علاوه بر آدرس کامل، این API اطلاعات ساختاریافته‌ای مانند نام محله (Locality)، منطقه شهرداری (Zone)، و نوع منطقه (LocalityType) را نیز ارائه می‌دهد که برای تحلیل‌های جغرافیایی مشتریان بسیار مفید است.

سامانه شبانیک به صورت دوره‌ای دیتابیس خود را با آخرین تغییرات کد پستی کشور همگام‌سازی می‌کند؛ بنابراین اطلاعات ارائه شده توسط API همیشه بر اساس آخرین داده‌های معتبر پستی است.

بله، با فراخوانی این API در لحظه‌ای که کاربر کد پستی را وارد می‌کند (رویداد onBlur)، می‌توانید فیلدهای آدرس (شهر، استان، خیابان) را به صورت خودکار برای کاربر پر کنید که تجربه کاربری فوق‌العاده‌ای در مرحله خرید ایجاد می‌کند.

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

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

آماده‌اید به ساده‌ترین شکل ممکن، API «تبدیل کد پستی به آدرس» را از شبانیک دریافت کنید؟

تنها در چند مرحله ساده، کلید اختصاصی API خود را دریافت کرده و سرویس تبدیل کد پستی به آدرس را در پروژه خود فعال کنید.

رفتن به پنل توسعه‌دهندگان
Shabanic Postman