API и интеграции

Генератор документов через API

API генератора нужен, когда CRM уже хранит стороны, объект, цену и условия сделки. Один POST создаёт асинхронную генерацию, а GET по generation_id показывает preflight, оплату, качество и готовые файлы.

Обновлено: 30.08.2026 · 8 минут

APIгенератор документовDOCXPDFсделкаидемпотентность
Инструкция8 минут
API и интеграцииГенератор документов через API
  1. 1Создайте API-ключ со scope document-generator. Для первого подключения используйте sandbox: он проверяет контракт ответа без LLM, файлов и списаний.
  2. 2Отправьте POST /api/v1/document-generator с draft.scenario и известными данными сторон, объекта, цены и расчётов. Для live обязательно передайте уникальный Idempotency-Key.
  3. 3Сохраните generation_id. Пока status=processing, опрашивайте GET /api/v1/document-generator/{generation_id}; повторный GET ничего не списывает.

Порядок действий

Что сделать

  1. Создайте API-ключ со scope document-generator. Для первого подключения используйте sandbox: он проверяет контракт ответа без LLM, файлов и списаний.
  2. Отправьте POST /api/v1/document-generator с draft.scenario и известными данными сторон, объекта, цены и расчётов. Для live обязательно передайте уникальный Idempotency-Key.
  3. Сохраните generation_id. Пока status=processing, опрашивайте GET /api/v1/document-generator/{generation_id}; повторный GET ничего не списывает.
  4. Если status=action_required, прочитайте error.code. Исправьте данные или пополните баланс и создайте новый запрос с новым Idempotency-Key.
  5. При status=completed скачайте DOCX/PDF по ссылкам documents[].docx_url и documents[].pdf_url, передавая тот же X-API-KEY, и сохраните SHA-256 файлов.

На что обратить внимание

Практические замечания

  • POST не списывает деньги до завершения preflight. После успешной проверки worker создаёт серверный quote и штатный резерв; при техническом срыве или недостаточном качестве резерв освобождается.
  • Idempotency-Key защищает от дубля проекта и повторного финансового действия. Один и тот же ключ с другим телом вернёт idempotency_conflict.
  • allow_external_llm=true разрешает внешний preflight только после псевдонимизации и проверки защищённого хранилища ключей. Исходные персональные данные не должны попадать в журналы интеграции.
  • Ссылки на файлы не публичные: скачать документ может только тот API-ключ, которым создана генерация.
  • Полный контракт draft и список сценариев смотрите в OpenAPI: https://api.realiq.ru/api/v1/openapi.json.