استعلام کد پستی

آدرس سرویس: POST https:/carbon/v4.0/public_service/inquiry/postal_code

شرح

این سرویس جهت استعلام کد ملی مورد استفاده قرار می گیرد.

Headers

مقادیر زیر باید در هدر قرار بگیرد

  Authorization : Bearer {Token}
  clientAddress : client IP

توجه : برای دریافت توکن مربوطه به بخش سرویس توکن مراجعه فرمایید

توضیحات

Authorization: در این قسمت توکن دریافت شده از سرویس توکن را وارد نمایید

clientAddress: آی پی مشتری نهایی که سرویس را دریافت کرده است .

Parameters

request_number(نوع داده عددی):(اجباری) این شناسه جهت پیگیری های بعدی مورد استفاده قرار می گیرد و پیشنهاد میگردد یه شناسه یکتا به ازای هر درخواست توسط سامانه مشتری تولید و به این سرویس ارسال گردد. سامانه ابری کربن هیچ کنترلی بر روی عدم تکراری بودن این مقدار انجام نمی دهد.
postal_code (نوع داده عددی):(اجباری) کد پستی

نمونه درخواست:

curl --location 'https:/carbon/v4.0/public_service/inquiry/postal_code' \
--header 'Content-Type: application/json' \
--header 'accept: application/json' \
--header 'clientAddress: xxx' \
--header 'Authorization: ••••••' \
--data '{
    "request_number": "202511122024",
    "postal_code": "...."
}'

جواب موفق:

{
    "status": "0",
    "message": "تراکنش با موفقیت انجام شد",
    "timestamp": "2025-12-10 13:57:25.204",
    "tracking_number": "859675473",
    "request_number": "202511122024",
    "result": {
        "postal_code": "....",
        "street": "",
        "locality_name": "",
        "province": "",
        "building_name": "",
        "description": "",
        "floor": "",
        "house_number": "",
        "locality_code": "",
        "locality_type": "",
        "side_floor": "شمال شرقی",
        "second_street": " ",
        "sub_locality": "",
        "town_ship": "تهران",
        "village": "null",
        "zone": "مرکزی",
        "address": "",
        "entrance": "null",
        "builiding_name": "",
        "building_id": "",
        "plate_number": "8"
    },
    "transaction_details": {
        "available_wallet_balance": "101782000",
        "provider_name": "Pertikan",
        "service_price": "....",
        "curency": "IRR",
        "remaining_number_of_calls": "1000",
        "remaining_number_of_calls_day": "1000"
    },
    "errors": {}
}

جواب ناموفق:

{
    "status": "1",
    "message": "تراکنش ناموفق",
    "timestamp": "2025-12-10 13:59:35.886",
    "tracking_number": "20251210135935883",
    "req_id": "202511122024",
    "result": {},
    "transaction_detials": {},
    "errors": {
        "error_code": "6001",
        "error_description": "invalid input parameter: postal_code is not found ",
        "reference_name": "postal_code",
        "original_value": ""
    }
}

status: عدد 0 به معنی موفق و عدد 1 به معنی ناموفق می باشد
message: پاسخ از طرف سرویس سامانه ابری کربن
timestamp : زمان و تاریخ درخواست
request_number: شماره پیگیری ارسال شده در زمان فراخوانی
tracking_number: شماره پیگیری ایجاد شده توسط سامانه ابری کربن جهت بررسی های بعدی
result: آبجکتی از پاسخ سرویس شامل:
postal_code : کد پستی
street : خیابان
locality_name: نام محل
province: نام استان
building_name: نام ساختمان
description: توضیحات
floor: طبقه
house_number: شماره خانه
locality_code: کد محل
locality_type: مدل محل
side_floor: جهت واحد
second_street: دومین خیابان
sub_locality: محله
town_ship: شهرستان
village: روستا
zone: منطقه
address: آدرس
entrance: ورودی
building_name: نام ساختمان
building_id: شناسه ساختمان
plate_number: شماره پلاک

در صورت بروز خطا در درخواست :

errors: جزییات خطا
error_code: کد مربوط به خطایی که پیش آمده است
error_description: متن خطا
reference_name: اطلاعات تکمیلی خطا
original_value: اطلاعات تکمیلی خطا