POST /api/v1/checks/bulk

Пакетный запуск проверок

Пакетный метод создаёт несколько независимых проверок одним запросом. Частичный успех допустим: по каждому элементу возвращается свой результат или понятная ошибка.

Открыть в Swagger API в базе знаний

Кратко для ИИ

Когда использовать

Загрузка очереди проверок из CRM, импорт лидов или массовая проверка перед внутренним скорингом партнёра.

Карта методов

Связанные методы

Эта страница описывает группу связанных методов. Для точной схемы параметров используйте Swagger, для продуктовой логики — блоки ниже.

POST/api/v1/checks/bulk

Пакетно создать до 50 проверок.

GET/api/v1/checks/{check_id}

Забрать результат каждой созданной проверки.

POST/api/v1/checks/quote

Заранее посчитать стоимость пакета.

Сценарий

Как проходит сценарий

Шаг 1

Подготовка пакета

Соберите items[] и при необходимости сначала вызовите предрасчёт.

Шаг 2

Создание пакета

POST /checks/bulk вернёт success/error по каждому элементу.

Шаг 3

Частичный успех

Успешные check_id продолжайте опрашивать, ошибочные элементы исправьте отдельно.

Шаг 4

Сбор отчётов

Для каждого check_id заберите PDF/result/доказательный блок обычным методом опроса.

Обязательные поля

Поле	Обяз.	Описание
items[]	Да	Массив до 50 проверок.
items[].type	Да	Тип проверки: продавец, объект или комплексная проверка.
items[].input_data	Да	Данные продавца/объекта для конкретной проверки.

Пример curl

curl -X POST https://api.realiq.ru/api/v1/checks/bulk \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: riq_live_xxx" \
  -d '{"items":[{"type":"seller","input_data":{"seller":{"last_name":"Иванов"}}}]}'

JSON-запрос

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

Для GET-методов показано JSON-представление URL, query-параметров и заголовков. Для загрузки файла показана структура form-data.

{
  "items": [
    {
      "type": "seller",
      "input_data": {
        "seller": {
          "last_name": "Иванов",
          "first_name": "Иван",
          "birth_date": "1980-01-01",
          "region": "Москва"
        }
      }
    },
    {
      "type": "object",
      "input_data": {
        "object": {
          "cadastral_number": "78:40:0008480:3996"
        }
      }
    }
  ]
}

JSON-ответ

Пример успешного JSON-ответа

Пример отражает структуру реального ответа API. Значения ID, SHA и ссылок сокращены или заменены демонстрационными.

{
  "items": [
    {
      "index": 0,
      "success": true,
      "check_id": "b9f6f2f0-b8c1-4f1c-bb8f-3cf3a9dc3b5a",
      "status": "processing",
      "type": "seller",
      "mode": "live",
      "cost": 390,
      "price_amount": 390
    },
    {
      "index": 1,
      "success": true,
      "check_id": "1fd01d28-5a46-49c3-8511-122e96a5fce0",
      "status": "processing",
      "type": "object",
      "mode": "live",
      "cost": 290,
      "price_amount": 290
    }
  ],
  "created_count": 2,
  "failed_count": 0,
  "mode": "live",
  "total_cost": 680,
  "balance_remaining": 11730,
  "request_id": "req_1780000000_abcd"
}

Полный JSON-ответ

Полный пример ответа

Развёрнутый пример показывает, какие блоки обычно получает интегратор. Значения ID, SHA, ссылок и персональных данных демонстрационные.

{
  "items": [
    {
      "index": 0,
      "success": true,
      "check_id": "b9f6f2f0-b8c1-4f1c-bb8f-3cf3a9dc3b5a",
      "status": "processing",
      "type": "seller",
      "mode": "live",
      "cost": 390,
      "price_amount": 390
    },
    {
      "index": 1,
      "success": true,
      "check_id": "1fd01d28-5a46-49c3-8511-122e96a5fce0",
      "status": "processing",
      "type": "object",
      "mode": "live",
      "cost": 290,
      "price_amount": 290
    },
    {
      "index": 2,
      "success": false,
      "error_code": "invalid_check_input",
      "message": "Не указан кадастровый номер объекта."
    }
  ],
  "created_count": 2,
  "failed_count": 1,
  "mode": "live",
  "total_cost": 680,
  "balance_remaining": 11730,
  "request_id": "req_1780000000_abcd"
}

Поля ответа

Как читать поля ответа

Поле	Что означает
items[]	Результат по каждому входному элементу. Порядок совпадает с запросом.
success	true — проверка создана; false — по элементу есть ошибка, но остальные могли создаться.
created_count/failed_count	Итог пакетного запуска. Частичный успех считается нормальным ответом 200.
total_cost	Суммарное списание только за успешные боевые элементы.

Ошибки

Типовые ошибки метода

HTTP 400validation_error

items пустой или больше 50 элементов.

Что делать: Разбейте пакет на несколько запросов.

{
  "error_code": "validation_error",
  "message": "items пустой или больше 50 элементов.",
  "request_id": "req_1780000000_abcd"
}

HTTP 402insufficient_funds

Баланс не покрывает успешные элементы.

Что делать: Сначала сделайте quote или пополните баланс.

{
  "error_code": "insufficient_funds",
  "message": "Баланс не покрывает успешные элементы.",
  "request_id": "req_1780000000_abcd"
}

HTTP 429rate_limit_exceeded

Слишком частый пакетный запуск.

Что делать: Снизьте частоту и размер пакета.

{
  "error_code": "rate_limit_exceeded",
  "message": "Слишком частый bulk-запуск.",
  "request_id": "req_1780000000_abcd"
}

Ответ processing

{
  "items": [{ "success": true, "check_id": "...", "status": "processing", "cost": 390 }],
  "created_count": 1,
  "failed_count": 0,
  "request_id": "req_..."
}

Ответ report_ready

{
  "items": [
    { "success": true, "check_id": "...", "status": "processing" },
    { "success": false, "error_code": "validation_error", "message": "Не указан type" }
  ],
  "created_count": 1,
  "failed_count": 1
}

Пример ошибки

{
  "error_code": "validation_error",
  "message": "items должен содержать от 1 до 50 элементов.",
  "request_id": "req_..."
}

Что списывается с баланса

Списывается только за успешно созданные боевые проверки. Ошибочные элементы не списываются.

Какие поля доказательного блока вернутся

Доказательный блок появляется у каждой созданной проверки после её завершения.
Пакетный ответ содержит check_id для последующего опроса статуса.