Личный кабинет

Главная → Документация → Сводный отчёт одним запросом

Сводный отчёт одним запросом

Метод /report собирает проверки одной машины за один запрос. Вы передаёте VIN, госномер или номер кузова и список блоков. Сервер сам строит порядок, находит недостающие номера, передаёт их блокам, которые их ждут, и отдаёт общий ответ с данными каждого блока.

Сам метод бесплатныйСписание только за выполненные блокиЗащита от повтора Idempotency-Key
Полная документация с примерами ответов, готовыми сценариями и кодом на PHP, Python и JavaScript скачивается в личном кабинете: «Кабинет» → «Доступные API» → «Сводный отчёт» → «Документация».

Зачем это нужно

Быстрый старт

curl -X POST "https://api.avtovincod.ru/report" \
  -H "Authorization: Bearer ВАШ_ТОКЕН" \
  -H "Idempotency-Key: order-12345" \
  -d "plate=А001АА77" \
  -d "blocks=gibdd,pledge,taxi,fines" \
  -d "max_cost=300" 

Ответ с кодом 200 значит, что отчёт закончен. Код 202 значит, что часть блоков ещё выполняется: в ответе уже есть готовые блоки, остальное забирается запросом GET /report?id=rp_....

Попробовать бесплатно можно на тестовых значениях: по VIN X7TEST00000000001 или госномеру Т000ТТ00 все блоки отвечают образцами без списания.

Параметры запроса

Параметры передаются в строке запроса, в форме или JSON-телом. Токен передаётся как у всех методов: Authorization: Bearer ....

ПараметрЧто значит
vin, plate, bodyНомер машины: обязателен хотя бы один. Если известно несколько номеров одной машины, передайте их все: блоки сразу возьмут нужный, и определять номер платным блоком не придётся. Можно передать query: сервер сам поймёт, VIN это, госномер или номер кузова.
stsНомер СТС, если он известен. Нужен штрафам: с ним блоки штрафов не ждут других блоков.
blocksСвой список блоков: коды через запятую или JSON-массив с настройками каждого блока. Порядок в списке задаёт порядок в ответе.
presetГотовый набор вместо списка: full, quick, vehicle, legal, history. Без blocks, preset и template берётся full.
excludeКакие блоки убрать из набора, коды через запятую.
templateИмя вашего шаблона. Параметры запроса главнее настроек шаблона.
save_templateСохранить настройки этого запроса шаблоном с таким именем. Пояснение передаётся в template_title.
max_costПотолок суммы за отчёт в рублях. Если смета выше, отчёт не запускается, ответ COST_LIMIT со сметой.
fit1: при превышении потолка взять блоки по порядку, сколько помещается. Не вошедшие получат статус skipped с причиной COST_LIMIT.
auto_resolve0: не добавлять блоки-определители номеров самим. По умолчанию 1.
dry_run1: только план и смета. Ничего не запускается и не списывается.
waitСколько секунд ждать готовности в этом запросе, от 0 до 110. По умолчанию 25.
datanone: без данных блоков, только статусы. По умолчанию full.

Настройки отдельного блока

Чтобы настроить блоки по отдельности, передайте blocks JSON-массивом:

{
  "plate": "А001АА77",
  "blocks": [
    {"code": "gibdd", "required": true},
    {"code": "osago", "by": "plate"},
    "pledge",
    "taxi"
  ],
  "max_cost": 300
}
НастройкаЧто значит
requiredОбязательный блок. Выполняется первым. Если он не дал результата (ошибка или пропуск), остальные блоки не запускаются и не списываются: они получают статус skipped с причиной REQUIRED_FAILED.
byИскать только по этому номеру: vin, plate, body или sts. Без настройки блок сам берёт лучший из доступных номеров.

Блоки и номера

В отчёт попадают только подключённые вам методы. Блок, который не подключён, получает статус skipped с причиной NOT_CONNECTED и не мешает остальным. Номера в колонке «Ищет по» идут в порядке предпочтения.

Код блокаПроверкаИщет поНаходит для других
gos2vinVIN по госномеругосномерVIN, кузов, СТС
vin2gosГосномер по VINVINгосномер, СТС
gibddИстория регистрацииVIN, кузовVIN, госномер, СТС, кузов
decodeРасшифровка VINVIN
pros_consПлюсы и минусы моделиVIN, кузов
scoreОграничения и розыскVIN, кузовVIN
accidentsПроверка ДТП (архив)VIN
accidents_rtДТП по базе ГИБДДVIN, кузов
europrotocolЕвропротоколVIN, госномер, кузов
hidden_damageСкрытые поврежденияVIN, кузов
pledgeРеестр залоговVIN, кузов
elptsЭлектронный ПТСVIN
probegТехосмотр и пробегVIN, кузов, госномер
taxiПроверка таксиVIN, госномер
taxi_plateТакси: вторая проверка, по госномеругосномер
osagoПолисы ОСАГОVIN, кузов, госномер
osago_historyИстория полисов ОСАГОVIN, кузов, госномер
nomerogramФотографии автомобилягосномер, VIN
sharingПроверка каршерингагосномер, VIN
sharing_vinКаршеринг: вторая проверка, по VINVIN
serviceСервисная историяVIN
lizingПроверка лизингаVIN
customsРастаможкаVIN
customs_ftsТаможня ФТСVIN, кузов
offersОбъявления о продажеVIN, госномер
recallsОтзывные кампанииVIN
priceРыночная оценкаVIN
lawsuitsСудебные делаVIN, госномер
invalid_regРеестр инвалидовгосномер
finesШтрафы ГИБДДСТС
fines_gisШтрафы ГИС ГМПСТС
briefКраткие данные ТСVIN, госномер
gibdd_archiveИстория регистрации из архиваVIN
autoparkНомер двигателяVIN, кузов
plate_historyИстория госномеровVIN, кузов
truck_passПропуска на МКАДгосномер
rnisРНИСгосномер

Готовые наборы

НаборНазначениеБлоки
fullПолный отчёт: все подключённые проверкивсе блоки полного отчёта
quickБыстрый: без долгих проверок (ДТП по базе ГИБДД, история ОСАГО)как full, кроме accidents_rt и osago_history
vehicleМашина и регистрацияgibdd, score, decode, pros_cons, customs, customs_fts, recalls, price, elpts
legalЮридическая чистотаgibdd, score, pledge, lizing, taxi, taxi_plate, sharing, sharing_vin, lawsuits, invalid_reg, fines, fines_gis
historyДТП, пробег и историяgibdd, accidents, accidents_rt, europrotocol, hidden_damage, probeg, service, offers, nomerogram, osago, osago_history

Список наборов, ваших шаблонов и доступных вам блоков отдаёт запрос GET /report?templates=1.

Когда блок ждёт и когда пропускается

Главное правило: блок запускается, как только известен номер, по которому он умеет искать. Если номера нет, сервер смотрит, может ли его дать другой блок отчёта.

  1. Номер есть в запросе. Блок запускается сразу, статус running.
  2. Номера нет, но его может найти другой блок. Блок получает статус waiting. В поле waits_for названо, какие номера он ждёт (identifiers), от каких блоков (from) и по какому номеру пойдёт, если не дождётся (fallback). В поле hint то же самое словами.
  3. Определителя в списке нет. Сервер сам добавит блок gos2vin (VIN по госномеру) или vin2gos (госномер по VIN), если он вам подключён. Такой блок помечен "auto": true и оплачивается как обычный запрос метода. Отключается параметром auto_resolve=0.
  4. Номер найден. Он появляется в identifiers с пометкой, какой блок его дал, а ждущие блоки запускаются сами.
  5. Номер не найден. Если у блока есть запасной номер, он запускается по нему. Если нет, блок получает статус skipped с причиной NO_IDENTIFIER: в needs названо, какого номера не хватило, в tried перечислены блоки, которые его не дали. Списания нет.

Пример ответа, пока определитель ещё работает:

{
  "code": "taxi",
  "name": "Такси",
  "status": "waiting",
  "waits_for": {"identifiers": ["vin"], "from": ["gos2vin"], "fallback": "plate"},
  "hint": "Ждёт VIN из блоков: «VIN по госномеру». Не получит - запустится по госномеру.",
  "charged": 0
}

Что от чего зависит

Вы передалиЧто происходит
ГосномерБлоки по госномеру стартуют сразу. Блоки по VIN ждут gos2vin или gibdd. Штрафы ждут номер СТС от тех же блоков.
VINБлоки по VIN стартуют сразу. Блоки только по госномеру (invalid_reg, truck_pass, rnis) ждут vin2gos или gibdd. Штрафы ждут номер СТС.
Номер кузоваСтартуют блоки, которые умеют искать по кузову. Остальные ждут VIN от gibdd или score.
Номер и stsШтрафы стартуют сразу, остальное как выше.
VIN, госномер и stsВсе блоки стартуют сразу, определитель не добавляется.

Блок customs_fts запускается после customs, если оба есть в отчёте: это видно в его waits_for. Определитель, добавленный сервером, не запускается, если его номер в итоге никому не нужен: он получает skipped с причиной NOT_NEEDED.

Такси и каршеринг: две проверки

В наборах full, quick и legal такси и каршеринг проверяются до двух раз, как в разделе «Отчёт» личного кабинета.

Статусы блока

СтатусЧто значитСписание
queuedВ очереди на запускнет
waitingЖдёт номер от другого блока, подробности в waits_forнет
runningВыполняетсянет
doneВыполнен, ответ метода в поле dataпо правилам метода
not_foundВыполнен, записей нет. Ответ метода в dataпо правилам метода
failedНе выполнен. Причина в error: код и текст ошибки методанет
skippedНе запускался. Причина в reason_code и reasonнет
cancelledОтчёт отменён до запуска блоканет

Причины пропуска

reason_codeЧто значит
NO_IDENTIFIERНет номера, по которому блок ищет. Поля needs и tried показывают, какого номера не хватило и кто его не дал.
NOT_CONNECTEDМетод вам не подключён.
UNKNOWN_BLOCKБлока с таким кодом нет.
BAD_BYВ настройке by указан номер, по которому блок не ищет.
COST_LIMITБлок не поместился в потолок суммы (при fit=1).
REQUIRED_FAILEDОбязательный блок не дал результата. Какой именно: поле because_of.
NOT_NEEDEDБлок не понадобился: номер уже известен, либо сведения уже нашёл основной блок.
CANCELLEDОтчёт отменён.

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

{
  "success": 1,
  "id": "rp_7996181dd42e328dce0d5608",
  "status": "done",
  "query": {"type": "plate", "value": "А001АА77"},
  "identifiers": {
    "vin":   {"value": "XTA210990Y2696785", "source": "gos2vin"},
    "plate": {"value": "А001АА77", "source": "input"},
    "body":  null,
    "sts":   {"value": "9912345678", "source": "gos2vin"}
  },
  "progress": {"total": 4, "done": 3, "not_found": 1, "failed": 0, "skipped": 0,
               "cancelled": 0, "running": 0, "waiting": 0, "queued": 0},
  "cost": {"charged": 40, "estimate_max": 40, "limit": 300, "currency": "RUB"},
  "blocks": [
    {"code": "gos2vin", "name": "VIN по госномеру", "status": "done", "auto": true,
     "by": "plate", "charged": 10, "requestId": 301552, "ms": 3013, "data": {"success": 1}},
    {"code": "pledge", "name": "Залоги", "status": "not_found",
     "by": "vin", "charged": 10, "requestId": 301554, "ms": 417, "data": {"success": 1, "found": 0}}
  ],
  "created_at": "2026-11-10T12:22:54+03:00",
  "finished_at": "2026-11-10T12:22:57+03:00"
}
ПолеЧто значит
idНомер отчёта. По нему отчёт можно получить повторно.
statusrunning, done или cancelled. Статус done значит, что все блоки пришли к итогу, в том числе с ошибкой или пропуском: смотрите progress.
identifiersВсе известные номера машины. source: input (из запроса) или код блока, который нашёл номер.
template, presetКакой это отчёт: имя вашего шаблона либо имя готового набора. У отчёта по своему списку этих полей нет.
cost.chargedСколько списано за отчёт на эту минуту: сумма по блокам.
cost.estimate_maxСмета: сколько отчёт может стоить самое большее.
blocks[].dataОтвет метода в том же виде, что при прямом вызове. Формат описан в документации метода.
blocks[].requestIdНомер запроса блока в истории кабинета.
pollAfterSec, pollЕсть, пока отчёт выполняется: через сколько секунд и каким запросом спросить снова.

Смета до запуска

Запрос с dry_run=1 возвращает план: какие блоки запустятся сразу ("run": "now"), какие будут ждать номер или обязательный блок ("run": "after"), какие не запустятся ("run": "never" с причиной), сколько отчёт может стоить и хватает ли баланса (cost.fits). Ничего не запускается и не списывается.

curl "https://api.avtovincod.ru/report?vin=XTA210990Y1234567&blocks=fines,pledge&dry_run=1" \
  -H "Authorization: Bearer ВАШ_ТОКЕН" 

Получение результата

Отменить отчёт: POST /report?id=rp_...&cancel=1. Блоки, которые ещё не начались, не запустятся. Уже запущенные доработают и будут оплачены по правилам метода.

Один долгий метод без ожидания

Так же можно запустить любую одну проверку, не дожидаясь ответа. Создайте отчёт из одного блока с wait=0: сервер сразу ответит 202 и номером отчёта, проверка выполнится на сервере, а о готовности сообщит вебхук report.done. Это удобно для долгих проверок (ДТП по базе ГИБДД, история ОСАГО, таможня ФТС): не нужно держать соединение и ловить таймаут на своей стороне.

curl -X POST "https://api.avtovincod.ru/report?vin=XTA210990Y1234567&blocks=accidents_rt&wait=0" \
  -H "Authorization: Bearer ВАШ_ТОКЕН" 

Шаблоны

Шаблон хранит список блоков с настройками, потолок суммы и остальные параметры под коротким именем. Собрать шаблон можно в личном кабинете («Кабинет» → «Доступные API» → «Сводный отчёт» → «Шаблоны и отчёты») или запросом:

curl -X POST "https://api.avtovincod.ru/report" \
  -H "Authorization: Bearer ВАШ_ТОКЕН" -H "Content-Type: application/json" \
  -d '{"vin": "XTA210990Y1234567", "dry_run": 1,
       "blocks": [{"code": "gibdd", "required": true}, "pledge", "taxi"],
       "max_cost": 200, "save_template": "dealer_check", "template_title": "Проверка перед выкупом"}'

Дальше достаточно plate=А001АА77&template=dealer_check. Удалить шаблон: POST /report?delete_template=dealer_check.

Списания

Передавайте заголовок Idempotency-Key: если ответ не дошёл и вы повторили запрос с тем же ключом, вернётся тот же отчёт. Новый не создаётся, блоки второй раз не запускаются и не списываются.

Коды ошибок

HTTPcodeЧто значит
400INPUT_REQUIREDНомер машины не передан.
400BAD_VIN, BAD_PLATE, BAD_BODY, BAD_QUERY, BAD_STSНомер не прошёл проверку формата.
400BAD_BLOCKS, BAD_PRESET, BAD_MAX_COST, BAD_JSONОшибка в параметрах, текст в error.
400TEMPLATE_NOT_FOUND, BAD_TEMPLATEШаблона с таким именем нет, либо шаблон не удалось сохранить: причина в error.
400NOTHING_TO_RUNНи один блок не может быть запущен. В ответе план с причинами по каждому блоку.
400COST_LIMITСмета выше max_cost. В ответе план и смета.
402INSUFFICIENT_BALANCEБаланса не хватает на отчёт. В ответе план и смета.
401NO_TOKEN, TOKEN_INVALIDТокен не передан или недействителен.
403IP_NOT_ALLOWED, TOKEN_SCOPEIP не в списке разрешённых, либо токену не разрешён метод report.
403NOT_ALLOWEDАккаунту не подключено ни одной проверки из отчёта.
404REPORT_NOT_FOUNDОтчёта с таким id нет.
405METHOD_NOT_ALLOWEDОтмена отчёта и удаление шаблона выполняются запросом POST.
429REPORT_LIMIT, RATE_LIMITСлишком много отчётов одновременно или в минуту. Повторите позже.
429SPEND_LIMIT_DAY, SPEND_LIMIT_MONTHДостигнут лимит расхода, заданный в личном кабинете: новый отчёт не создаётся. У блока уже идущего отчёта тот же код приходит в blocks[].error, блок не списывается.
503PROVIDER_FAILОтчёт временно недоступен. Повторите запрос.

Ошибка отдельного блока не делает ошибочным весь отчёт: она лежит в blocks[].error, остальные блоки выполняются.

Вопросы и ответы

Сколько ждать отчёт?

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

Что будет, если один блок упал?

Сервер повторит его сам. Если не получилось, блок получит статус failed без списания, остальные блоки отработают как обычно.

Можно ли запустить отчёт только по госномеру?

Да. Блоки по госномеру стартуют сразу, для остальных сервер сам определит VIN. Если VIN по госномеру не нашёлся, блоки по VIN будут пропущены без списания, а в ответе будет названа причина.

Как не заплатить больше, чем планировали?

Узнайте смету запросом с dry_run=1 и задайте max_cost. Сумма отчёта не превысит смету.

Собрать шаблон без кода

В личном кабинете есть конструктор: отметьте блоки, расставьте порядок, задайте потолок суммы и получите готовое имя шаблона для запроса.

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