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

Главная → Документация → Пакетная проверка по 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 со сметой.
fit1: если баланса не хватает на весь пакет, проверить столько машин, на сколько хватает. Остальные останутся в пакете отложенными.
dry_run1: только смета. Пакет не создаётся, ничего не списывается.

Поле 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}
      ]
    }
  ]
}
ПолеЗначение
statequeued, running, done: машина в очереди, проверяется, проверена. deferred: отложена (не хватило баланса). error: номер не распознан. duplicate: повтор. over_limit: сверх лимита пакета
levelобщий итог по машине и по каждой проверке: bad (найдено проблемное), warn (стоит посмотреть), ok (чисто), fail (не удалось проверить)
foundномера, которые сервер определил сам: VIN, госномер, марка и модель
checks[].statuswaiting, 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.

Списания и лимиты

Коды ошибок

HTTPcodeЧто значит
400BAD_ITEMS, NO_ITEMSСписок машин не передан или в нём нет ни одного распознанного номера. Причины по строкам в errors.
400BAD_CHECKSПроверки не переданы или недоступны аккаунту. Доступные коды в available.
400NOTHING_TO_RUNНи одну из выбранных проверок нельзя выполнить по этим номерам.
400COST_LIMIT, BAD_MAX_COSTСмета выше max_cost, либо max_cost задан неверно.
400BAD_JSON, BAD_ACTIONТело запроса не разобрано, либо для готового пакета передано неизвестное действие.
402INSUFFICIENT_BALANCEБаланса не хватает на весь пакет. В ответе смета и fit_cars.
401NO_TOKEN, TOKEN_INVALIDТокен не передан или недействителен.
403NOT_ALLOWED, IP_NOT_ALLOWED, TOKEN_SCOPEПакетная проверка не подключена аккаунту, IP не в списке разрешённых, либо токену не разрешён этот метод.
404BATCH_NOT_FOUNDПакета с таким id нет у вашего аккаунта.
409BATCH_ACTIVE, BUSYУже идёт другой пакет, либо пакеты аккаунта сейчас обновляются: повторите через несколько секунд.
429RATE_LIMIT, SPEND_LIMIT_DAY, SPEND_LIMIT_MONTHСлишком частые запросы к методу, либо достигнут лимит расхода. Повторите через Retry-After секунд.
503PROVIDER_FAIL, NOT_AVAILABLEМетод временно недоступен. Повторите запрос.

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

Сколько машин в одном пакете?

Лимит вашего аккаунта приходит в ответе GET /batch, поле limits.max_cars. Больший список разбейте на несколько пакетов и отправляйте их по очереди.

Сколько ждать пакет?

Зависит от числа машин и проверок. Быстрые проверки занимают секунды на машину, долгие могут идти минуты. Не держите соединение: используйте вебхук или опрос.

Чем пакет отличается от сводного отчёта?

Сводный отчёт: много проверок по одной машине, с передачей найденных номеров между блоками. Пакет: одни и те же проверки по списку машин.

Можно ли запустить пакет в кабинете, а результаты забрать по API?

Да. Номер пакета виден в адресе страницы пакета в кабинете, а пакеты аккаунта возвращает GET /batch.