POST /api/v1/document-check

Проверка документов

Метод принимает файл и запускает анализ документа. Результат забирается по job_id: статус, найденные условия, риск-факторы, PDF и доказательный блок.

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

Кратко для ИИ

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

Проверка ДКП, доверенности, согласия, выписки или комплекта сделки из внешней системы.

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

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

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

POST/api/v1/document-check

Загрузить документ и создать задачу анализа.

GET/api/v1/document-check/{job_id}

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

Сценарий

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

Шаг 1

Загрузка

Передайте файл через multipart/form-data и сохраните job_id.

Шаг 2

Обработка

Пока status=processing, показывайте пользователю, что анализ идёт.

Шаг 3

Готовый отчёт

При report_ready заберите result.analysis, pdf_url и доказательный блок.

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

Поле	Обяз.	Описание
file	Да	PDF/скан/документ в multipart form-data.
scenario	Нет	single_document, deal_context или иной поддержанный сценарий.
document_type_guess	Нет	Предполагаемый тип документа, если CRM его знает.

Пример curl

curl -X POST https://api.realiq.ru/api/v1/document-check \
  -H "X-API-KEY: riq_live_xxx" \
  -F "file=@contract.pdf" \
  -F "scenario=single_document"

JSON-запрос

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

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

{
  "content_type": "multipart/form-data",
  "form_data": {
    "file": "@contract.pdf",
    "scenario": "single_document",
    "document_type_guess": "Договор купли-продажи"
  }
}

JSON-ответ

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

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

{
  "job_id": "9b7928d8-e248-47ee-8df8-f43cccd97077",
  "status": "processing",
  "mode": "live",
  "cost": 240,
  "balance_remaining": 12410,
  "request_id": "req_1780000000_abcd"
}

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

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

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

{
  "job_id": "9b7928d8-e248-47ee-8df8-f43cccd97077",
  "status": "report_ready",
  "created_at": "2026-06-28T12:03:10Z",
  "completed_at": "2026-06-28T12:04:10Z",
  "result": {
    "analysis": {
      "document_type": "Договор купли-продажи",
      "risk_score": 24,
      "risk_level": "low",
      "short_conclusion": "Критичные противоречия не выявлены, отдельные условия требуют сверки с ЕГРН.",
      "found_clauses": [
        {
          "title": "Предмет договора",
          "status": "ok",
          "summary": "Кадастровый номер указан."
        },
        {
          "title": "Расчёты",
          "status": "attention",
          "summary": "Порядок передачи денег требует сверки с фактической схемой."
        }
      ],
      "recommendations": [
        "Сверить стороны, объект, цену и порядок расчётов перед подписанием."
      ]
    }
  },
  "pdf_url": "https://realiq.ru/reports/document-9b7928d8.pdf",
  "evidence": {
    "check_evidence_root_hash": "7c2d91...91af",
    "pdf_sha256": "5b9180...c010",
    "data_snapshot_sha256": "6f77aa...300d",
    "tsa": {
      "status": "not_configured",
      "provider": null,
      "token_sha256": null,
      "completed_at": null
    },
    "datestamp": {
      "value": "2026-06-28T12:04:10Z",
      "provider": "RealIQ",
      "created_at": "2026-06-28T12:04:10Z"
    },
    "verify_url": "https://realiq.ru/verify",
    "sources": []
  },
  "request_id": "req_1780000000_abcd"
}

Поля ответа

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

Поле	Что означает
job_id	ID анализа документа для опроса статуса.
result.analysis	Структурированный вывод по документу: тип, риск, условия, рекомендации.
pdf_url	PDF-отчёт по документу.
evidence	SHA исходного/итогового результата и метка времени анализа.

Ошибки

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

HTTP 400unsupported_document_format

Формат файла не поддерживается.

Что делать: Передайте PDF/изображение/поддержанный документ.

{
  "error_code": "unsupported_document_format",
  "message": "Формат файла не поддерживается.",
  "request_id": "req_1780000000_abcd"
}

HTTP 413document_too_large

Файл больше допустимого лимита.

Что делать: Сожмите файл или разделите комплект.

{
  "error_code": "document_too_large",
  "message": "Файл больше допустимого лимита.",
  "request_id": "req_1780000000_abcd"
}

HTTP 402insufficient_funds

Не хватает баланса.

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

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

Ответ processing

{
  "job_id": "...",
  "status": "processing",
  "mode": "live",
  "cost": 240,
  "balance_remaining": 12410,
  "request_id": "req_..."
}

Ответ report_ready

{
  "job_id": "...",
  "status": "report_ready",
  "created_at": "2026-06-28T12:03:10Z",
  "completed_at": "2026-06-28T12:04:10Z",
  "result": { "analysis": { "risk_score": 24 }, "extract": null, "report": null },
  "pdf_url": "https://realiq.ru/reports/...",
  "evidence": { "check_evidence_root_hash": "...", "pdf_sha256": "..." },
  "request_id": "req_..."
}

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

{
  "error_code": "unsupported_document_format",
  "message": "Формат файла не поддерживается.",
  "request_id": "req_..."
}

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

В боевом режиме списывается стоимость анализа документа. Ошибка валидации файла не должна списывать баланс.

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

document_sha256
pdf_sha256
check_evidence_root_hash
datestamp