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

1. Обзор

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

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

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 }

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. Тарификация

10. Лимиты и кэширование

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

Время кэша задаётся в часах индивидуально для каждого клиента. Повторный запрос того же VIN в пределах кэша возвращается без обращения к ГИБДД. Принудительное обновление:

GET /score?vin=Z94K241BBJR061674&force_refresh=1

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. По запросу для токена настраивается список разрешённых IP; запросы с других адресов отклоняются с кодом IP_NOT_ALLOWED.

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

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

14. Поддержка

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

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