Документация API

1. Обзор

API возвращает данные базы ГИБДД по VIN-номеру транспортного средства. Один запрос - полный ответ: характеристики, история владения, документы, действующие ограничения и статус розыска.

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

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

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

Принцип работы

1. Клиент отправляет GET-запрос с VIN и токеном. 2. API проверяет токен, IP, лимиты и баланс. 3. VIN нормализуется (кириллица → латиница) и валидируется. 4. API запрашивает данные у ГИБДД - асинхронно, до 45 секунд. 5. При получении данных списывается стоимость запроса. 6. Клиент получает JSON с характеристиками, ограничениями и розыском.

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

Каждый клиент получает уникальный Bearer-токен (96 символов hex) при подключении. Передать его можно двумя способами.

Способ 1 - заголовок Authorization (рекомендуется)

GET /score?vin=Z94K241BBJR061674 HTTP/1.1
Host: api.avtovincod.ru
Authorization: Bearer ВАШ_ТОКЕН_96_СИМВОЛОВ

Способ 2 - параметр token в URL

GET /score?vin=Z94K241BBJR061674&token=ВАШ_ТОКЕН_96_СИМВОЛОВ

3. Эндпоинт и параметры

GET https://api.avtovincod.ru/score?vin={VIN}

Требования к VIN

Ровно 17 символов; латинские буквы A-Z (кроме I, O, Q) и цифры 0-9. Регистр не важен - API приводит его к верхнему. Примеры валидных VIN: Z94K241BBJR061674, WAUZZZ8UXER030082, WBALM71090E298475.

4. Нормализация VIN

Кириллические буквы, визуально совпадающие с латинскими, заменяются автоматически. Это снимает проблему VIN, скопированных из СТС, документов и старых баз, где кириллица и латиница перемешаны.

5. Формат ответа

Успешный ответ (success=1)

{
  "success": 1,
  "record": {
    "vin": "Z94K241BBJR061674",
    "bodyNumber": "Z94K241BBJR061674",
    "regNumber": null,
    "sts": { "num": null, "date": "2021-01-27" },
    "pts": { "num": null, "date": "2017-11-17" },
    "model": "HYUNDAI SOLARIS",
    "engineVolume": "1368",
    "color": "Белый",
    "powerHp": "99.6",
    "powerKwt": "73.3",
    "year": "2017",
    "maxWeight": "1600",
    "weightWithoutLoading": "1210",
    "category": "B",
    "lastRegAction": "В связи с изменением собственника",
    "recordStatus": "действующая",
    "ownershipPeriods": [
      { "personType": "Юридическое лицо", "from": "2017-12-23", "to": "2021-01-27" },
      { "personType": "Физическое лицо", "from": "2021-01-27", "to": null }
    ]
  },
  "restrictions": [],
  "searches": [],
  "status": {
    "restricted": false,
    "wanted": false,
    "spec_wanted": false
  }
}

Данные не найдены или ошибка (success=0)

{ "success": 0 }

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

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

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

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

{
  "success": 1,
  "found": 1,
  "record": {
    "vin": "Z94K241BBJR061674",
    "bodyNumber": null,
    "model": "LADA GFL110 LADA VESTA",
    "year": "2021",
    "color": "БЕЛЫЙ",
    "category": "B",
    "engineVolume": "1596",
    "powerHp": "106",
    "powerKwt": "78",
    "maxWeight": "1670",
    "weightWithoutLoading": "1230",
    "recordStatus": "действующая",
    "lastRegAction": "Изменение собственника",
    "ownershipPeriods": [
      {
        "personType": "Юридическое лицо",
        "from": "2021-06-01",
        "to": "2023-04-10"
      },
      ...
    ]
  },
  "restrictions": [
    {
      "restriction_name": "Запрет на регистрационные действия",
      "region": "г. Москва",
      "organization_name": "Судебный пристав",
      "reasons": "Документ: 0000 от 01.09.2026",
      "enforcement_number": "00000/00/00000-ИП",
      "enforcement_date": "2026-09-01",
      "osp_address": "г. Москва"
    }
  ],
  "searches": [],
  "status": {
    "restricted": true,
    "wanted": false,
    "spec_wanted": false
  },
  "billing": {
    "charged": 14,
    "currency": "RUB",
    "billed": true,
    "balance": 986,
    "requestId": 1234567
  }
}

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

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

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

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

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

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

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

Данные от источника не получены: HTTP 200, success: 0. Бесплатно, повторите запрос позже. Запрос записан в историю с charged: 0.

{
  "success": 0,
  "billing": {
    "charged": 0,
    "currency": "RUB",
    "billed": false,
    "balance": 986,
    "requestId": 1234569
  }
}

6. Описание полей

Корневые поля

Объект record

Элемент ownershipPeriods

7. Ограничения и розыск

Блок restrictions

Массив объектов, каждый - отдельное ограничение (запрет на регистрационные действия, наложенный судебными приставами):

"restrictions": [
  {
    "restriction_name": "Запрет на регистрационные действия",
    "region": "Краснодарский край",
    "organization_name": "Судебный участок № 62...",
    "reasons": "Документ: 709722738/2340 от 17.03.2026, П*******а О***а В********а...",
    "enforcement_number": "152126/26/23040-ИП",
    "enforcement_date": "2025-12-05",
    "osp_address": "350075, г. Краснодар, ул. Стасова, 180/1"
  }
]

Персональные данные в поле reasons маскируются: Петрусева Ольга Валерьевна → П*******а О***а В********а.

Блок searches

Блок status

8. Коды ошибок

При ошибке API возвращает success=0 плюс поля error и code:

{ "success": 0, "error": "Токен не передан.", "code": "NO_TOKEN" }

9. Тарификация

Стоимость в каждом ответе

Чтобы вести учёт у себя, не сверяясь с кабинетом, в ответ добавляется блок billing. Он есть во всех ответах, которые попали в историю запросов: и в платных, и в бесплатных (тогда charged равен 0).

{
  "success": 1,
  ...
  "billing": {
    "charged": 14,
    "currency": "RUB",
    "billed": true,
    "balance": 481,
    "requestId": 1234567
  }
}

Те же значения приходят в заголовках X-Charged, X-Balance и X-Request-Id: их можно читать, не разбирая тело ответа. Блока нет, если запрос не дошёл до учёта (неверный или пустой токен, ошибка до проверки доступа) или ничего не стоил по правилам метода (например, ДТП-задача ещё в работе или повторный опрос готовой задачи). Правило простое: нет блока billing - деньги не списаны.

В тестовом режиме блок тоже есть: charged 0, billed false, requestId null.

10. Лимиты

Лимиты раздельные и считаются по платным запросам: дневной (сброс в 00:00 МСК), месячный и годовой. Значение 0 означает отсутствие лимита; лимиты настраиваются администратором. При превышении API возвращает HTTP 429 с соответствующим кодом.

Если нужны заведомо свежие данные, запрос можно выполнить принудительно:

GET /score?vin=Z94K241BBJR061674

11. Примеры интеграции

curl -X GET "https://api.avtovincod.ru/score?vin=Z94K241BBJR061674" \
  -H "Authorization: Bearer ВАШ_ТОКЕН"

$token = 'ВАШ_ТОКЕН';
$vin = 'WAUZZZ8UXER030082';

$ch = curl_init("https://api.avtovincod.ru/score?vin={$vin}");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 60,
    CURLOPT_HTTPHEADER => ["Authorization: Bearer {$token}"],
]);
$data = json_decode(curl_exec($ch), true);
curl_close($ch);

if ($data['success'] === 1) {
    $r = $data['record'];
    echo "Модель: {$r['model']}, Год: {$r['year']}\n";
    echo "Владельцев: " . count($r['ownershipPeriods']) . "\n";

    if ($data['status']['restricted']) {
        foreach ($data['restrictions'] as $restr) {
            echo "Ограничение: {$restr['restriction_name']} ({$restr['region']})\n";
        }
    }
    if ($data['status']['wanted']) {
        echo "ТС в розыске!\n";
    }
} elseif (isset($data['code'])) {
    echo "Ошибка: {$data['code']} - {$data['error']}\n";
} else {
    echo "Данные не найдены\n";
}

import requests

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

if data.get("success") == 1:
    r = data["record"]
    print(f"{r['model']}, {r['year']}, {r['color']}")
    print(f"Ограничения: {data['status']['restricted']}")
    print(f"Розыск: {data['status']['wanted']}")

const res = await fetch(
  'https://api.avtovincod.ru/score?vin=Z94K241BBJR061674',
  { headers: { 'Authorization': 'Bearer ВАШ_ТОКЕН' } }
);
const data = await res.json();

if (data.success === 1) {
  const { model, year, color } = data.record;
  console.log(model, year, color);
  console.log('Ограничения:', data.status.restricted);
  console.log('Розыск:', data.status.wanted);
}

12. Безопасность

Токен. Храните как пароль: не публикуйте в открытых репозиториях, конфигах и фронтенде; передавайте только по HTTPS; используйте заголовок Authorization вместо параметра URL. При компрометации - сразу запросите сброс.

Белый список IP. Список разрешённых адресов вы задаёте сами в личном кабинете: раздел «Кабинет», блок «Доступ к API по IP». Подходят IPv4, IPv6 и подсети вида 203.0.113.0/24. Запросы с других адресов отклоняются с кодом IP_NOT_ALLOWED (HTTP 403) без списания. Проверки в личном кабинете, в Telegram-боте, пакетная проверка и мониторинг работают при любом списке.

Rate limiting. Не более 200 запросов в минуту с одного IP (глобально), плюс персональный лимит вашего токена.

13. Рекомендации по интеграции

14. Поддержка

Вопросы по интеграции и подключению: api@avtovincod.ru. Чтобы разбор был быстрым, приложите: ваш идентификатор клиента, дату и время запроса (UTC), использованный VIN и полный ответ API.

Токен ещё не получен - зарегистрируйтесь в личном кабинете: токен выдаётся сразу, после пополнения баланса запросы работают немедленно.