Главная → Документация → Сводный отчёт одним запросом
Сводный отчёт одним запросом
Метод /report собирает проверки одной машины за один запрос. Вы передаёте VIN, госномер или номер кузова и список блоков. Сервер сам строит порядок, находит недостающие номера, передаёт их блокам, которые их ждут, и отдаёт общий ответ с данными каждого блока.
Зачем это нужно
- Один запрос вместо десяти и больше. Не нужно самим вызывать методы по очереди, следить за таймаутами и повторами.
- Номера находятся сами. Передали госномер, а залоги ищутся по VIN: сервер определит VIN и запустит блок, когда номер появится.
- По каждому блоку видно, что с ним. Выполняется, ждёт номер (какой и от кого), пропущен (почему), завершился ошибкой.
- Отчёт настраивается. Свой список и порядок блоков, готовые наборы, сохранённые шаблоны, обязательные блоки, потолок суммы.
Быстрый старт
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 со сметой. |
fit | 1: при превышении потолка взять блоки по порядку, сколько помещается. Не вошедшие получат статус skipped с причиной COST_LIMIT. |
auto_resolve | 0: не добавлять блоки-определители номеров самим. По умолчанию 1. |
dry_run | 1: только план и смета. Ничего не запускается и не списывается. |
wait | Сколько секунд ждать готовности в этом запросе, от 0 до 110. По умолчанию 25. |
data | none: без данных блоков, только статусы. По умолчанию 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 и не мешает остальным. Номера в колонке «Ищет по» идут в порядке предпочтения.
| Код блока | Проверка | Ищет по | Находит для других |
|---|---|---|---|
gos2vin | VIN по госномеру | госномер | VIN, кузов, СТС |
vin2gos | Госномер по VIN | VIN | госномер, СТС |
gibdd | История регистрации | VIN, кузов | VIN, госномер, СТС, кузов |
decode | Расшифровка VIN | VIN | |
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 | Каршеринг: вторая проверка, по VIN | VIN | |
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.
Когда блок ждёт и когда пропускается
Главное правило: блок запускается, как только известен номер, по которому он умеет искать. Если номера нет, сервер смотрит, может ли его дать другой блок отчёта.
- Номер есть в запросе. Блок запускается сразу, статус
running. - Номера нет, но его может найти другой блок. Блок получает статус
waiting. В полеwaits_forназвано, какие номера он ждёт (identifiers), от каких блоков (from) и по какому номеру пойдёт, если не дождётся (fallback). В полеhintто же самое словами. - Определителя в списке нет. Сервер сам добавит блок
gos2vin(VIN по госномеру) илиvin2gos(госномер по VIN), если он вам подключён. Такой блок помечен"auto": trueи оплачивается как обычный запрос метода. Отключается параметромauto_resolve=0. - Номер найден. Он появляется в
identifiersс пометкой, какой блок его дал, а ждущие блоки запускаются сами. - Номер не найден. Если у блока есть запасной номер, он запускается по нему. Если нет, блок получает статус
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 такси и каршеринг проверяются до двух раз, как в разделе «Отчёт» личного кабинета.
- Такси. Блок
taxiищет по VIN. Если разрешений не найдено и известен госномер, запускаетсяtaxi_plate: тот же метод по госномеру. - Каршеринг. Блок
sharingищет по госномеру. Если не найдено и известен VIN, запускаетсяsharing_vin: тот же метод по VIN. - Вторая проверка не запускается и не списывается, если основной блок уже нашёл сведения или сам шёл по этому номеру: статус
skipped, причинаNOT_NEEDED. - Вторая проверка оплачивается как обычный запрос того же метода и приходит отдельным блоком. Смета считает оба запроса.
- В свой список вторые проверки добавляются явно:
blocks=taxi,taxi_plate,sharing,sharing_vin. Убрать из набора:exclude=taxi_plate,sharing_vin.
Статусы блока
| Статус | Что значит | Списание |
|---|---|---|
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 | Номер отчёта. По нему отчёт можно получить повторно. |
status | running, 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 ВАШ_ТОКЕН"
Получение результата
- В том же запросе. Сервер ждёт до
waitсекунд. Если отчёт успел, ответ200. - Опросом. При ответе
202запрашивайтеGET /report?id=rp_...&wait=25, покаstatusравенrunning. Запросы состояния бесплатны. Параметрblock=pledge,taxiоставит в ответе только нужные блоки. - Вебхуком. Подпишитесь в кабинете на событие
report.done: когда отчёт закончится, на ваш адрес придёт уведомление со статусами блоков, без данных. Данные забираются запросом поid.
Отменить отчёт: 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 ВАШ_ТОКЕН"
- Ответ
202:idотчёта иstatus: running. Соединение можно закрыть. - Когда проверка закончится, придёт событие
report.done. Данные заберите запросомGET /report?id=rp_...: ответ метода лежит вblocks[0].data. - Без вебхука работает опрос:
GET /report?id=rp_...&wait=25. - Списание то же, что при прямом вызове метода, и по тем же правилам.
Шаблоны
Шаблон хранит список блоков с настройками, потолок суммы и остальные параметры под коротким именем. Собрать шаблон можно в личном кабинете («Кабинет» → «Доступные 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.
Списания
- Сам метод
/reportбесплатный. Каждый блок оплачивается как прямой вызов своего метода, по вашей цене и по правилам этого метода. - Блоки со статусами
failed,skipped,cancelled,waitingне списываются. - Перед запуском сервер сверяет смету с балансом. Если баланса не хватает на весь отчёт, ответ
INSUFFICIENT_BALANCEсо сметой, ничего не запускается. Сfit=1иmax_costможно взять только то, что помещается. - Каждый блок виден в истории запросов кабинета отдельной строкой, его номер есть в
requestId. - Повторное получение отчёта по
idбесплатно.
Idempotency-Key: если ответ не дошёл и вы повторили запрос с тем же ключом, вернётся тот же отчёт. Новый не создаётся, блоки второй раз не запускаются и не списываются.Коды ошибок
| HTTP | code | Что значит |
|---|---|---|
| 400 | INPUT_REQUIRED | Номер машины не передан. |
| 400 | BAD_VIN, BAD_PLATE, BAD_BODY, BAD_QUERY, BAD_STS | Номер не прошёл проверку формата. |
| 400 | BAD_BLOCKS, BAD_PRESET, BAD_MAX_COST, BAD_JSON | Ошибка в параметрах, текст в error. |
| 400 | TEMPLATE_NOT_FOUND, BAD_TEMPLATE | Шаблона с таким именем нет, либо шаблон не удалось сохранить: причина в error. |
| 400 | NOTHING_TO_RUN | Ни один блок не может быть запущен. В ответе план с причинами по каждому блоку. |
| 400 | COST_LIMIT | Смета выше max_cost. В ответе план и смета. |
| 402 | INSUFFICIENT_BALANCE | Баланса не хватает на отчёт. В ответе план и смета. |
| 401 | NO_TOKEN, TOKEN_INVALID | Токен не передан или недействителен. |
| 403 | IP_NOT_ALLOWED, TOKEN_SCOPE | IP не в списке разрешённых, либо токену не разрешён метод report. |
| 403 | NOT_ALLOWED | Аккаунту не подключено ни одной проверки из отчёта. |
| 404 | REPORT_NOT_FOUND | Отчёта с таким id нет. |
| 405 | METHOD_NOT_ALLOWED | Отмена отчёта и удаление шаблона выполняются запросом POST. |
| 429 | REPORT_LIMIT, RATE_LIMIT | Слишком много отчётов одновременно или в минуту. Повторите позже. |
| 429 | SPEND_LIMIT_DAY, SPEND_LIMIT_MONTH | Достигнут лимит расхода, заданный в личном кабинете: новый отчёт не создаётся. У блока уже идущего отчёта тот же код приходит в blocks[].error, блок не списывается. |
| 503 | PROVIDER_FAIL | Отчёт временно недоступен. Повторите запрос. |
Ошибка отдельного блока не делает ошибочным весь отчёт: она лежит в blocks[].error, остальные блоки выполняются.
Вопросы и ответы
Сколько ждать отчёт?
Большинство блоков отвечает за секунды. Долгие проверки (ДТП по базе ГИБДД, история ОСАГО) могут идти несколько минут: возьмите набор quick или забирайте результат опросом либо вебхуком.
Что будет, если один блок упал?
Сервер повторит его сам. Если не получилось, блок получит статус failed без списания, остальные блоки отработают как обычно.
Можно ли запустить отчёт только по госномеру?
Да. Блоки по госномеру стартуют сразу, для остальных сервер сам определит VIN. Если VIN по госномеру не нашёлся, блоки по VIN будут пропущены без списания, а в ответе будет названа причина.
Как не заплатить больше, чем планировали?
Узнайте смету запросом с dry_run=1 и задайте max_cost. Сумма отчёта не превысит смету.
Собрать шаблон без кода
В личном кабинете есть конструктор: отметьте блоки, расставьте порядок, задайте потолок суммы и получите готовое имя шаблона для запроса.