POST /api/v1/valuation

Оценка объекта

Метод запускает оценку объекта по кадастровому номеру и доступным параметрам. POST сразу возвращает id, статус, стоимость и результат, если оценка сформирована синхронно; метод опроса возвращает полный доказательный блок.

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

Кратко для ИИ

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

Встроенная оценка ликвидности/стоимости объекта внутри CRM, личного кабинета банка или витрины агентства.

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

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

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

POST/api/v1/valuation

Создать задачу оценки объекта.

GET/api/v1/valuation/{valuation_id}

Получить статус, результат оценки, PDF и доказательный блок.

Сценарий

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

Шаг 1

Создание

Передайте кадастровый номер и дополнительные параметры объекта.

Шаг 2

Опрос статуса

Опрашивайте GET /valuation/{valuation_id}, пока задача не перейдёт в report_ready.

Шаг 3

Использование результата

Покажите диапазон цены, ликвидность, факторы и PDF-отчёт.

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

Поле	Обяз.	Описание
cadastral_number	Да	Кадастровый номер объекта.
address	Нет	Адрес для уточнения и отображения.
object_type	Нет	Квартира, помещение, дом, участок.

Пример curl

curl -X POST https://api.realiq.ru/api/v1/valuation \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: riq_live_xxx" \
  -d '{"cadastral_number":"78:40:0008480:3996"}'

JSON-запрос

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

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

{
  "cadastral_number": "78:40:0008480:3996",
  "address": "Санкт-Петербург, примерный адрес",
  "object_type": "apartment"
}

JSON-ответ

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

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

{
  "id": "1fd01d28-5a46-49c3-8511-122e96a5fce0",
  "status": "report_ready",
  "mode": "live",
  "result": {
    "valuation": {
      "price_range": {
        "min": 10000000,
        "max": 11200000,
        "currency": "RUB"
      },
      "liquidity": "normal",
      "comment": "Оценка рассчитана по доступным параметрам объекта и рыночным ориентирам."
    },
    "report": null
  },
  "pdf_url": "https://realiq.ru/reports/valuation-1fd01d28.pdf",
  "cost": 149,
  "balance_remaining": 12410,
  "request_id": "req_1780000000_abcd"
}

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

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

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

{
  "id": "val_1fd01d28",
  "status": "report_ready",
  "created_at": "2026-06-28T12:10:00Z",
  "completed_at": "2026-06-28T12:10:25Z",
  "result": {
    "valuation": {
      "cadastral_number": "78:40:0008480:3996",
      "object_type": "apartment",
      "price_range": {
        "min": 10000000,
        "max": 11200000,
        "currency": "RUB"
      },
      "estimated_price": 10600000,
      "liquidity": "normal",
      "confidence": 0.78,
      "factors": [
        {
          "title": "Локация",
          "effect": "positive",
          "comment": "Городская застройка с устойчивым спросом."
        },
        {
          "title": "Площадь и тип объекта",
          "effect": "neutral",
          "comment": "Параметры сопоставимы с рыночными объектами."
        }
      ],
      "comment": "Оценка рассчитана по доступным параметрам объекта и рыночным ориентирам."
    }
  },
  "pdf_url": "https://realiq.ru/reports/valuation-1fd01d28.pdf",
  "evidence": {
    "check_evidence_root_hash": "82aa31...11cf",
    "pdf_sha256": "de98a1...64bd",
    "data_snapshot_sha256": "76c8bb...1a52",
    "tsa": {
      "status": "not_configured",
      "provider": null,
      "token_sha256": null,
      "completed_at": null
    },
    "datestamp": {
      "value": "2026-06-28T12:10:25Z",
      "provider": "RealIQ",
      "created_at": "2026-06-28T12:10:25Z"
    },
    "verify_url": "https://realiq.ru/verify",
    "sources": []
  },
  "request_id": "req_1780000000_abcd"
}

Поля ответа

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

Поле	Что означает
id	ID задачи оценки.
result.valuation.price_range	Диапазон оценки объекта в рублях.
estimated_price	Ориентир внутри диапазона, если рассчитан.
liquidity/confidence	Ликвидность и уверенность расчёта.
factors[]	Факторы, которые объясняют оценку.
evidence	Цифровой след оценки и PDF.

Ошибки

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

HTTP 400invalid_check_input

Нет кадастрового номера или адреса.

Что делать: Передайте cadastral_number или достаточный адрес.

{
  "error_code": "invalid_check_input",
  "message": "Нет кадастрового номера или адреса.",
  "request_id": "req_1780000000_abcd"
}

HTTP 402insufficient_funds

Не хватает баланса на оценку.

Что делать: Пополните баланс.

{
  "error_code": "insufficient_funds",
  "message": "Не хватает баланса на оценку.",
  "request_id": "req_1780000000_abcd"
}

HTTP 429rate_limit_exceeded

Превышен лимит оценки.

Что делать: Повторите позже.

{
  "error_code": "rate_limit_exceeded",
  "message": "Превышен лимит оценки.",
  "request_id": "req_1780000000_abcd"
}

Ответ processing

{
  "id": "...",
  "status": "report_ready",
  "mode": "live",
  "result": { "valuation": { "price_range": { "min": 10000000, "max": 11200000 } } },
  "pdf_url": "https://realiq.ru/reports/...",
  "cost": 149,
  "balance_remaining": 12410,
  "request_id": "req_..."
}

Ответ report_ready

{
  "id": "...",
  "status": "report_ready",
  "created_at": "2026-06-28T12:10:00Z",
  "completed_at": "2026-06-28T12:10:25Z",
  "result": { "valuation": { "price_range": { "min": 10000000, "max": 11200000 } } },
  "pdf_url": "https://realiq.ru/reports/...",
  "evidence": { "check_evidence_root_hash": "..." },
  "request_id": "req_..."
}

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

{
  "error_code": "invalid_check_input",
  "message": "Укажите кадастровый номер.",
  "request_id": "req_..."
}

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

Списывается цена оценки по активному тарифу. Тестовый режим не списывает баланс.

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

valuation_snapshot_sha256
pdf_sha256
check_evidence_root_hash