Главная → Документация → Расшифровка VIN

Расшифровка VIN

Расшифровка самого VIN-номера: какой автомобиль в нём зашифрован. Марка, модель, поколение и кузов, двигатель с объёмом и мощностью, коробка и привод, годы выпуска, страна и город сборки, завод-изготовитель. Ответ в JSON.

Что это даёт

Это данные о конструкции автомобиля, а не о его истории. Расшифровка отвечает на вопрос "что это за машина", а не "что с ней было". Владельцев, ДТП, залогов и ограничений здесь нет, для них есть история регистрации, ДТП по базе ГИБДД, реестр залогов и ограничения и розыск.

Расшифровка не зависит от регистрационных действий: она остаётся верной после продажи автомобиля и после смены номеров. Её удобно показать сразу, ещё до запросов в государственные базы.

Полная расшифровка: full = 1

В VIN зашифрована платформа, а не конкретная машина. Один номер может подходить к нескольким модификациям: BMW X6 E71 выпускался и с бензиновым 4.4 на 558 л.с., и с дизельным 3.0 на 235 л.с. Поэтому метод отдаёт список вариантов variants, а их число в поле found.

Варианты мы сверяем с данными о самой машине: регистрационными (год, объём двигателя, мощность, топливо) и данными осмотров (коробка, привод, модификация). Если остаётся ровно один вариант, ответ приходит с "full": 1:

• в variants только этот вариант, found равно 1;
• модификацию можно показывать как точную, без выбора пользователем;
• пустые поля варианта (привод, коробка, модификация) заполняются, если они известны по осмотрам этой машины или таких же машин;
• у варианта registrationMatch: true, если он совпал с регистрацией, и тогда confirmed: true.

Если однозначно выбрать не получилось, приходит "full": 0 и только подходящие варианты. Совпали с регистрацией несколько: в variants только они (например, 4 из 55 возможных по этому VIN), found равно их числу. Ни один не совпал или сравнить не с чем: варианты, которые противоречат регистрации, убираются, остальные остаются. Цена одна и та же при full: 1 и full: 0.

Уже подключены? Менять ничего не нужно: запрос, цена и прежние поля остались как были. Поле full стоит сразу после found, смотреть на него не обязательно.

Как читать ответ

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

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

Эндпоинт

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

Параметры

Только VIN: расшифровывается сам номер, поэтому по госномеру или номеру кузова расшифровывать нечего. Если есть только госномер, получите VIN методом /gos2vin.

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

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

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

Ниже все исходы запроса с пояснениями. В примерах VIN условные, суммы в блоке billing тоже условные: цена зависит от тарифа. Перенос строк сделан для чтения, ответ приходит одной строкой JSON.

1. Определён один вариант (full: 1)

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

HTTP 200, success: 1, found: 1, full: 1. Модификация определена точно: вариант совпал с регистрационными данными машины по объёму (2488 см³) и мощности, поэтому registrationMatch: true и confirmed: true. Запрос платный, сумма и остаток в блоке billing.

{
  "success": 1,
  "query": { "vin": "RUMGJ523803054321" },
  "vin": { "requested": "RUMGJ523803054321", "normalized": "RUMGJ523803054321" },
  "found": 1,
  "full": 1,
  "variants": [
    {
      "title": "MAZDA 6",
      "brand": "MAZDA",
      "model": "6",
      "bodyName": null,
      "generation": "III",
      "trim": null,
      "modification": null,
      "market": "RU",
      "years": { "start": 2012, "finish": null, "current": true, "model": null },
      "body": "SDN",
      "drive": null,
      "doors": 4,
      "transmission": { "code": "AUT", "text": "автомат", "name": null, "speeds": null },
      "engine": {
        "series": null, "fuelCode": "PO", "fuelText": "бензин",
        "volumeL": 2.5, "volumeCcm": 2488,
        "powerPs": 191.71, "powerKw": 141, "torqueNm": 256,
        "emission": "Euro 5", "layout": "L4", "valves": null,
        "aspiration": "N", "compression": null, "fuelRate": "6.3"
      },
      "assembly": { "country": "Russia", "region": null, "city": null, "plant": null },
      "checkDigit": "absent",
      "powerSummary": "2.5{l} 191.71{PS} Euro 5",
      "plant": {
        "name": "ООО МАЗДА СОЛЛЕРС Мануфэкчуринг Рус",
        "brand": "MAZDA", "country": "Russia",
        "address": "690001 Приморский край г. Владивосток ул. Дальзаводская, 2",
        "phone": "(423) 251-37-11", "web": "mazda.ru",
        "registerDate": "01.10.2012", "regionCode": "25"
      },
      "registrationMatch": true
    }
  ],
  "confirmed": true,
  "decoded": true,
  "billing": {
    "charged": 1.8, "currency": "RUB", "billed": true,
    "balance": 998.2, "requestId": 1234567
  }
}

Поля, которых у источника нет (здесь привод и серия двигателя), приходят как null. Если они известны по осмотрам, при full: 1 они заполняются.

2. Несколько вариантов (full: 0)

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

HTTP 200, success: 1, found: 2, full: 0. Марка, модель, кузов F25, полный привод и завод определены точно: в обоих вариантах они одинаковые. Различается только коробка. В этом VIN она не зашифрована, в регистрационных данных коробку не указывают, осмотров этой машины нет. Сравнить не с чем, поэтому у обоих вариантов registrationMatch: null и confirmed: false.

Как показать пользователю: "BMW X3 xDrive (F25), полный привод, коробка: автомат или механика". Объём и мощность двигателя для этой модификации в расшифровке не указаны. Запрос платный, как и при одном варианте: расшифровка выполнена.

{
  "success": 1,
  "query": { "vin": "WBAWX51080L705318" },
  "vin": { "requested": "WBAWX51080L705318", "normalized": "WBAWX51080L705318" },
  "found": 2,
  "full": 0,
  "variants": [
    {
      "title": "BMW X3 xDrive",
      "brand": "BMW",
      "model": "X3",
      "bodyName": "F25",
      "generation": "II",
      "trim": null,
      "modification": null,
      "market": "EU",
      "years": { "start": 2009, "finish": null, "current": true, "model": null },
      "body": "WGN",
      "drive": "4WD",
      "doors": 5,
      "transmission": { "code": "AUT", "text": "автомат", "name": null, "speeds": null },
      "engine": {
        "series": null, "fuelCode": null, "fuelText": null,
        "volumeL": null, "volumeCcm": null,
        "powerPs": null, "powerKw": null, "torqueNm": null,
        "emission": null, "layout": null, "valves": null,
        "aspiration": null, "compression": null, "fuelRate": null
      },
      "assembly": {
        "country": "United States", "region": "South Carolina",
        "city": "Spartanburg", "plant": null
      },
      "checkDigit": "passed",
      "powerSummary": null,
      "plant": {
        "name": "Bayerische Motoren Werke AG", "brand": "BMW", "country": "Germany",
        "address": "Munchen 13 Munchen 13 Germany",
        "phone": null, "web": "bmw.com/com/en/",
        "registerDate": "31.03.1999", "regionCode": null
      },
      "registrationMatch": null
    },
    {
      "title": "BMW X3 xDrive",
      "brand": "BMW",
      "model": "X3",
      "bodyName": "F25",
      "generation": "II",
      "trim": null,
      "modification": null,
      "market": "EU",
      "years": { "start": 2009, "finish": null, "current": true, "model": null },
      "body": "WGN",
      "drive": "4WD",
      "doors": 5,
      "transmission": { "code": "MAN", "text": "механика", "name": null, "speeds": null },
      "engine": {
        "series": null, "fuelCode": null, "fuelText": null,
        "volumeL": null, "volumeCcm": null,
        "powerPs": null, "powerKw": null, "torqueNm": null,
        "emission": null, "layout": null, "valves": null,
        "aspiration": null, "compression": null, "fuelRate": null
      },
      "assembly": {
        "country": "United States", "region": "South Carolina",
        "city": "Spartanburg", "plant": null
      },
      "checkDigit": "passed",
      "powerSummary": null,
      "plant": {
        "name": "Bayerische Motoren Werke AG", "brand": "BMW", "country": "Germany",
        "address": "Munchen 13 Munchen 13 Germany",
        "phone": null, "web": "bmw.com/com/en/",
        "registerDate": "31.03.1999", "regionCode": null
      },
      "registrationMatch": null
    }
  ],
  "confirmed": false,
  "decoded": true,
  "billing": {
    "charged": 1.8, "currency": "RUB", "billed": true,
    "balance": 998.2, "requestId": 1234567
  }
}

Варианты, совпавшие с регистрацией (registrationMatch: true), всегда стоят первыми. Если берёте только variants[0], получаете наиболее вероятный вариант.

3. Только данные регистрации (decoded: false)

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

HTTP 200, success: 1, decoded: false, full: 0. Заводской расшифровки этого VIN нет, но машина нам известна: вариант собран из регистрационных данных. Есть марка, модель, год выпуска (years.model), объём, мощность и топливо. Завода, кузова, коробки и комплектации в таком ответе нет. Структура та же, что у обычной расшифровки, разбор менять не нужно. Запрос платный.

{
  "success": 1,
  "query": { "vin": "WVWZZZAUZEW198765" },
  "vin": { "requested": "WVWZZZAUZEW198765", "normalized": null },
  "found": 1,
  "full": 0,
  "variants": [
    {
      "title": "VOLKSWAGEN GOLF, 2013",
      "brand": "VOLKSWAGEN",
      "model": "GOLF",
      "bodyName": null,
      "generation": null,
      "trim": null,
      "modification": null,
      "market": null,
      "years": { "start": null, "finish": null, "current": false, "model": 2013 },
      "body": null,
      "drive": null,
      "doors": null,
      "transmission": { "code": null, "text": null, "name": null, "speeds": null },
      "engine": {
        "series": null, "fuelCode": null, "fuelText": "бензин",
        "volumeL": 1.4, "volumeCcm": 1395,
        "powerPs": 122, "powerKw": 89.73, "torqueNm": null,
        "emission": null, "layout": null, "valves": null,
        "aspiration": null, "compression": null, "fuelRate": null
      },
      "assembly": { "country": null, "region": null, "city": null, "plant": null },
      "checkDigit": null,
      "powerSummary": null,
      "plant": null,
      "registrationMatch": true
    }
  ],
  "decoded": false,
  "confirmed": true,
  "billing": {
    "charged": 1.8, "currency": "RUB", "billed": true,
    "balance": 998.2, "requestId": 1234567
  }
}

Здесь full всегда 0: без заводской расшифровки полной она быть не может.

4. VIN не расшифрован (NOT_DECODED)

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

HTTP 200, success: 0, code: NOT_DECODED. Расшифровать VIN не удалось, данных о машине тоже нет. Бесплатно, charged: 0. Частые причины: ошибка при вводе VIN, номер редкой или самодельной машины, номер шасси вместо VIN. Повторный запрос раньше чем через сутки вернёт такой же ответ, тоже бесплатно.

{
  "success": 0,
  "query": { "vin": "XTA210990Y2765432" },
  "error": "VIN не расшифрован",
  "code": "NOT_DECODED",
  "billing": {
    "charged": 0, "currency": "RUB", "billed": false,
    "balance": 1000, "requestId": 1234568
  }
}

5. Временный сбой (PROVIDER_FAIL)

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

HTTP 200, success: 0, code: PROVIDER_FAIL. Расшифровка сейчас не выполнена, бесплатно. Повторите через 10-15 минут: в первые 10 минут после сбоя повторный запрос этого VIN сразу возвращает такой же ответ. Код HTTP здесь 200, поэтому проверяйте поле success.

{
  "success": 0,
  "error": "Проверка не выполнена",
  "code": "PROVIDER_FAIL",
  "billing": {
    "charged": 0, "currency": "RUB", "billed": false,
    "balance": 1000, "requestId": 1234569
  }
}

6. Ошибка в запросе (BAD_VIN)

GET https://api.avtovincod.ru/decode?vin=WBAWX51080L70531

HTTP 400, code: BAD_VIN: в VIN 16 символов. Текст из error можно показать пользователю. Бесплатно и в историю не пишется, поэтому блока billing нет.

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

7. Недостаточно средств (INSUFFICIENT_BALANCE)

HTTP 402. Запрос не выполнялся, деньги не списаны. Пополните баланс в кабинете или включите автопополнение.

{
  "success": 0,
  "error": "Недостаточно средств. ",
  "code": "INSUFFICIENT_BALANCE"
}

Поля ответа

Поля варианта

Если данных нет, поле приходит как null, набор полей всегда один и тот же. Годы всегда числа: признак "выпускается сейчас" вынесен во флаг years.current.

Как определяется полная расшифровка

Данные регистрации и осмотров нужны только для выбора варианта. Госномер, СТС, владельцы и другие сведения о машине в ответ не попадают.

Как использовать full в своём коде

import requests

d = requests.get("https://api.avtovincod.ru/decode", params={"vin": "WBAWX51080L705318"},
                 headers={"Authorization": "Bearer ВАШ_ТОКЕН"}, timeout=60).json()

if not d.get("success"):
    print(d["code"], d["error"])                 # NOT_DECODED, PROVIDER_FAIL: бесплатно
elif d.get("full") == 1:
    v = d["variants"][0]                         # модификация определена точно
    print("Точно:", v["title"], v["transmission"]["text"])
elif not d.get("decoded"):
    v = d["variants"][0]                         # только данные регистрации
    print("По данным регистрации:", v["title"])
else:
    # несколько вариантов: общее показать как точное, различия списком
    gears = sorted({(v["transmission"]["text"] or "?") for v in d["variants"]})
    v = d["variants"][0]
    print(v["brand"], v["model"], "коробка:", " или ".join(gears))

Коды ошибок

Все ошибки приходят в виде {"success": 0, "error": "...", "code": "..."} и бесплатны. NOT_DECODED и PROVIDER_FAIL приходят с HTTP 200, поэтому проверяйте поле success.

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

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

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

<?php
$url = 'https://api.avtovincod.ru/decode?' . 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/decode", 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/decode?" + 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/decode?"+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/decode?" + 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/decode?" + "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/decode")
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Запрос("/decode?" + "vin=" + КодироватьСтроку("X7TEST00000000001", СпособКодированияСтроки.КодировкаURL));
Запрос.Заголовки.Вставить("Authorization", "Bearer " + Токен);
Ответ = Соединение.Получить(Запрос);

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

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

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

Тарификация

Списание один раз за выполненную расшифровку (success: 1), цена одна: при full: 1, при нескольких вариантах и при ответе из регистрационных данных. NOT_DECODED, PROVIDER_FAIL и ошибки бесплатны.

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

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

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

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