Главная → Документация → Пакетная проверка по API
Пакетная проверка по API
Метод /batch проверяет список машин одним запросом. Вы присылаете номера и коды проверок, получаете номер пакета и смету «не больше». Дальше работает сервер: держать соединение не нужно. О готовности сообщит вебхук batch.done, результаты забираются по номеру пакета. Тот же пакет виден в личном кабинете, раздел «Пакетная проверка».
Быстрый старт
curl -X POST "https://api.avtovincod.ru/batch" \
-H "Authorization: Bearer ВАШ_ТОКЕН" \
-H "Content-Type: application/json" \
-d '{
"name": "Парк, ноябрь",
"checks": ["pledge", "taxi"],
"items": [
"XTA210990Y1234567",
"А123ВС777",
{"vin": "Z94K241BBJR061674", "label": "Инв. 17"}
]
}'
Ответ 201: номер пакета, статус queued и смета. Затем дождитесь события batch.done или опрашивайте GET /batch?id=..., пока статус равен queued или running.
Создать пакет
POST https://api.avtovincod.ru/batch. Параметры в теле запроса: JSON или обычная форма.
| Параметр | Описание |
|---|---|
items | Список машин, обязателен. Массив: каждая машина задаётся строкой с номером (VIN, госномер или номер кузова определяются сами) либо объектом с полями vin, plate, body, sts, label. В форме можно передать текст: по одной машине в строке. |
checks | Коды проверок, обязателен: массив или строка через запятую. Коды те же, что у методов: pledge, taxi, gibdd, score и другие, подключённые вашему аккаунту. |
name | Название пакета, до 150 знаков. Видно в кабинете и в событии вебхука. |
max_cost | Потолок сметы в рублях. Если смета больше, пакет не создаётся: ответ COST_LIMIT со сметой. |
fit | 1: если баланса не хватает на весь пакет, проверить столько машин, на сколько хватает. Остальные останутся в пакете отложенными. |
dry_run | 1: только смета. Пакет не создаётся, ничего не списывается. |
Поле label у машины: ваша подпись (инвентарный номер, имя водителя). Она вернётся в результатах. Поле sts нужно проверкам, которые ищут по номеру СТС.
Если проверке нужен номер, которого в списке нет (например, VIN при известном госномере), сервер сначала определит его отдельной платной проверкой. Она попадёт в смету с признаком auto.
Ответ
{
"success": 1,
"id": 1842,
"name": "Парк, ноябрь",
"status": "queued",
"rows": {"total": 3, "started": 3, "done": 0, "deferred": 0},
"cost": {"charged": 0, "estimate_max": 96, "currency": "RUB"},
"checks": [{"code": "pledge", "name": "Залоги"}, {"code": "taxi", "name": "Такси"}],
"pollAfterSec": 15,
"input": {"received": 3, "accepted": 3, "duplicates": 0, "over_limit": 0, "errors": []},
"estimate": {
"max": 96, "currency": "RUB", "cars": 3,
"checks": [
{"code": "pledge", "name": "Залоги", "cars": 3, "sum": 45, "auto": false},
{"code": "taxi", "name": "Такси", "cars": 3, "sum": 36, "auto": false},
{"code": "gos2vin", "name": "VIN по госномеру", "cars": 1, "sum": 15, "auto": true}
],
"unavailable": []
}
}
Суммы в примере условные. estimate.max: больше этой суммы пакет не спишет. Фактически спишется меньше: оплачиваются только выполненные проверки, по правилам каждого метода.
| Поле | Значение |
|---|---|
input.received, accepted | сколько строк получено и сколько машин принято в пакет |
input.duplicates | повторы в списке: проверяются один раз |
input.over_limit | машины сверх лимита пакета: в пакет не вошли, отправьте их следующим пакетом |
input.errors | строки, в которых номер не распознан: номер строки, значение и причина |
estimate.unavailable | проверки, которые нельзя выполнить для части машин, с причиной |
Состояние и результаты
GET /batch?id=1842 возвращает состояние пакета. Запросы состояния бесплатны.
| Статус | Значение |
|---|---|
queued, running | пакет выполняется. Повторите запрос через pollAfterSec секунд |
paused | пакет на паузе, причина в pause_reason и pause_text. При нехватке баланса он продолжится сам после пополнения |
done | все проверки закончены |
stopped | пакет остановлен. Выполненные проверки остаются в результатах |
Результаты по машинам: добавьте rows=1. Строки приходят страницами: page и per_page (до 200).
GET /batch?id=1842&rows=1&page=1&per_page=100
{
"success": 1, "id": 1842, "status": "done",
"page": {"page": 1, "per_page": 100, "total": 3, "pages": 1},
"items": [
{
"row": 3, "state": "done", "level": "bad",
"input": {"vin": "Z94K241BBJR061674", "label": "Инв. 17"},
"checks": [
{"code": "pledge", "name": "Залоги", "status": "done", "level": "bad",
"summary": "в залоге", "charged": 15, "requestId": 1840233},
{"code": "taxi", "name": "Такси", "status": "done", "level": "ok",
"summary": "нет", "charged": 12, "requestId": 1840234}
]
}
]
}
| Поле | Значение |
|---|---|
state | queued, running, done: машина в очереди, проверяется, проверена. deferred: отложена (не хватило баланса). error: номер не распознан. duplicate: повтор. over_limit: сверх лимита пакета |
level | общий итог по машине и по каждой проверке: bad (найдено проблемное), warn (стоит посмотреть), ok (чисто), fail (не удалось проверить) |
found | номера, которые сервер определил сам: VIN, госномер, марка и модель |
checks[].status | waiting, queued, running, done, failed, skipped, cancelled |
checks[].summary | короткий итог проверки словами |
checks[].charged, requestId | сколько списано за проверку и её номер в истории запросов |
checks[].error | код и текст ошибки, если проверка не выполнена. Такая проверка не списывается |
Полный ответ метода по каждой проверке: добавьте data=full. Тогда в checks[].data придёт тот же ответ, что при прямом вызове метода. С data=full страница не больше 20 строк; одну машину удобно запросить параметром row:
GET /batch?id=1842&row=3&data=full
Список последних пакетов: GET /batch без параметров. В ответе также лимиты аккаунта: сколько машин в одном пакете и сколько пакетов может идти одновременно.
Остановить пакет
POST /batch?id=1842&stop=1
Проверки, которые ещё не начались, отменяются и не списываются. Те, что уже выполняются, дорабатывают и оплачиваются по правилам метода.
Вебхук о готовности
В личном кабинете, раздел «Вебхук», укажите адрес своей системы и отметьте событие «Пакетная проверка готова» (batch.done). Событие придёт, когда пакет закончится. Подпись и повторы доставки такие же, как у остальных событий. Результаты заберите запросом GET /batch?id=...&rows=1.
Списания и лимиты
- Сам метод
/batchбесплатный. Списывают проверки пакета: по вашим ценам и по правилам каждого метода, как при прямом вызове. - Если баланса не хватает на весь пакет, ответ
402со сметой и числом машин, на которые хватает (fit_cars). С параметромfit=1пакет запустится для этих машин. - Расход пакета, созданного по API, входит в лимит расхода. При достигнутом лимите новый пакет не создаётся, а идущий ждёт: проверки продолжатся после сброса или увеличения лимита.
- Повтор создания после обрыва связи защищайте заголовком Idempotency-Key: второй пакет не создастся.
- Дополнительному токену метод разрешается отметкой «Пакетная проверка по API».
Коды ошибок
| HTTP | code | Что значит |
|---|---|---|
| 400 | BAD_ITEMS, NO_ITEMS | Список машин не передан или в нём нет ни одного распознанного номера. Причины по строкам в errors. |
| 400 | BAD_CHECKS | Проверки не переданы или недоступны аккаунту. Доступные коды в available. |
| 400 | NOTHING_TO_RUN | Ни одну из выбранных проверок нельзя выполнить по этим номерам. |
| 400 | COST_LIMIT, BAD_MAX_COST | Смета выше max_cost, либо max_cost задан неверно. |
| 400 | BAD_JSON, BAD_ACTION | Тело запроса не разобрано, либо для готового пакета передано неизвестное действие. |
| 402 | INSUFFICIENT_BALANCE | Баланса не хватает на весь пакет. В ответе смета и fit_cars. |
| 401 | NO_TOKEN, TOKEN_INVALID | Токен не передан или недействителен. |
| 403 | NOT_ALLOWED, IP_NOT_ALLOWED, TOKEN_SCOPE | Пакетная проверка не подключена аккаунту, IP не в списке разрешённых, либо токену не разрешён этот метод. |
| 404 | BATCH_NOT_FOUND | Пакета с таким id нет у вашего аккаунта. |
| 409 | BATCH_ACTIVE, BUSY | Уже идёт другой пакет, либо пакеты аккаунта сейчас обновляются: повторите через несколько секунд. |
| 429 | RATE_LIMIT, SPEND_LIMIT_DAY, SPEND_LIMIT_MONTH | Слишком частые запросы к методу, либо достигнут лимит расхода. Повторите через Retry-After секунд. |
| 503 | PROVIDER_FAIL, NOT_AVAILABLE | Метод временно недоступен. Повторите запрос. |
Вопросы и ответы
Сколько машин в одном пакете?
Лимит вашего аккаунта приходит в ответе GET /batch, поле limits.max_cars. Больший список разбейте на несколько пакетов и отправляйте их по очереди.
Сколько ждать пакет?
Зависит от числа машин и проверок. Быстрые проверки занимают секунды на машину, долгие могут идти минуты. Не держите соединение: используйте вебхук или опрос.
Чем пакет отличается от сводного отчёта?
Сводный отчёт: много проверок по одной машине, с передачей найденных номеров между блоками. Пакет: одни и те же проверки по списку машин.
Можно ли запустить пакет в кабинете, а результаты забрать по API?
Да. Номер пакета виден в адресе страницы пакета в кабинете, а пакеты аккаунта возвращает GET /batch.