Главная → Документация → История авто в Беларуси

История авто в Беларуси

Быстрый отчёт по базам Республики Беларусь по VIN: дата ввоза и таможенного оформления, регистрации, техосмотры и пробеги, ДТП и страховые случаи, работа в такси, продажи на аварийных аукционах. Обычно готов за минуту. Полезно для машин, ввезённых в Россию из Беларуси.

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

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

Эндпоинт

GET https://api.avtovincod.ru/by-history

Можно и POST с теми же параметрами в теле формы.

Параметры

Марку сервис определяет по VIN сам (коды производителей NHTSA и наша база). Если определить её не удалось, отчёт заказывается без марки: на результат это не влияет, передавать brand не нужно. Какую марку подставим, можно узнать бесплатно: GET /vv-brand?vin=VIN&method=by_history (ответ: brand, required, candidates).

Как работает: заказ, номер задачи, опрос

Отчёт формируется обычно до минуты (иногда дольше), поэтому метод асинхронный, как ДТП по базе ГИБДД:

1. Заказ: GET /by-history?vin=VIN. Ответ сразу: status: "processing" и номер задачи taskId. Бесплатно.
2. Опрос: GET /by-history?task=taskId не чаще, чем через pollAfterSec секунд (обычно 30). Пока отчёт готовится - снова processing и оценка eta_sec. Опросы бесплатны.
3. Готово: status: "done", ссылки на файлы отчёта в report.files и блок billing - деньги списываются один раз, в этот момент. Повторный опрос той же задачи отдаёт тот же ответ без нового списания.

Задачу не нужно держать открытой: отчёт досчитается на сервере, даже если вы перестали опрашивать, и будет ждать по taskId. Повторный заказ того же VIN, пока первый готовится, вернёт тот же taskId (второй раз не платите).

Проверка наличия данных перед заказом. Перед каждым заказом сервис бесплатно спрашивает источник, есть ли по VIN данные для этого отчёта, ничего передавать для этого не нужно. Данных нет: ответ приходит сразу, NOT_AVAILABLE с полем "precheck": true, без задачи и без списания. Источник проверки не ответил: отчёт заказывается как обычно.

У источника проверки очередь (не чаще одного запроса в 3 секунды). Если она занята, сервис сам ждёт и повторяет до 25 секунд, поэтому ответ на заказ иногда приходит через 20-30 секунд: ставьте таймаут HTTP-клиента не меньше 60 секунд. Не дождались - ответ 429 SERVICE_BUSY с полем retryAfterSec (и заголовком Retry-After): повторите тот же запрос через указанное число секунд, деньги не списаны. Узнать заранее, в каких отчётах по VIN есть данные, можно методом Наличие данных по VIN.

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

curl -H "Authorization: Bearer $TOKEN" "https://api.avtovincod.ru/by-history?vin=VF1RFB00X56123456"
# через 30 секунд и далее, пока status не станет done:
curl -H "Authorization: Bearer $TOKEN" "https://api.avtovincod.ru/by-history?task=3f2b9c1e-7a4d-4e8b-9c21-5d6e7f8a9b0c"

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

1. Заказ принят

{
  "success": 1,
  "status": "processing",
  "taskId": "3f2b9c1e-7a4d-4e8b-9c21-5d6e7f8a9b0c",
  "query": {
    "vin": "VF1RFB00X56123456"
  },
  "eta_sec": 60,
  "pollAfterSec": 30,
  "poll": "GET /by-history?task=3f2b9c1e-7a4d-4e8b-9c21-5d6e7f8a9b0c"
}

2. Опрос: ещё готовится

{
  "success": 1,
  "status": "processing",
  "taskId": "3f2b9c1e-7a4d-4e8b-9c21-5d6e7f8a9b0c",
  "query": {
    "vin": "VF1RFB00X56123456"
  },
  "eta_sec": 25,
  "pollAfterSec": 30,
  "poll": "GET /by-history?task=3f2b9c1e-7a4d-4e8b-9c21-5d6e7f8a9b0c",
  "note": "Отчёт получен, собираем все файлы."
}

3. Опрос: отчёт готов

{
  "success": 1,
  "status": "done",
  "found": 1,
  "taskId": "3f2b9c1e-7a4d-4e8b-9c21-5d6e7f8a9b0c",
  "query": {
    "vin": "VF1RFB00X56123456"
  },
  "report": {
    "code": "by_history",
    "title": "История авто в Беларуси",
    "vin": "VF1RFB00X56123456",
    "brand": "Renault",
    "created_at": "2026-11-01 12:14:05",
    "files": [
      {
        "type": "pdf",
        "name": "by_history_VF1RFB00X56123456.pdf",
        "size": 284113,
        "url": "https://api.avtovincod.ru/vv-file/Qm9kZXJfdGVzdF90b2tlbl8xMjM0NTY3"
      }
    ],
    "web_url": null,
    "text": null,
    "files_until": "2027-01-30"
  },
  "billing": {
    "charged": 389,
    "currency": "RUB",
    "billed": true,
    "balance": 1611,
    "requestId": 1234567
  }
}

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

Файлы. Ссылки https://api.avtovincod.ru/vv-file/... открываются без токена (ссылка сама служит доступом, не публикуйте её), файл приходит с понятным именем by_history_VIN.pdf. Срок хранения - 90 дней (files_until), потом ссылка отвечает 410 FILE_GONE: сохраните файлы к себе. Параметр ?dl=1 - скачать, а не открыть в браузере. Документ оформлен источником отчёта, мы его не меняем.

Коды ошибок

Все ошибки бесплатны.

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

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

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

<?php
$url = 'https://api.avtovincod.ru/by-history?' . http_build_query(['vin' => 'X7TEST00000000001']);
$ch  = curl_init($url);
curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true, CURLOPT_TIMEOUT => 90,
    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/by-history", params={"vin": "X7TEST00000000001"},
                 headers={"Authorization": "Bearer " + os.environ["AVC_TOKEN"]}, timeout=90)
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/by-history?" + new URLSearchParams({ vin: "X7TEST00000000001" });
const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.AVC_TOKEN}` },
                               signal: AbortSignal.timeout(90000) });
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/by-history?"+q.Encode(), nil)
	req.Header.Set("Authorization", "Bearer "+os.Getenv("AVC_TOKEN"))
	resp, err := (&http.Client{Timeout: 90 * 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/by-history?" + q))
            .header("Authorization", "Bearer " + System.getenv("AVC_TOKEN"))
            .timeout(Duration.ofSeconds(90)).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(90) };
http.DefaultRequestHeaders.Authorization =
    new AuthenticationHeaderValue("Bearer", Environment.GetEnvironmentVariable("AVC_TOKEN"));
var url = "https://api.avtovincod.ru/by-history?" + "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/by-history")
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: 90) { |h| h.request(req) }
d = JSON.parse(res.body)
puts d["success"] == 1 ? d : "#{d["code"]}: #{d["error"]}"

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

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

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

Заказ и опрос готовности (Python)

import os, time, requests

URL = "https://api.avtovincod.ru/by-history"
H = {"Authorization": "Bearer " + os.environ["AVC_TOKEN"]}

while True:   # заказ; очередь проверки наличия данных занята (429 SERVICE_BUSY) - повторить через retryAfterSec
    d = requests.get(URL, params={"vin": "VF1RFB00X56123456"}, headers=H, timeout=90).json()
    if d.get("code") != "SERVICE_BUSY": break
    time.sleep(d.get("retryAfterSec", 10))
while d.get("success") == 1 and d.get("status") == "processing":
    time.sleep(max(10, d.get("pollAfterSec", 30)))
    d = requests.get(URL, params={"task": d["taskId"]}, headers=H, timeout=90).json()

if d.get("success") == 1:
    for f in d["report"]["files"]:
        open(f["name"], "wb").write(requests.get(f["url"], timeout=120).content)
    print("готово, списано", d.get("billing", {}).get("charged"))
else:
    print(d["code"], d["error"])

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

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

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

GET https://api.avtovincod.ru/by-history?task=3f2b9c1e-7a4d-4e8b-9c21-5d6e7f8a9b0c
Authorization: Bearer ВАШ_ТОКЕН

HTTP 200, status: "done": отчёт готов, одно списание по цене метода, сумма и остаток в блоке billing (цифры в примере условные). Ответ на заказ и опросы до готовности блока billing не содержат: они бесплатны.

{
  "success": 1,
  "status": "done",
  "found": 1,
  "taskId": "3f2b9c1e-7a4d-4e8b-9c21-5d6e7f8a9b0c",
  "query": {
    "vin": "VF1RFB00X56123456"
  },
  "report": {
    "code": "by_history",
    "title": "История авто в Беларуси",
    "vin": "VF1RFB00X56123456",
    "brand": "Renault",
    "created_at": "2026-11-01 12:14:05",
    "files": [
      {
        "type": "pdf",
        "name": "by_history_VF1RFB00X56123456.pdf",
        "size": 284113,
        "url": "https://api.avtovincod.ru/vv-file/Qm9kZXJfdGVzdF90b2tlbl8xMjM0NTY3"
      }
    ],
    "web_url": null,
    "text": null,
    "files_until": "2027-01-30"
  },
  "billing": {
    "charged": 389,
    "currency": "RUB",
    "billed": true,
    "balance": 1611,
    "requestId": 1234567
  }
}

Бесплатная проба без списания: https://api.avtovincod.ru/by-history?vin=X7TEST00000000001 сразу вернёт готовый отчёт-образец по этой же схеме с полем testMode: true и charged: 0; опрос ?task=TEST-TASK-0001 - тоже образец.

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

GET https://api.avtovincod.ru/by-history?vin=VF1RFB00X5612345
Authorization: Bearer ВАШ_ТОКЕН

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

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

Нет данных

GET https://api.avtovincod.ru/by-history?task=3f2b9c1e-7a4d-4e8b-9c21-5d6e7f8a9b0c
Authorization: Bearer ВАШ_ТОКЕН

Источник ответил, что по этому VIN данных нет: HTTP 200, status: "error", NOT_AVAILABLE. Бесплатно, блока billing нет.

{
  "success": 0,
  "status": "error",
  "taskId": "3f2b9c1e-7a4d-4e8b-9c21-5d6e7f8a9b0c",
  "query": {
    "vin": "VF1RFB00X56123456"
  },
  "error": "По этому VIN отчёт не сформирован: в источнике нет данных. Деньги не списаны.",
  "code": "NOT_AVAILABLE"
}

Тарификация

Заказ и опросы бесплатны. Списание одно - когда отчёт готов; повторный опрос готовой задачи не списывает. Нет данных (NOT_AVAILABLE), ошибки, отчёт не получен за 30 минут (PROVIDER_TIMEOUT) - бесплатно.

При заказе проверяется баланс с учётом отчётов, которые уже готовятся (их цена зарезервирована). Если к моменту готовности на балансе не хватает денег, опрос отвечает 402 INSUFFICIENT_BALANCE со status: "unpaid": пополните баланс и повторите опрос - отчёт будет выдан (ждёт 7 дней).

В ответ добавляется блок billing: сколько списано за этот запрос (charged, в рублях), платный ли он (billed), остаток баланса после запроса (balance) и номер в истории запросов (requestId). Те же данные в заголовках 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 - инструмент belarus_history (vin - заказ, task - опрос); всего инструментов 43.
• Цены и списания как у API, в результате тоже есть блок billing. Тестовые значения работают бесплатно.
• Инструкция по подключению: avtovincod.ru/docs/mcp/