مستندات API

معرفی API برای توسعه‌دهندگان

محصول API برآورد برای برنامه‌نویس‌ها و تیم‌های فنی شامل موارد زیر است:

• مستندات REST API (سرویس ها، پارامترها و نمونه پاسخ)
• نمونه کد PHP، Laravel، Node.js، C# / ABP MVC، Java و Python
• احراز هویت امن با توکن اختصاصی
• داشبورد مصرف (تعرفه روزانه، گزارش درخواست‌ها، کلید API)
• پلن همکاری یا نمایندگی برای استفاده سازمانی و white-label

آدرس پایه API: https://api2.baravard.com/api

احراز هویت و امنیت

پس از ثبت‌نام در صفحه API، توکن اختصاصی از پنل مدیریت API دریافت می‌شود. این توکن در پارامتر key تمام درخواست‌ها ارسال می‌شود.

در تمام نمونه‌های این صفحه، مقدار API_KEY را با توکن اختصاصی دریافتی از پنل برآورد جایگزین کنید.

داشبورد مصرف

در پنل مدیریت API می‌توانید:

• توکن API را مشاهده، کپی یا تجدید کنید
• IP و دامنه مجاز را محدود کنید
• تعرفه مصرفی روزانه و کل هر سرویس را ببینید
• از گزارش API برای ردیابی درخواست‌ها استفاده کنید
• کیف پول را از بخش شارژ کیف پول شارژ کنید

پلن همکاری یا نمایندگی

برای استفاده سازمانی، نمایشگاه‌ها، پلتفرم‌های واسط یا white-label، پلن‌های همکاری با تعرفه و پشتیبانی اختصاصی ارائه می‌شود. برای دریافت اطلاعات از طریق فرم ثبت‌نام API درخواست دهید یا با پشتیبانی برآورد تماس بگیرید.

نمونه کد اتصال به API برآورد

نمونه‌های زیر برای اتصال سمت سرور نوشته شده‌اند. در همه نمونه‌ها API_KEY را با توکن پنل جایگزین کنید.

۰. تست سریع با cURL

دریافت لیست قیمت خودروهای صفر:

curl "https://api2.baravard.com/api/car/zerolist?key=API_KEY"

قیمت‌گذاری پایه خودرو:

curl "https://api2.baravard.com/api/car/pricing?key=API_KEY&carId=734&model=1404&colorId=16103&km=15000"

دریافت موجودی کیف پول:

curl "https://api2.baravard.com/api/getcredit?key=API_KEY&plugin=false"

۱. PHP

کلاس ساده اتصال به API:

<?php

class BaravardApi
{
    private string $baseUrl = 'https://api2.baravard.com/api';
    private string $apiKey;

    public function __construct(string $apiKey)
    {
        $this->apiKey = $apiKey;
    }

    private function get(string $endpoint, array $params = []): array
    {
        $params['key'] = $this->apiKey;
        $url = $this->baseUrl . '/' . ltrim($endpoint, '/') . '?' . http_build_query($params);

        $ch = curl_init($url);
        curl_setopt_array($ch, [
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_TIMEOUT        => 30,
            CURLOPT_CONNECTTIMEOUT => 10,
            CURLOPT_HTTPHEADER     => ['Accept: application/json'],
        ]);

        $response = curl_exec($ch);
        $error    = curl_error($ch);
        $status   = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        curl_close($ch);

        if ($response === false) {
            throw new Exception('خطا در اتصال به API: ' . $error);
        }
        if ($status < 200 || $status >= 300) {
            throw new Exception('پاسخ ناموفق از API. کد وضعیت: ' . $status);
        }

        $data = json_decode($response, true);
        if (json_last_error() !== JSON_ERROR_NONE) {
            throw new Exception('پاسخ API معتبر نیست.');
        }
        return $data;
    }

    public function zeroPriceList(): array { return $this->get('car/zerolist'); }

    public function basePricing(int $carId, int $model, int $colorId, int $km): array
    {
        return $this->get('car/pricing', [
            'carId' => $carId, 'model' => $model, 'colorId' => $colorId, 'km' => $km,
        ]);
    }

    public function walletBalance(): array
    {
        return $this->get('getcredit', ['plugin' => 'false']);
    }
}

نمونه استفاده:

$baravard = new BaravardApi('API_KEY');

try {
    $result = $baravard->basePricing(734, 1404, 16103, 15000);
    print_r($result);
} catch (Exception $e) {
    echo $e->getMessage();
}

۲. Laravel

در .env:

BARAVARD_API_KEY=API_KEY
BARAVARD_BASE_URL=https://api2.baravard.com/api

در config/services.php:

'baravard' => [
    'key'      => env('BARAVARD_API_KEY'),
    'base_url' => env('BARAVARD_BASE_URL', 'https://api2.baravard.com/api'),
],

Service:

<?php

namespace App\Services;

use Illuminate\Support\Facades\Http;
use RuntimeException;

class BaravardService
{
    private string $baseUrl;
    private string $apiKey;

    public function __construct()
    {
        $this->baseUrl = rtrim(config('services.baravard.base_url'), '/');
        $this->apiKey  = config('services.baravard.key');
    }

    private function get(string $endpoint, array $params = []): array
    {
        $params['key'] = $this->apiKey;
        $response = Http::timeout(30)->acceptJson()
            ->get($this->baseUrl . '/' . ltrim($endpoint, '/'), $params);

        if ($response->failed()) {
            throw new RuntimeException('خطا در ارتباط با API برآورد.');
        }
        return $response->json();
    }

    public function zeroPriceList(): array { return $this->get('car/zerolist'); }

    public function basePricing(int $carId, int $model, int $colorId, int $km): array
    {
        return $this->get('car/pricing', compact('carId', 'model', 'colorId', 'km'));
    }

    public function walletBalance(): array { return $this->get('getcredit', ['plugin' => 'false']); }
}

Controller:

public function pricing(BaravardService $baravard): JsonResponse
{
    return response()->json($baravard->basePricing(734, 1404, 16103, 15000));
}

۳. Node.js (۱۸+)

const API_KEY = process.env.BARAVARD_API_KEY || 'API_KEY';
const BASE_URL = 'https://api2.baravard.com/api';

async function request(endpoint, params = {}) {
    const query = new URLSearchParams({ ...params, key: API_KEY });
    const response = await fetch(`${BASE_URL}/${endpoint}?${query}`, {
        headers: { Accept: 'application/json' },
    });
    if (!response.ok) throw new Error(`Status: ${response.status}`);
    return await response.json();
}

async function basePricing() {
    return request('car/pricing', {
        carId: '734', model: '1404', colorId: '16103', km: '15000',
    });
}

basePricing().then(console.log).catch(console.error);

۴. C# / .NET / ABP MVC

در appsettings.json:

{
  "Baravard": {
    "BaseUrl": "https://api2.baravard.com/api",
    "ApiKey": "API_KEY"
  }
}

public class BaravardService : IBaravardService, ITransientDependency
{
    private readonly HttpClient _httpClient;
    private readonly string _baseUrl;
    private readonly string _apiKey;

    public BaravardService(HttpClient httpClient, IConfiguration configuration)
    {
        _httpClient = httpClient;
        _baseUrl = configuration["Baravard:BaseUrl"]?.TrimEnd('/')
            ?? "https://api2.baravard.com/api";
        _apiKey = configuration["Baravard:ApiKey"]
            ?? throw new Exception("Baravard API Key is not configured.");
    }

    public async Task<object?> GetBasePricingAsync(int carId, int model, int colorId, int km)
    {
        var url = $"{_baseUrl}/car/pricing?key={Uri.EscapeDataString(_apiKey)}"
            + $"&carId={carId}&model={model}&colorId={colorId}&km={km}";
        var response = await _httpClient.GetAsync(url);
        response.EnsureSuccessStatusCode();
        return await response.Content.ReadFromJsonAsync<object>();
    }
}

// Module: context.Services.AddHttpClient<IBaravardService, BaravardService>(...);

۵. Java / Spring Boot

در application.yml:

baravard:
  base-url: https://api2.baravard.com/api
  api-key: API_KEY

Service (RestTemplate):

@Service
public class BaravardService {
    private final RestTemplate restTemplate;
    private final BaravardProperties properties;

    public Object getBasePricing(int carId, int model, int colorId, int km) {
        String baseUrl = properties.getBaseUrl().replaceAll("/$", "");
        String url = UriComponentsBuilder.fromHttpUrl(baseUrl + "/car/pricing")
            .queryParam("key", properties.getApiKey())
            .queryParam("carId", carId).queryParam("model", model)
            .queryParam("colorId", colorId).queryParam("km", km)
            .toUriString();
        return restTemplate.getForObject(url, Object.class);
    }
}

Controller:

@RestController
public class CarPriceController {
    @GetMapping("/api/cars/pricing")
    public Object pricing() {
        return baravardService.getBasePricing(734, 1404, 16103, 15000);
    }
}

۶. Python

import requests

class BaravardApi:
    def __init__(self, api_key: str, base_url: str = "https://api2.baravard.com/api"):
        self.api_key = api_key
        self.base_url = base_url.rstrip("/")

    def get(self, endpoint: str, params: dict | None = None):
        if params is None:
            params = {}
        params["key"] = self.api_key
        response = requests.get(
            f"{self.base_url}/{endpoint.lstrip('/')}",
            params=params, timeout=30,
            headers={"Accept": "application/json"},
        )
        response.raise_for_status()
        return response.json()

    def base_pricing(self, car_id, model, color_id, km):
        return self.get("car/pricing", {
            "carId": car_id, "model": model, "colorId": color_id, "km": km,
        })

baravard = BaravardApi(api_key="API_KEY")
print(baravard.base_pricing(734, 1404, 16103, 15000))

نکات مهم پیاده‌سازی

1. توکن را در فرانت‌اند قرار ندهید. فرانت‌اند → سرور مشتری → API برآورد.
2. تایم‌اوت درخواست‌ها را حدود ۳۰ ثانیه تنظیم کنید.
3. کش برای لیست خودرو، رنگ و zerolist سمت سرور مشتری توصیه می‌شود.
4. قیمت‌گذاری پایه ممکن است از کیف پول کسر شود؛ پس از تکمیل اطلاعات کاربر ارسال کنید.
5. خطاها: به کاربر پیام ساده («در حال حاضر امکان دریافت قیمت وجود ندارد») و در لاگ سرور جزئیات (timeout، invalid token، wallet error).

میزان اعتبار - Credit

از این متد برای دریافت باقیمانده اعتبار استفاده می‌کنیم.

دسترسی به این API پس از ثبت درخواست با وارد کردن توکن به جای key مقدور خواهد بود و جهت ارسال درخواست سایر API های قیمت گذاری، اطلاعات این API مورد نیاز است.

استفاده از این API رایگان می باشد.

ساختار URL:

پارامترهای ورودی

پارامترهای خروجی

لیست خودروها - API Carlist

از این متد برای دریافت لیست خودروها استفاده می‌کنیم.

دسترسی به این API پس از ثبت درخواست با وارد کردن توکن به جای key مقدور خواهد بود و جهت ارسال درخواست سایر API های قیمت گذاری، اطلاعات این API مورد نیاز است.

استفاده از این API رایگان می باشد.

ساختار URL:

پارامترهای ورودی

پارامترهای خروجی

لیست رنگ‌های خودرو - API CarColorList

از این متد برای دریافت لیست رنگ خودروها استفاده می‌کنیم.

ساختار URL:

پارامترهای ورودی

پارامترهای خروجی

لیست قیمت صفر - API Zero List

از این متد برای دریافت لیست قیمت خودروهای صفر استفاده می‌شود.

ساختار URL:

پارامترهای ورودی

پارامترهای خروجی

نمونه خروجی

  
{  
    "cars": [  
        {  
            "Id": 15,  
            "Name": "سمند سورن پلاس مالتی مدیا",  
            "SubName": "EF7 رینگ فولادی",  
            "Price": 750000000,  
            "CompanyPrice": 500000000,  
            "PriceDate": "2025-02-02T15:45:01.1304854",  
            "OldDayPrice": 750000000,  
            "BrandId": 425,  
            "RootBrandName": "سمند",  
            "EndYear": 1402,  
            "Percent": 0.0  
        },  
        {  
            "Id": 28,  
            "Name": "دنا پلاس توربو اتوماتیک",  
            "SubName": "",  
            "Price": 1030000000,  
            "PriceDate": "2025-02-02T15:34:59.2586676",  
            "OldDayPrice": 1030000000,  
            "BrandId": 22,  
            "RootBrandName": "دنا",  
            "EndYear": 1404,  
            "Percent": 0.0  
        }  
    ]  
}  
            

قیمت‌گذاری - API Pricing

از این متد برای قیمت‌گذاری خودروها استفاده می‌کنیم.

ساختار URL:

پارامترهای ورودی

پارامترهای خروجی

قیمت گذاری تخصصی خودرو - API Car Full Pricing

از این متد برای دریافت جزئیات قیمت خودرو استفاده می‌شود.

ساختار URL:

پارامترهای ورودی

نمونه ورودی

  
{
  "token": "*****-*****-*****-*****-*****",
  "carId": 778,
  "colorId": -1,  
  "carUserKm": -1,
  "carUserModel": -1,

  "coloredSpots": 0,
  "carUserScratch": 0,

  "carUserReplacedRoom": false,
  "carUserReplacedKapoot": false,
  "carUserReplacedSaghf": false,
  "carUserReplacedSandogh": false,
  "carUserReplacedDoorFL": false,
  "carUserReplacedDoorFR": false,
  "carUserReplacedDoorBL": false,
  "carUserReplacedDoorBR": false,
  "carUserReplacedMudguardFL": false,
  "carUserReplacedMudguardFR": false,
  "carUserReplacedMudguardBL": false,
  "carUserReplacedMudguardBR": false,

  "carUserColoredFull": false,
  "carUserColoredAround": false,
  "carUserColoredKapoot": true,
  "carUserColoredSaghf": false,
  "carUserColoredSandogh": false,
  "carUserColoredDoorFL": false,
  "carUserColoredDoorFR": false,
  "carUserColoredDoorBL": false,
  "carUserColoredDoorBR": false,
  "carUserColoredMudguardFL": false,
  "carUserColoredMudguardFR": false,
  "carUserColoredMudguardBL": false,
  "carUserColoredMudguardBR": false,
  "carUserColoredRekabR": false,
  "carUserColoredRekabL": false,

  "carUserColorLessRefinementKapoot": false,
  "carUserColorLessRefinementSaghf": false,
  "carUserColorLessRefinementSandogh": false,
  "carUserColorLessRefinementBottomSandogh": false,
  "carUserColorLessRefinementDoorFL": false,
  "carUserColorLessRefinementDoorFR": false,
  "carUserColorLessRefinementDoorBL": false,
  "carUserColorLessRefinementDoorBR": false,
  "carUserColorLessRefinementMudguardFL": false,
  "carUserColorLessRefinementMudguardFR": false,
  "carUserColorLessRefinementMudguardBL": false,
  "carUserColorLessRefinementMudguardBR": false,

  "carUserHitChassisFL": false,
  "carUserHitChassisFR": false,
  "carUserHitChassisBL": false,
  "carUserHitChassisBR": false,
  "carUserHitSiniFL": false,
  "carUserHitSiniFR": false,
  "carUserHitSiniBL": false,
  "carUserHitSiniBR": false,

  "carUserHitSotoonFL": false,
  "carUserHitSotoonFR": false,
  "carUserHitSotoonBL": false,
  "carUserHitSotoonBR": false,
  "carUserHitSotoonML": false,
  "carUserHitSotoonMR": false,
  "carUserHitKalafL": false,
  "carUserHitKalafR": false,

  "carUserRotKapoot": false,
  "carUserRotChassis": false,
  "carUserRotSandogh": false,
  "carUserRotFloor": false,
  "carUserRotRekab": false,
  "carUserRotMudguard": false,

  "carUserSunburnKapoot": false,
  "carUserSunburnSaghf": false,
  "carUserSunburnSandogh": false,
  "carUserSunburnMudguard": false
}
    

پارامترهای خروجی

افت قیمت خودرو - API Falling

از این متد برای محاسبه افت قیمت خودرو خودروها استفاده می‌کنیم.

ساختار URL:

پارامترهای ورودی

دقیقا ورودی های سرویس قیمت گذاری تخصصی خودرو می باشد.

نمونه خروجی

  
{  
    "CarId": 788,  
    "CarModel": 1401,  
    "CarKm": 0.0,  
    "CarBrandName": "شاهین دنده ای G",  
    "PriceDate": "2025-02-02T15:45:39.4495186",  
    "IntDaysOldPriceDate": 3.0,  
    "CarPrice": 760000000,  
    "CarPriceBaseKarkard": 730000000,  
    "PriceOptions": 0,  
    "PriceRing": 0,  
    "PriceCostOptions": 0,  
    "PriceCostHealthCooler": 0,  
    "PriceCostHealthEngine": 0,  
    "PriceCostHealthJeloBandy": 0,  
    "PriceCostHealthHeaters": 0,  
    "PriceCostHealthGearBox": 0,  
    "PriceCostNeedSmoothBody": 0,  
    "PriceInsurance": 0,  
    "PriceReplaced": 0,  
    "PriceKarkard": 31000000,  
    "PriceColor": 0,  
    "PriceLining": 0,  
    "PriceFrontTires": 0,  
    "PriceBackTires": 0,  
    "PriceColoredParts": 0,  
    "PriceHitChassis": 0,  
    "PriceRot": 0,  
    "PriceSmoothBody": 0,  
    "PriceScratch": 0,  
    "PriceColored": 0,  
    "PriceReduction": 0,  
    "PriceSunburn": 0,  
    "PriceHitdSotoon": 0,  
    "PricingFactors": [  
        {  
            "Name": "آپشنهای اضافی",  
            "Price": 0  
        },  
        {  
            "Name": "رینگ",  
            "Price": 0  
        },  
        {  
            "Name": "آپشنها",  
            "Price": 0  
        },  
        {  
            "Name": "سیستم تهویه",  
            "Price": 0  
        },  
        {  
            "Name": "موتور",  
            "Price": 0  
        },  
        {  
            "Name": "جلوبندی",  
            "Price": 0  
        },  
        {  
            "Name": "گرمکن",  
            "Price": 0  
        },  
        {  
            "Name": "گیربکس",  
            "Price": 0  
        },  
        {  
            "Name": "صافکاری و رنگ",  
            "Price": 0  
        },  
        {  
            "Name": "اعتبار بیمه",  
            "Price": 0  
        },  
        {  
            "Name": "کم کار",  
            "Price": 31000000  
        },  
        {  
            "Name": "رنگ خودرو",  
            "Price": 0  
        },  
        {  
            "Name": "تودوزی",  
            "Price": 0  
        },  
        {  
            "Name": "لاستیک جلو",  
            "Price": 0  
        },  
        {  
            "Name": "لاستیک عقب",  
            "Price": 0  
        },  
        {  
            "Name": "رنگ شدگی",  
            "Price": 0  
        },  
        {  
            "Name": "ضربه خوردگی شاسی یا سینی",  
            "Price": 0  
        },  
        {  
            "Name": "پوسیدگی",  
            "Price": 0  
        },  
        {  
            "Name": "صافکاری بدون رنگ",  
            "Price": 0  
        },  
        {  
            "Name": "خط و خش",  
            "Price": 0  
        },  
        {  
            "Name": "لکه رنگی",  
            "Price": 0  
        },  
        {  
            "Name": "کاهش اضافی",  
            "Price": 0  
        },  
        {  
            "Name": "آفتاب سوختگی",  
            "Price": 0  
        },  
        {  
            "Name": "ضربه خوردگی ستون یا کلاف",  
            "Price": 0  
        },  
        {  
            "Name": "قطعات تعویضی بدنه",  
            "Price": 0  
        }  
    ]  
}