POST /api/v1/document-generator

Генератор документов к сделке

Метод принимает структурированные данные сделки, запускает защищённый preflight и формирует комплект документов через тот же юридический конвейер, что и кабинет RealIQ. Состояние и ссылки на DOCX/PDF забираются по generation_id.

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

Метод RealIQPOST /api/v1/document-generator

Вход5 полей схемы→Обработкаstatus + request_id→Результат3 доказательных полей

Кратко для ИИ

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

Автоматическое формирование договора, передаточного акта и других документов сделки из CRM, банковского кабинета или внутренней системы агентства.

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

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

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

POST/api/v1/document-generator

Создать генерацию из структурированного draft и получить generation_id.

GET/api/v1/document-generator/{generation_id}

Получить этап, оплату, уровень качества и список готовых документов.

GET/api/v1/document-generator/{generation_id}/documents/{document_id}

Скачать файл с тем же X-API-KEY; формат задаётся query-параметром format=docx|pdf.

Сценарий

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

Шаг 1

Создание

Передайте draft, scope document-generator и уникальный Idempotency-Key.

Шаг 2

Preflight

RealIQ проверяет полноту и противоречия без списания; при успехе worker создаёт серверный quote и резерв.

Шаг 3

Формирование

Пока status=processing, опрашивайте GET по generation_id.

Шаг 4

Скачивание

При completed сохраните SHA и скачайте DOCX/PDF по защищённым API-ссылкам.

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

Поле	Обяз.	Описание
draft.scenario	Да	Сценарий сделки, например secondary_sale, pdkp_deposit, share_sale или residential_rental.
draft.sellers / draft.buyers	Нет	Стороны сделки и их реквизиты. Состав ролей зависит от сценария.
draft.objects	Нет	Объекты, адреса, кадастровые номера, площадь и иные известные параметры.
draft.price / draft.payments	Нет	Цена и порядок расчётов для возмездных сценариев.
allow_external_llm	Нет	Разрешает внешний preflight только после псевдонимизации и проверки защищённого хранилища ключей.

Пример curl

curl -X POST https://api.realiq.ru/api/v1/document-generator   -H "Content-Type: application/json"   -H "X-API-KEY: riq_live_xxx"   -H "Idempotency-Key: crm-document-kit-1001"   -d '{"draft":{"scenario":"secondary_sale","sellers":[{"full_name":"Иванов Иван Иванович"}],"buyers":[{"full_name":"Петров Пётр Петрович"}],"objects":[{"object_type":"apartment","address":"г. Москва, ул. Примерная, д. 1, кв. 10","cadastral_number":"77:01:0001001:1001","area":52.4}],"price":15000000,"deal_city":"Москва"},"allow_external_llm":true}'

JSON-запрос

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

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

{
  "draft": {
    "scenario": "secondary_sale",
    "sellers": [{ "full_name": "Иванов Иван Иванович" }],
    "buyers": [{ "full_name": "Петров Пётр Петрович" }],
    "objects": [{
      "object_type": "apartment",
      "address": "г. Москва, ул. Примерная, д. 1, кв. 10",
      "cadastral_number": "77:01:0001001:1001",
      "area": 52.4
    }],
    "price": 15000000,
    "deal_city": "Москва"
  },
  "allow_external_llm": true
}

JSON-ответ

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

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

{
  "generation_id": "d6e86af2-36f5-4c69-8f8a-4be27b97dc42",
  "status": "processing",
  "stage": "awaiting_confirmation",
  "mode": "live",
  "estimated_cost": 1090,
  "cost": 0,
  "payment_status": "pending",
  "balance_remaining": 12410,
  "quality_tier": null,
  "documents": [],
  "request_id": "req_1780000000_abcd"
}

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

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

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

{
  "generation_id": "d6e86af2-36f5-4c69-8f8a-4be27b97dc42",
  "status": "completed",
  "stage": "completed",
  "mode": "live",
  "estimated_cost": 1090,
  "cost": 1090,
  "payment_status": "settled",
  "balance_remaining": 11320,
  "quality_tier": "verified",
  "documents": [
    {
      "id": "9ceca243-f68d-40bc-a688-80a90f4fb8cf",
      "kind": "sale_contract",
      "title": "Договор купли-продажи",
      "docx_sha256": "d8545f...b207",
      "pdf_sha256": "88ea11...a294",
      "docx_url": "/api/v1/document-generator/d6e86af2-36f5-4c69-8f8a-4be27b97dc42/documents/9ceca243-f68d-40bc-a688-80a90f4fb8cf?format=docx",
      "pdf_url": "/api/v1/document-generator/d6e86af2-36f5-4c69-8f8a-4be27b97dc42/documents/9ceca243-f68d-40bc-a688-80a90f4fb8cf?format=pdf"
    }
  ],
  "created_at": "2026-08-30T10:00:00Z",
  "completed_at": "2026-08-30T10:01:40Z",
  "error": null,
  "request_id": "req_1780000000_abcd"
}

Поля ответа

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

Поле	Что означает
status / stage	status стабилен для интеграции; stage показывает текущий шаг preflight и генерации.
estimated_cost / cost / payment_status	До preflight доступна оценка; после server quote — фактический резерв и его состояние.
documents[]	Публичные ID, типы, SHA-256 и защищённые ссылки на DOCX/PDF.
quality_tier	verified, ai_assisted или incomplete_draft по результату штатной проверки качества.

Ошибки

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

HTTP 400idempotency_key_required

Live-запрос отправлен без Idempotency-Key.

Что делать: Создавайте стабильный ключ на одну операцию CRM.

{
  "error_code": "idempotency_key_required",
  "message": "Для live-запроса обязателен Idempotency-Key.",
  "request_id": "req_1780000000_abcd"
}

HTTP 403scope_denied

У ключа нет scope document-generator.

Что делать: Владелец должен выдать ключу доступ к генератору документов.

{
  "error_code": "scope_denied",
  "message": "API-ключ не разрешает метод document-generator.",
  "request_id": "req_1780000000_abcd"
}

HTTP 409generation_not_completed

Интеграция пытается скачать файл до финальной проверки комплекта.

Что делать: Продолжайте опрашивать GET статуса и скачивайте документы только после status=completed.

{
  "error_code": "generation_not_completed",
  "message": "Комплект ещё не прошёл финальную проверку и недоступен для скачивания.",
  "request_id": "req_1780000000_abcd"
}

HTTP 200generation_input_requires_attention

Preflight завершён, но обязательных данных недостаточно или найдены блокирующие противоречия.

Что делать: Исправьте draft и создайте новый запрос с новым Idempotency-Key; деньги не резервируются.

{
  "generation_id": "d6e86af2-36f5-4c69-8f8a-4be27b97dc42",
  "status": "action_required",
  "stage": "preflight_ready",
  "error": {
    "code": "generation_input_requires_attention",
    "message": "Комплект нельзя сформировать автоматически: проверьте обязательные данные и создайте новый запрос."
  },
  "request_id": "req_1780000000_abcd"
}

Ответ processing

{
  "generation_id": "d6e86af2-36f5-4c69-8f8a-4be27b97dc42",
  "status": "processing",
  "stage": "awaiting_confirmation",
  "mode": "live",
  "estimated_cost": 1090,
  "cost": 0,
  "payment_status": "pending",
  "balance_remaining": 12410,
  "quality_tier": null,
  "documents": [],
  "request_id": "req_..."
}

Ответ report_ready

{
  "generation_id": "d6e86af2-36f5-4c69-8f8a-4be27b97dc42",
  "status": "completed",
  "stage": "completed",
  "mode": "live",
  "estimated_cost": 1090,
  "cost": 1090,
  "payment_status": "settled",
  "balance_remaining": 11320,
  "quality_tier": "verified",
  "documents": [{
    "id": "9ceca243-f68d-40bc-a688-80a90f4fb8cf",
    "kind": "sale_contract",
    "title": "Договор купли-продажи",
    "docx_sha256": "...",
    "pdf_sha256": "...",
    "docx_url": "/api/v1/document-generator/d6e86af2-36f5-4c69-8f8a-4be27b97dc42/documents/9ceca243-f68d-40bc-a688-80a90f4fb8cf?format=docx",
    "pdf_url": "/api/v1/document-generator/d6e86af2-36f5-4c69-8f8a-4be27b97dc42/documents/9ceca243-f68d-40bc-a688-80a90f4fb8cf?format=pdf"
  }],
  "request_id": "req_..."
}

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

{
  "generation_id": "d6e86af2-36f5-4c69-8f8a-4be27b97dc42",
  "status": "action_required",
  "stage": "preflight_ready",
  "error": {
    "code": "generation_input_requires_attention",
    "message": "Комплект нельзя сформировать автоматически: проверьте обязательные данные и создайте новый запрос."
  },
  "request_id": "req_..."
}

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

POST сначала создаёт preflight без списания. После успешной проверки worker рассчитывает серверную цену и создаёт штатный резерв. При технической ошибке или недостаточном качестве резерв освобождается; sandbox ничего не списывает.

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

docx_sha256 и pdf_sha256 для каждого документа
уровень качества комплекта
серверные версии юридического каталога остаются внутри штатного конвейера