Документация

Витрима — ИИ-инструмент для команды студии

Витрима — облачная платформа для архитектурных бюро и студий интерьера. Подключите инструмент на сайт, авторизуйте сотрудников и ведите проекты: опросный лист, визуализации, ТЗ и бюджет. Этот раздел — гид по установке, программному интерфейсу, фирменному стилю и безопасности.

Если вы только что зарегистрировались — начните с раздела Установка на сайт. Если интересен прямой доступ к данным сессий — смотрите Программный интерфейс.

Установка на сайт

Самый простой способ — одна строка подключения в шапке страницы студии. Инструмент смонтируется автоматически; авторизованный сотрудник получает доступ к режиму студии.

<script
  src="https://app.vitrima.pro/widget-loader.js"
  data-vitrima-key="vit_••••••••"
  data-vitrima-host="https://app.vitrima.pro"
  defer
></script>

Где взять ключ? В кабинете на странице «Обзор».
Куда вставлять? В блок <head> или перед закрытием </body>.
Сколько весит? Загрузчик около 12 КБ; сам чат подгружается отложенной загрузкой во встроенное окно только после первого открытия.

Альтернатива: встроенное окно вручную

Если вы хотите контролировать положение виджета или сделать его на странице — используйте встроенное окно напрямую.

<iframe
  src="https://app.vitrima.pro/widget?apiKey=vit_••••••••"
  style="width:380px;height:560px;border:0;border-radius:20px;"
  loading="lazy"
              title="Витрима — чат ИИ"
></iframe>

В URL ?apiKey=… — это один из способов авторизации виджета. Для работы привязки к домену встройте через официальный код подключения выше или отдавайте страницу с родителем того же адреса (иначе сервер вернёт отказ). Сессии хранятся в памяти браузера вашего домена и автоматически продолжаются между визитами.

Фирменный стиль

Параметры фирменного стиля задаются на странице Кабинет → Фирменный стиль (тарифы Про и Студия):

Имя ассистента — отображается в шапке виджета.
Цвет акцента — кнопки, пузыри, фокус-рамки. HEX, например #7c6cf8.
Логотип — URL на прозрачный PNG / SVG, отрисуется в шапке (~32px высотой).
Тон голоса и системные инструкции для ИИ — добавляются к заданию модели. Опишите роль, ограничения, формат ответов.

Программный интерфейс

Все эндпоинты живут под /api/ai-brief/embed и требуют заголовков X-Api-Key (или Authorization: Bearer …) и X-Vitrima-Embed-Parent — origin сайта, где показывается виджет (например https://example.com). Первый успешный запрос привязывает ключ к этому домену.

GET /branding

Получить публичные параметры бренда: имя, цвет, логотип.

curl https://app.vitrima.pro/api/ai-brief/embed/branding \
  -H "X-Api-Key: vit_••••••••" \
  -H "X-Vitrima-Embed-Parent: https://example.com"

POST /sessions

Создать новую сессию диалога.

curl -X POST https://app.vitrima.pro/api/ai-brief/embed/sessions \
  -H "X-Api-Key: vit_••••••••" \
  -H "X-Vitrima-Embed-Parent: https://example.com" \
  -H "Content-Type: application/json" \
  -d '{}'

POST /sessions/:id/messages

Отправить сообщение от пользователя и получить ответ модели.

curl -X POST https://app.vitrima.pro/api/ai-brief/embed/sessions/SID/messages \
  -H "X-Api-Key: vit_••••••••" \
  -H "X-Vitrima-Embed-Parent: https://example.com" \
  -H "Content-Type: application/json" \
  -d '{"content":"Здравствуйте"}'

POST /sessions/:id/site-photo

Загрузить фото участка (multipart, поле image). Файл сохраняется в сессии и передаётся модели при каждом сообщении и при генерации фасада (если провайдер поддерживает референс).

curl -X POST https://app.vitrima.pro/api/ai-brief/embed/sessions/SID/site-photo \
  -H "X-Api-Key: vit_••••••••" \
  -H "X-Vitrima-Embed-Parent: https://example.com" \
  -F "image=@plot.jpg"

Удалить фото: DELETE /sessions/:id/site-photo с теми же заголовками.

POST /sessions/:id/confirm-concept-for-tz

Зафиксировать переход клиента к этапу ТЗ после выбора концепции (хотя бы одна визуализация уже есть). До этого запроса ответы модели не поднимают briefPhase выше концепции — можно безопасно уточнять фасад и перегенерировать изображение.

curl -X POST https://app.vitrima.pro/api/ai-brief/embed/sessions/SID/confirm-concept-for-tz \
  -H "X-Api-Key: vit_••••••••" \
  -H "X-Vitrima-Embed-Parent: https://example.com"

Уведомления на сервер

Чтобы получать события (новые лиды / сообщения) на свой сервер — задайте адрес уведомлений в Кабинете → Фирменный стиль и опционально секрет для подписи. Доступно на тарифах Про и Студия.

Витрима отправит POST-запрос с подписью:

POST https://your-crm/api/vitrima
X-Vitrima-Signature: sha256=<hmac(sha256, secret, body)>
Content-Type: application/json

{
  "type": "session.completed",
  "tenantId": "...",
  "session": { "_id": "...", "messages": [...] }
}

Проверяйте подпись перед обработкой — это защитит от подделки. Подпись рассчитывается по сырому телу запроса.

Безопасность ключа

Полный ключ показывается один раз при создании или перевыпуске. На сервере хранится только bcrypt-хеш.
Если потеряли ключ — нажмите «Перегенерировать» в кабинете. Старый перестанет работать сразу.
«Деактивировать» — мягкое отключение: tenant остаётся, но виджет перестаёт авторизоваться. Можно выпустить новый ключ когда нужно.
Ключ ходит по защищённому каналу. По возможности храните его на сервере и проксируйте запросы — для сайтов без серверной части используйте ?apiKey или атрибут в коде подключения, понимая, что любой посетитель сможет его увидеть.

Лимиты и тарифы

Тариф	Генераций / мес	На клиента	Лидов / мес (мин.)	Цена
Старт	50	3	16	5 900 ₽ / мес
Про	150	5	30	12 900 ₽ / мес
Студия	400	10	40	29 900 ₽ / мес
Внедрение	индивидуально	индивидуально	150 000 – 500 000 ₽ разово + от 49 000 ₽ / мес

Лимиты считаются в календарном месяце. При превышении виджет сообщает пользователю «лимит исчерпан» и продолжит работать после переключения тарифа в один клик. Сверх включённого пакета генераций — оплата по факту (30 ₽ за генерацию).

Поддержка

Telegram: @vitrimaru
Электронная почта: vitrima.pro@gmail.com

Не нашли ответ? Напишите нам — обычно отвечаем в течение нескольких часов в рабочее время.