Главная → Документация → Краткие данные ТС

Краткие данные ТС

Короткая карточка автомобиля по VIN или государственному номеру: марка с моделью и годом выпуска, мощность, тип и объём двигателя, расположение руля, снаряжённая масса. Дешёвый запрос, которым удобно показать пользователю данные об автомобиле до покупки полного отчёта.

Когда это нужно

Метод задуман как витрина до покупки. Показав человеку «Лада Приора, 2009 г., 98 л.с.» сразу после ввода номера, вы даёте ему убедиться, что нашлась именно его машина, — и только потом предлагаете оплатить полный отчёт.

Владельцев, ограничений, ДТП и залогов здесь нет: для них есть история регистрации, ограничения и розыск, ДТП по базе ГИБДД и реестр залогов.

Аутентификация

Токен передаётся заголовком Authorization: Bearer <токен> либо параметром ?token=. Токен один для всех API — он в личном кабинете.

Эндпоинт

GET https://api.avtovincod.ru/brief

Параметры

Параметр	Описание	Обязателен
`vin`	VIN автомобиля, 17 символов	да*
`plate`	государственный номер, русскими буквами	да*

* Нужен ровно один из двух: vin и plate вместе — ошибка INPUT_CONFLICT. Госномер принимается и латиницей — похожие буквы приводятся к русским автоматически. Поиск по номеру кузова этот метод не поддерживает.

Пример запроса

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.avtovincod.ru/brief?vin=XTA21703090180422"

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.avtovincod.ru/brief?plate=А001АА178"

Пример ответа

{
  "success": 1,
  "query": { "vin": "XTA21703090180422" },
  "response": {
    "vin": "XTA21703090180422",
    "regNumber": "Т81***761",
    "mark_model": "ЛАДА 217030 ЛАДА ПРИОРА",
    "year": "2009",
    "horsepower": "98",
    "engine_type": "Газовый",
    "engine_vol": "1596",
    "wheel_type": "левый руль",
    "weight": "1130"
  }
}

Что возвращает

Поле	Значение
`vin`	VIN автомобиля — скрыт, если искали по госномеру
`regNumber`	государственный номер — скрыт, если искали по VIN
`mark_model`	марка, модель и год одной строкой
`year`	год выпуска
`horsepower`	мощность двигателя, л. с. (число строкой: «98»)
`engine_type`	тип двигателя: бензиновый, дизельный, газовый, электрический
`engine_vol`	рабочий объём двигателя, см³ (число строкой: «1596»)
`wheel_type`	расположение руля: левый или правый
`weight`	снаряжённая масса, кг (число строкой: «1130»)

Второй идентификатор приходит скрытым

Из пары «VIN — государственный номер» полностью возвращается только тот, по которому вы искали. Второй приходит частично закрытым звёздочками: Т81***761 при поиске по VIN, XWEG************* при поиске по номеру. Это не ошибка и не признак неполных данных — так устроен источник.

На сценарий «витрина до покупки» это работает: человек видит, что его автомобиль найден и второй идентификатор в базе есть, а получает он этот идентификатор уже в полном отчёте. Если он нужен сразу — используйте метод /gos2vin: он возвращает VIN и номер кузова по государственному номеру без сокрытия.

В коде рассчитывайте на строку со звёздочками, а не на пустое значение: поле приходит заполненным. Проверять на маску проще всего по наличию символа «звёздочка».

Коды ошибок

Код	Значение
`NO_TOKEN`	токен не передан
`TOKEN_INVALID`	токен недействителен или деактивирован
`NOT_ALLOWED`	API не подключён вашему токену
`INPUT_REQUIRED`	не передан ни vin, ни plate
`INPUT_CONFLICT`	переданы одновременно vin и plate — нужен ровно один
`BAD_VIN`	VIN не 17 символов либо содержит I, O, Q
`PLATE_INVALID`	госномер не похож на регистрационный знак
`NOT_FOUND`	автомобиль не найден — запрос не тарифицируется
`INSUFFICIENT_BALANCE`	недостаточно средств на балансе
`RATE_LIMIT`	превышен лимит запросов в минуту
`PROVIDER_FAIL`	источник не ответил, повторите позже

Примеры кода: PHP, Python, JavaScript, Go, Java, C#, Ruby, 1С

Примеры готовы к запуску: токен берётся из переменной окружения AVC_TOKEN, а в запросе стоит тестовое значение (vin=X7TEST00000000001). По тестовым значениям приходит ответ-образец по схеме метода: бесплатно, без списания и даже при нулевом балансе, с полем "testMode": true. Так интеграцию можно собрать и проверить до первого платного запроса. Все тестовые значения.

cURLPHPPythonJavaScriptGoJavaC#Ruby1С

curl -s --max-time 60 -G "https://api.avtovincod.ru/brief" \
  --data-urlencode "vin=X7TEST00000000001" \
  -H "Authorization: Bearer $AVC_TOKEN"

<?php
$url = 'https://api.avtovincod.ru/brief?' . http_build_query(['vin' => 'X7TEST00000000001']);
$ch  = curl_init($url);
curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 60,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('AVC_TOKEN')]]);
$d = json_decode(curl_exec($ch), true);
echo $d['success'] ? json_encode($d, JSON_UNESCAPED_UNICODE) : $d['code'] . ': ' . $d['error'];

import os, requests

r = requests.get("https://api.avtovincod.ru/brief", params={"vin": "X7TEST00000000001"},
                 headers={"Authorization": "Bearer " + os.environ["AVC_TOKEN"]}, timeout=60)
d = r.json()
print(d if d.get("success") else f'{d["code"]}: {d["error"]}')

// Node.js 18+, файл .mjs (await на верхнем уровне)
const url = "https://api.avtovincod.ru/brief?" + new URLSearchParams({ vin: "X7TEST00000000001" });
const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.AVC_TOKEN}` },
                               signal: AbortSignal.timeout(60000) });
const d = await res.json();
console.log(d.success ? d : `${d.code}: ${d.error}`);

package main

import (
	"fmt"
	"io"
	"net/http"
	"net/url"
	"os"
	"time"
)

func main() {
	q := url.Values{}
	q.Set("vin", "X7TEST00000000001")
	req, _ := http.NewRequest("GET", "https://api.avtovincod.ru/brief?"+q.Encode(), nil)
	req.Header.Set("Authorization", "Bearer "+os.Getenv("AVC_TOKEN"))
	resp, err := (&http.Client{Timeout: 60 * time.Second}).Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	body, _ := io.ReadAll(resp.Body)
	fmt.Println(resp.StatusCode, string(body))
}

// Java 11+
import java.net.URI;
import java.net.URLEncoder;
import java.net.http.*;
import java.nio.charset.StandardCharsets;
import java.time.Duration;

public class AvtoVinCod {
    public static void main(String[] args) throws Exception {
        String q = "vin=" + URLEncoder.encode("X7TEST00000000001", StandardCharsets.UTF_8);
        HttpRequest req = HttpRequest.newBuilder(URI.create("https://api.avtovincod.ru/brief?" + q))
            .header("Authorization", "Bearer " + System.getenv("AVC_TOKEN"))
            .timeout(Duration.ofSeconds(60)).GET().build();
        HttpResponse<String> resp = HttpClient.newHttpClient()
            .send(req, HttpResponse.BodyHandlers.ofString());
        System.out.println(resp.statusCode() + " " + resp.body());
    }
}

// .NET 6+
using System.Net.Http.Headers;

using var http = new HttpClient { Timeout = TimeSpan.FromSeconds(60) };
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("AVC_TOKEN"));
var url = "https://api.avtovincod.ru/brief?" + "vin=" + Uri.EscapeDataString("X7TEST00000000001");
var resp = await http.GetAsync(url);
Console.WriteLine((int)resp.StatusCode + " " + await resp.Content.ReadAsStringAsync());

require "net/http"
require "json"

uri = URI("https://api.avtovincod.ru/brief")
uri.query = URI.encode_www_form(vin: "X7TEST00000000001")
req = Net::HTTP::Get.new(uri)
req["Authorization"] = "Bearer #{ENV["AVC_TOKEN"]}"
res = Net::HTTP.start(uri.host, uri.port, use_ssl: true, read_timeout: 60) { |h| h.request(req) }
d = JSON.parse(res.body)
puts d["success"] == 1 ? d : "#{d["code"]}: #{d["error"]}"

Токен = "ВАШ_ТОКЕН";
Соединение = Новый HTTPСоединение("api.avtovincod.ru", 443, , , , 60, Новый ЗащищенноеСоединениеOpenSSL);
Запрос = Новый HTTPЗапрос("/brief?" + "vin=" + КодироватьСтроку("X7TEST00000000001", СпособКодированияСтроки.КодировкаURL));
Запрос.Заголовки.Вставить("Authorization", "Bearer " + Токен);
Ответ = Соединение.Получить(Запрос);

Чтение = Новый ЧтениеJSON;
Чтение.УстановитьСтроку(Ответ.ПолучитьТелоКакСтроку("UTF-8"));
Данные = ПрочитатьJSON(Чтение);
Чтение.Закрыть();

Если Данные.success = 1 Тогда
    Сообщить("Проверка выполнена");
Иначе
    Сообщить(Данные.code + ": " + Данные.error);
КонецЕсли;

Бесплатных тестовых периодов и долгих согласований нет: пополните баланс в личном кабинете и сразу проверяйте реальные машины. Токен выдаётся при регистрации, деньги списываются только по правилам метода (раздел "Тарификация"). Нужен доступ из ИИ-ассистента: MCP-сервер.

Примеры ответов: успешный, ошибка, источник недоступен

Успешный запрос

GET https://api.avtovincod.ru/brief?vin=XTA21703090180422
Authorization: Bearer ВАШ_ТОКЕН

HTTP 200, success: 1. Списание по тарифу метода, сумма и остаток в блоке billing (цифры в примере условные).

{
  "success": 1,
  "query": {
    "vin": "XTA21703090180422"
  },
  "response": {
    "vin": "XTA21703090180422",
    "regNumber": "Т00***00",
    "mark_model": "ЛАДА GFL110 LADA VESTA",
    "year": "2021",
    "horsepower": "106",
    "engine_type": "Бензиновый",
    "engine_vol": "1596",
    "wheel_type": "левый руль",
    "weight": "1230"
  },
  "billing": {
    "charged": 0.5,
    "currency": "RUB",
    "billed": true,
    "balance": 999.5,
    "requestId": 1234567
  }
}

Бесплатная проба без списания: https://api.avtovincod.ru/brief?vin=X7TEST00000000001 вернёт ответ-образец по этой же схеме с полем testMode: true и charged: 0.

Неуспешный запрос

GET https://api.avtovincod.ru/brief?vin=XTA2170309018042
Authorization: Bearer ВАШ_ТОКЕН

Ошибка в параметрах: HTTP 400, код BAD_VIN, текст ошибки можно показать пользователю. Бесплатно.

{
  "success": 0,
  "error": "VIN должен содержать 17 символов, у вас 16. Проверьте ввод.",
  "code": "BAD_VIN"
}

Источник недоступен

GET https://api.avtovincod.ru/brief?vin=XTA21703090180422
Authorization: Bearer ВАШ_ТОКЕН

Источник временно недоступен: HTTP 503, SERVICE_UNAVAILABLE. Бесплатно, повторите запрос позже. Запрос записан в историю с charged: 0.

{
  "success": 0,
  "error": "Сервис временно недоступен",
  "code": "SERVICE_UNAVAILABLE",
  "billing": {
    "charged": 0,
    "currency": "RUB",
    "billed": false,
    "balance": 999.5,
    "requestId": 1234569
  }
}

Тарификация

Списание происходит только за ответ с данными. Если автомобиль не найден (NOT_FOUND), деньги не берутся: у этого метода нет «пустого положительного» результата, платить не за что. Ошибки любого рода также бесплатны.

В ответ добавляется блок billing: сколько списано за этот запрос (charged, в рублях), платный ли он (billed), остаток баланса после запроса (balance) и номер в истории запросов (requestId). Те же данные в заголовках X-Charged, X-Balance, X-Request-Id. Нет блока - запрос не списан. Подробнее о блоке billing.

Уже подключены? Ничего менять не нужно.

Прежние поля ответа, коды ошибок, HTTP-статусы и правила списания остались как были. Интеграции, настроенные раньше, работают без изменений.
Новое только одно: в конец JSON добавлен блок billing, а в ответ пришли заголовки X-Charged, X-Balance, X-Request-Id. Использовать их не обязательно.
Если ваш код строго проверяет состав полей ответа (например, схема с запретом лишних полей), разрешите поле billing.

MCP-сервер для ИИ-ассистентов

Подключите проверки к ИИ-ассистенту: Claude, Cursor, VS Code и другим клиентам с поддержкой MCP (Model Context Protocol). Ассистент сам вызывает нужный метод по вашему токену, и проверку можно запросить обычными словами: "проверь залог и ограничения по VIN", "есть ли штрафы по СТС". Удобно менеджерам автосалона, лизинга и страховой без программиста, а разработчику помогает быстро собрать прототип интеграции.

Адрес сервера: https://api.avtovincod.ru/mcp, авторизация тем же токеном (Authorization: Bearer ВАШ_ТОКЕН).
Этот метод в MCP - инструмент vehicle_brief; всего инструментов 43.
Цены и списания как у API, в результате тоже есть блок billing. Тестовые значения работают бесплатно.
Инструкция по подключению: avtovincod.ru/docs/mcp/

Попробовать без программиста

В личном кабинете есть консоль проверки: введите VIN или госномер и получите результат в читаемом виде.

Открыть кабинет