holetron-lab/godcrm
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
godcrm/scripts/training_ru.md
GOD CRM Release f89e074dd1
Some checks failed
CI / Lint / Typecheck / Test / Build (push) Has been cancelled
Details
CI / PostgreSQL Integration Tests (push) Has been cancelled
Details
GOD CRM — public scrubbed snapshot 
Governed substrate for autonomous agents: scoped identity (passports),
audited actions, MCP workspace. Infra IPs and secrets redacted for public release.
2026-08-10 04:01:45 +03:00

58 KiB
Raw Permalink Blame History

Добро пожаловать в GOD CRM

GOD CRM -- это гибкая система управления данными, которая позволяет организовать информацию так, как удобно именно вам. Создавайте таблицы, настраивайте представления и автоматизируйте рутинные задачи.

Ключевые возможности

  • Таблицы -- Храните любые данные в структурированных таблицах с кастомными полями
  • Представления -- Смотрите на данные по-разному: таблица, канбан, календарь, галерея
  • Виджеты -- Создавайте дашборды с визуализацией данных из разных таблиц
  • Автоматизации -- Автоматизируйте действия при изменении данных

Быстрый старт

  1. Создайте пространство -- Пространство -- это контейнер для ваших проектов и таблиц. Например: "Работа", "Личное", "Стартап".
  2. Добавьте таблицу -- Таблица хранит ваши данные. Каждая запись -- это строка с набором полей (колонок).
  3. Настройте представление -- Выберите как отображать данные: таблица для детального просмотра, канбан для задач, календарь для событий.
  4. Добавьте виджеты на дашборд -- Выведите ключевые метрики и данные на дашборд пространства.

Пространства

Пространства -- это верхний уровень организации в GOD CRM. Используйте их для разделения разных областей работы или жизни.

Что такое пространство?

  • Проекты -- пространство содержит проекты, каждый со своим набором таблиц и настроек
  • Дашборд -- у каждого пространства есть дашборд с виджетами для быстрого обзора
  • Кастомизация -- название, иконка и цвет для быстрой визуальной идентификации

Примеры использования

Работа

  • CRM клиентов
  • Трекер задач
  • База знаний

Личное

  • Финансы
  • Привычки
  • Цели на год

Стартап

  • Roadmap
  • Инвесторы
  • Метрики

Обучение

  • Курсы
  • Книги
  • Заметки

Таблицы

Таблицы -- основа GOD CRM. Каждая запись в таблице -- это объект с набором свойств, которые вы определяете сами.

Создание таблицы

  1. Перейдите в проект и нажмите + Создать таблицу
  2. Укажите название, иконку и описание таблицы
  3. Добавьте колонки (поля) -- они определяют структуру данных
  4. Начните добавлять записи через кнопку + Добавить

Операции с записями

  • Добавить -- Создайте новую запись в таблице
  • Редактировать -- Двойной клик открывает карточку записи
  • Импорт -- Загрузите данные из CSV файла
  • Экспорт -- Выгрузите данные в CSV или Excel

Выделение и массовые операции

Построчное выделение

  • Чекбокс слева от каждой строки для выделения
  • Чекбокс в заголовке -- выделить/снять все видимые строки
  • Выделенные строки подсвечиваются цветом
  • Горячие клавиши: Shift+Click для диапазона, Ctrl+A для всех

Контейнер выделенных

Badge справа от кнопки "Фильтры" показывает количество выделенных строк. Клик открывает меню с действиями:

  • По умолчанию -- без сортировки
  • Выделенные сверху -- показать выделенные первыми
  • Выделенные снизу -- показать выделенные последними
  • Снять выделение -- очистить все
  • Выбрать все отфильтрованные -- выделить результаты фильтров

Массовая замена (Find & Replace)

Кнопка "Замена" справа от контейнера открывает модалку для массового изменения данных.

Применить к:

  • Выделенным строкам -- только отмеченные чекбоксами
  • Отфильтрованным строкам -- результаты текущих фильтров
  • Всем строкам -- вся таблица без ограничений

Типы операций:

  • Заменить значение -- Draft -> Active
  • Добавить (prefix/suffix) -- Hello -> Hello World
  • Очистить значение -- Text -> (пусто)
  • Применить формулу -- {name} - {code}

Дополнительно:

  • Поддержка регулярных выражений (regex)
  • Учет регистра (case sensitive)
  • Предпросмотр изменений перед применением
  • Отображение количества затронутых строк

Пример: найти "Draft" и заменить на "Active" в колонке Status для 5 выделенных строк.

Представления

Одни и те же данные можно отображать по-разному. Представления позволяют выбрать наиболее удобный формат для текущей задачи.

Типы представлений

Таблица

Классический табличный вид со всеми колонками. Идеален для детального просмотра и редактирования данных. Применение: CRM с контактами, Инвентарь, База данных

Канбан

Карточки, сгруппированные по колонкам статуса. Перетаскивайте карточки между колонками. Применение: Трекер задач, Процесс продаж, Найм сотрудников

Календарь

Записи отображаются на календаре по датам. Поддерживает события с длительностью. Применение: Встречи, Дедлайны, Контент-план

Таймлайн

Gantt-диаграмма с датами начала и окончания. Видна длительность и пересечения. Применение: Проекты, Roadmap, Планирование

Галерея

Карточки с превью изображений. Отлично для визуального контента. Применение: Портфолио, Каталог товаров, Мудборды

Чек-лист

Список задач с чекбоксами. Отмечайте выполненное, следите за прогрессом. Применение: To-do листы, Чек-листы, Привычки

График

Визуализация данных в виде графиков: столбчатые, линейные, круговые. Применение: Аналитика, Отчеты, Метрики

Типы колонок

Колонки определяют какие данные можно хранить в таблице. Выбирайте правильный тип для валидации и удобного редактирования.

Доступные типы

text -- Текст

Любой текст, заметки, описания.

Возможности:

  • Шаблон отображения с переменными: {{name}} ({{code}})
  • Префикс и суффикс для форматирования
  • Поддержка формул в значении по умолчанию
  • Перенос текста: одна строка, авто-перенос, ограниченный

Настройки:

  • formula -- Шаблон с переменными из других колонок
  • prefix -- Текст перед значением
  • suffix -- Текст после значения
  • defaultValue -- Значение по умолчанию для новых строк

Пример: Шаблон: {{first_name}} {{last_name}} -> Иван Иванов

number -- Число

Числа, суммы, количество.

Возможности:

  • Форматы: обычное число, валюта, процент (%)
  • Минимальное и максимальное значение
  • Шаг для кнопок +/- в ячейке
  • Количество знаков после запятой

Настройки:

  • format -- number | currency | percent
  • min / max -- Ограничения значений
  • step -- Шаг изменения (по умолчанию 1)
  • decimals -- Знаков после запятой (0-10)

Пример: Формат: currency, decimals: 2 -> 1 234,50 руб.

select -- Выбор (Select)

Одно значение из списка опций с цветами.

Возможности:

  • Список опций с цветовой кодировкой
  • Импорт опций из CSV или другой таблицы
  • Автоматический сбор опций из существующих данных
  • Поддержка relation для подгрузки из связанной таблицы

Настройки:

  • options -- Массив { id, label, color }
  • relation.tableId -- Таблица-источник опций
  • relation.valueColumn -- Колонка со значениями
  • relation.labelColumn -- Колонка с лейблами

Пример: Статус: Новый | В работе | Готово

multi-select -- Мульти-выбор (Multi-Select)

Несколько значений из списка (теги, категории).

Возможности:

  • Выбор нескольких значений из списка
  • Режим relation -- подгрузка опций из связанной таблицы
  • 4 формата отображения: badges, list, count, first
  • 4 формата хранения: json, comma, semicolon, newline

Настройки:

  • relation.tableId -- Таблица с опциями
  • relation.valueColumn -- Колонка со значениями (id)
  • relation.labelColumn -- Колонка с лейблами
  • relation.colorColumn -- Колонка с цветами (опционально)
  • relation.displayMode -- badges | list | count | first
  • relation.storageFormat -- json | comma | semicolon | newline

Пример: Теги: [React] [TypeScript] [Node.js] или "3 тега"

datetime -- Дата и время

Конкретная дата и время.

Возможности:

  • 3 формата хранения: ISO 8601, Unix (сек), Unix (мс)
  • Выбор часового пояса: UTC или браузерный
  • 11 форматов отображения
  • Поддержка NOW() для текущей даты

Настройки:

  • storageFormat -- ISO8601 | unix | unix_ms
  • timezone -- UTC | browser
  • displayFormat -- 25.12.2024 10:30, 25 декабря 2024, и др.

Пример: Хранение: 2024-12-25T10:30:00Z -> Показ: 25 декабря 2024, 13:30

time -- Время (Cron)

Расписание для cron-задач (HH:MM, день месяца).

Возможности:

  • Ввод времени в формате HH:MM
  • Выбор дня месяца для периодических задач
  • Интеграция с автоматизациями
  • Визуальный редактор расписания

Настройки:

  • format -- HH:MM | cron expression
  • dayOfMonth -- День месяца (1-31)
  • repeatType -- daily | weekly | monthly

Пример: 09:00 каждый день или 15:30 каждое 1-е число месяца

checkbox -- Чекбокс

Да/Нет, включено/выключено.

Возможности:

  • Настраиваемые значения для Да/Нет
  • 3 стиля: галочка, переключатель, да/нет
  • Значение по умолчанию

Настройки:

  • trueValue -- Значение для "Да" (1, true, yes...)
  • falseValue -- Значение для "Нет" (0, false, no...)
  • style -- checkbox | toggle | yesno

Пример: Стиль toggle: ВКЛ / ВЫКЛ

url -- URL (ссылка)

Ссылки на сайты и ресурсы.

Возможности:

  • Шаблон URL с переменными из других колонок
  • Настраиваемый текст ссылки
  • Открытие в новой вкладке
  • Превью ссылки

Настройки:

Пример: Шаблон: https://shop.com/products/{{slug}} -> Открыть товар

email -- Email

Электронная почта.

Возможности:

  • 4 формата отображения
  • Кнопка "Написать письмо"
  • Копирование по клику
  • Маскирование для конфиденциальности

Настройки:

  • displayFormat -- full | link | masked | domain

Пример: Masked: u***@e***.com, Domain: @example.com

phone -- Телефон

Номера телефонов.

Возможности:

  • 4 формата отображения
  • Автоформатирование по стране
  • Кнопки: позвонить, WhatsApp, Telegram
  • Маскирование для конфиденциальности

Настройки:

  • format -- full | national | international | masked
  • country -- ru | us | uk | de

Пример: +79001234567 -> 8 (900) 123-45-67 (RU) или +7 *** *--67

file -- Файл

Загрузка файлов.

Возможности:

  • Загрузка одного или нескольких файлов
  • Формула для вычисляемого пути
  • Префикс (домен) и суффикс (параметры)
  • Форматы: полный URL, имя файла, путь

Настройки:

  • formula -- Шаблон: {{folder}}/{{filename}}
  • prefix -- Например: https://cdn.site.com/
  • suffix -- Например: ?v=2

Пример: prefix + formula -> https://cdn.site.com/docs/report.pdf

image -- Изображение

Загрузка и отображение изображений.

Возможности:

  • 4 режима галереи: стек, карусель, сетка, одно фото
  • Настраиваемая высота (32-200px)
  • Форма: квадрат, скругленный, круг
  • Лайтбокс при клике

Настройки:

  • galleryMode -- stack | carousel | grid | single
  • height -- Высота в пикселях (32-200)
  • shape -- square | rounded | circle
  • fit -- cover | contain | fill

Пример: Режим stack: [фото][фото][фото] +3 фото

person -- Пользователь

Ссылка на пользователя системы.

Возможности:

  • 3 источника: системные пользователи, из таблицы, ручной ввод
  • 5 форматов отображения
  • Аватар и имя

Настройки:

  • source -- system | table | manual
  • displayFormat -- name | avatar | avatar_name | email | card

Пример: Иван Иванов или ivan@company.com

relation -- Связь (Relation)

Ссылка на запись из другой таблицы.

Возможности:

  • Выбор связанной таблицы
  • Настраиваемая колонка для отображения
  • Переход к связанной записи по клику
  • Множественная связь (многие-ко-многим)

Настройки:

  • linkedTableId -- ID связанной таблицы
  • displayColumn -- Колонка для отображения

Пример: Клиент: -> Иванов Иван (клик открывает карточку)

table -- Встроенная таблица

Отображает записи из другой таблицы, отфильтрованные по текущей строке.

Возможности:

  • Показывает связанные записи прямо в ячейке
  • Фильтрация по ключу текущей строки
  • Выбор колонок для отображения
  • Пагинация при большом количестве

Настройки:

  • sourceTableId -- Таблица-источник
  • filterColumn -- Колонка для фильтрации
  • displayColumns -- Колонки для отображения

Пример: Товар -> [Подтовары: Размер S | Размер M | Размер L]

rollup -- Сводка (Rollup)

Агрегация данных из связанной таблицы.

Возможности:

  • 10 функций агрегации
  • 4 формата вывода: число, валюта, процент, компактный
  • Автоматический пересчет при изменении данных

Настройки:

  • function -- sum | count | avg | min | max | percent | range | countAll | countValues | countUnique
  • format -- number | currency | percent | compact

Пример: Сумма заказов: 125 400 руб. или Кол-во: 47 шт.

vector -- Вектор (AI поиск)

Векторные эмбеддинги для семантического поиска.

Возможности:

  • AI-эмбеддинги для поиска по смыслу
  • Формула для составления текста
  • Интеграция с OpenAI text-embedding-ada-002
  • Хранение в PostgreSQL + pgvector

Настройки:

  • formula -- Шаблон: {{title}} {{description}}
  • prefix -- Контекст перед текстом
  • suffix -- Контекст после текста

Пример: Запрос: "синие джинсы" -> Найдено: "Брюки деним navy" (95%)

button -- Кнопка

Кнопка для действий.

Возможности:

  • 3 типа действий: открыть URL, webhook, автоматизация
  • Поддержка переменных в URL
  • 3 стиля: primary, secondary, danger

Настройки:

  • action -- url | webhook | automation
  • url -- URL с переменными: /edit/{{id}}
  • style -- primary | secondary | danger

Пример: [Редактировать] -> /admin/edit/{{id}}

audio -- Аудио

Аудио плеер для воспроизведения звуков.

Возможности:

  • Встроенный аудио плеер в ячейке
  • Поддержка URL на аудио файлы
  • Формула для вычисления пути
  • Префикс (домен CDN)

Настройки:

Пример: [0:00 / 3:45] -> воспроизведение из CDN

password -- Пароль

Зашифрованный текст.

Возможности:

  • Скрытое отображение: --------
  • Безопасное хранение
  • Кнопка показать/скрыть
  • Копирование в буфер

Настройки:

  • showButton -- Показывать кнопку "глазик"

Пример: Поле ввода: [--------]

formula -- Формула

Вычисляемое поле.

Возможности:

  • JavaScript выражения
  • Доступ к данным других колонок
  • Автопересчет при изменении
  • Форматирование результата

Настройки:

  • expression -- JS выражение: price * qty
  • format -- number | currency | percent

Пример: Итого: price * qty * (1 - discount/100) -> 8 500 руб.

dialog -- AI Диалог

AI диалог / переписка.

Возможности:

  • История переписки с AI
  • Контекст из текущей строки
  • Интеграция с AI агентами
  • Сохранение диалога в строке

Настройки:

  • agentId -- ID AI агента для диалога
  • contextColumns -- Колонки для контекста

Пример: Диалог с AI по карточке клиента

chat -- AI Чат

AI чат-разговор.

Возможности:

  • Полноценный чат с AI
  • История сообщений
  • Стриминг ответов
  • Поддержка разных моделей

Настройки:

  • model -- Модель: gpt-4, claude-3, etc.
  • systemPrompt -- Системный промпт

Пример: Чат с ИИ-ассистентом в ячейке

Векторная колонка (AI поиск)

Что такое векторная колонка?

Векторная колонка автоматически создает AI-эмбеддинги (векторные представления) из текстовых данных, что позволяет искать записи по смыслу, а не по точному совпадению слов.

Применение:

  • Поиск похожих товаров
  • Семантический поиск документов
  • Рекомендации контента
  • Дублирование записей

Технология:

  • OpenAI text-embedding-ada-002
  • Хранение в PostgreSQL + pgvector
  • Косинусное сходство для поиска
  • Автоматическая векторизация

Настройки векторной колонки

formula (необязательно) -- Формула для создания текста, который будет векторизован. Поддерживает переменные из других колонок.

{{title}} {{articul}}
{{description}}
Категория: {{category_id}}
Бренд: {{brand_id}}

prefix (необязательно) -- Текст, добавляемый перед формулой. Используется для контекста. Например: "Товар: "

suffix (необязательно) -- Текст, добавляемый после формулы. Например: " (в наличии)"

Пример: Поиск товаров

Пользователь ищет "синие джинсы мужские". Система найдет товары с похожим смыслом, даже если слова отличаются: "Брюки деним navy для мужчин".

Запрос: синие джинсы мужские -> Результат: Брюки деним navy (95% сходство)

Действия с колонками

Создание колонки

  1. Клик по кнопке + Добавить колонку в заголовке таблицы
  2. Выберите тип колонки из списка (text, number, select и т.д.)
  3. Укажите название и системное имя (автоматически генерируется из названия)
  4. Настройте параметры в зависимости от типа
  5. Нажмите Сохранить

Редактирование

Клик по иконке шестеренки в заголовке колонки или правая кнопка мыши -> Настройки

Удаление

Настройки колонки -> внизу кнопка "Удалить колонку". Данные будут потеряны!

Перемещение

Перетащите заголовок колонки влево/вправо для изменения порядка отображения

Скрытие/Показ

Правая кнопка на заголовке -> Скрыть колонку. Восстановить через меню "Скрытые колонки"

Дублирование

Настройки колонки -> Дублировать. Создает копию со всеми настройками

Изменение ширины

Перетащите границу между заголовками колонок или укажите точное значение в пикселях

Настройки отображения

Ширина колонки

Размер в пикселях (80-800px). Значения: Авто, 150px (по умолчанию), 200px, 300px...

Выравнивание текста

Горизонтальное выравнивание содержимого: Слева, По центру, Справа

Перенос текста

Поведение при переполнении ячейки:

  • nowrap -- Одна строка с обрезкой ...
  • wrap -- Автоматический перенос, высота по содержимому
  • ellipsis -- Ограниченный перенос (2-3 строки) + ...

Типографика

Размер шрифта (10-24px), жирный, курсив, моноширинный

Цвета

Цвет текста и цвет фона ячейки

Формулы и переменные

Что такое формулы?

Формулы позволяют автоматически вычислять значения на основе других колонок. Используйте переменные в фигурных скобках {{column_name}} для подстановки значений.

Пример:

{{first_name}} {{last_name}} ({{email}})

Результат: Иван Петров (ivan@example.com)

Синтаксис переменных

{{column_name}} -- Базовая подстановка значения из колонки

{{title}} - {{price}} руб.

{{value}} -- Текущее значение ячейки (для формул типа файл, вектор)

Префикс: https://cdn.example.com/
Формула: {{folder}}/{{value}}
Результат: https://cdn.example.com/images/photo.jpg

NOW() -- Специальная функция для текущей даты и времени

Значение по умолчанию: NOW()
Результат: 2025-12-13T23:45:00

Где можно использовать формулы

  • Текстовые колонки -- Шаблон отображения, префикс, суффикс
  • Файлы и изображения -- Формула пути, префикс URL
  • URL колонки -- Шаблон ссылки, текст ссылки
  • Векторные колонки -- Формула векторизации текста
  • Кнопки -- URL для перехода, webhook endpoint
  • Значения по умолчанию -- Для любого типа колонки

Практические примеры формул

  • Полное имя: {{first_name}} {{middle_name}} {{last_name}}
  • URL товара: https://shop.com/products/{{id}}/{{slug}}
  • Путь к файлу: {{year}}/{{month}}/{{category}}/{{filename}}
  • Описание для поиска: {{brand}} {{model}} {{color}} {{size}}

Важные замечания

  • Если колонка не существует, {{unknown}} будет выделена красным
  • Существующие колонки подсвечиваются {{name}} зеленым
  • Формулы пересчитываются автоматически при изменении исходных данных
  • В формулах учитывается регистр: {{Name}} != {{name}}

Настройки колонок

  • Название -- Отображаемое имя колонки
  • Тип -- Определяет формат данных
  • Обязательность -- Требовать заполнение
  • Значение по умолчанию -- Автоматически подставляется
  • Ширина -- Размер колонки в таблице
  • Видимость -- Скрыть/показать колонку

Фильтры и поиск

Фильтры помогают найти нужные записи в большом объеме данных. Комбинируйте условия для точного результата.

Поиск

Быстрый поиск по всем текстовым полям:

  • Введите текст в поле поиска -- результаты обновятся мгновенно
  • Поиск работает по названию и текстовым колонкам
  • Можно выбрать конкретные колонки для поиска

Типы фильтров

Фильтр по выбору

Показать записи с определенными значениями в колонке типа Select/Multiselect. Пример: Статус = 'В работе' ИЛИ 'На проверке'

Фильтр по дате

Показать записи в определенном диапазоне дат. Пример: Дедлайн: с 1 декабря по 31 декабря

Комбинированные фильтры

Несколько фильтров применяются одновременно (условие И). Пример: Статус = 'В работе' И Исполнитель = 'Иван'

Сортировка

Упорядочивание записей:

  • Клик по заголовку колонки -- сортировка по возрастанию
  • Повторный клик -- сортировка по убыванию
  • Работает для текста, чисел и дат

Виджеты и дашборды

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

Создание виджета

  1. Перейдите на дашборд пространства и нажмите + Добавить виджет
  2. Выберите тип представления (канбан, календарь, график и т.д.)
  3. Укажите таблицу-источник данных
  4. Настройте маппинг полей и фильтры в настройках виджета

Типы виджетов

  • Таблица
  • Канбан
  • Календарь
  • Таймлайн
  • График
  • Чек-лист

Управление дашбордом

  • Изменение размера -- перетащите угол виджета
  • Перемещение -- перетащите виджет за заголовок
  • Настройки -- нажмите шестеренку в углу виджета
  • Удаление -- через меню настроек виджета

Автоматизации

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

Триггеры (когда запускать)

  • Создание записи -- Когда в таблицу добавляется новая запись
  • Обновление записи -- Когда изменяется любое поле записи
  • Изменение поля -- Когда изменяется конкретное поле (например, статус)
  • Удаление записи -- Когда запись удаляется из таблицы

Действия (что делать)

  • Отправить уведомление -- Email или push-уведомление пользователю
  • Обновить запись -- Автоматически изменить поля записи
  • Создать запись -- Добавить новую запись в эту или другую таблицу
  • Вызвать Webhook -- Отправить HTTP-запрос на внешний сервис

Примеры автоматизаций

  • КОГДА Статус задачи -> 'Готово' ТОГДА Отправить уведомление автору задачи
  • КОГДА Создана новая заявка ТОГДА Назначить ответственного менеджера
  • КОГДА Дедлайн через 1 день ТОГДА Напомнить исполнителю

Webhooks

Интеграция с внешними сервисами.

Webhooks позволяют отправлять данные из CRM во внешние системы при определенных событиях.

  • Интеграция с Telegram ботами
  • Синхронизация с внешними CRM
  • Отправка данных в аналитические системы
  • Запуск процессов в n8n, Zapier, Make

REST API

GOD CRM предоставляет полнофункциональный REST API для интеграции с внешними системами. Все эндпоинты возвращают JSON и требуют аутентификации.

Аутентификация

API поддерживает два способа аутентификации: JWT токены и API ключи.

API Ключи (рекомендуется для интеграций)

Создайте API ключ в Настройках -> API Ключи. Ключ начинается с sk-

Использование через заголовок X-API-Key:

X-API-Key: sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Или через Authorization:

Authorization: Bearer sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

JWT Токены (для веб-приложений)

Получите токен через POST /api/v3/auth/login

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Базовый URL

https://crm.hltrn.cc/api/v3

Управление API ключами

GET /api-keys -- Получить список ваших API ключей

POST /api-keys -- Создать новый API ключ

Request Body:

{
  "name": "string",
  "scopes": ["*"],
  "expires_in_days": "number"
}

DELETE /api-keys/:id -- Удалить (отозвать) API ключ

Доступные права (scopes)

  • * -- полный доступ
  • tables:read
  • tables:write
  • rows:read
  • rows:write
  • widgets:read
  • widgets:write

Таблицы API

GET /tables -- Получить список всех таблиц

POST /tables -- Создать новую таблицу

Request Body:

{
  "name": "string",
  "space_id": "number",
  "emoji": "string"
}

GET /tables/:id -- Получить информацию о таблице

PATCH /tables/:id -- Обновить таблицу

Request Body:

{
  "name": "string",
  "emoji": "string"
}

DELETE /tables/:id -- Удалить таблицу

Колонки API

GET /tables/:tableId/columns -- Получить колонки таблицы

POST /tables/:tableId/columns -- Создать колонку

Request Body:

{
  "name": "string",
  "type": "text|number|select|datetime|...",
  "options": "object"
}

PATCH /columns/:id -- Обновить колонку

DELETE /columns/:id -- Удалить колонку

Типы колонок

text, number, select, multi_select, datetime, time, checkbox, url, email, phone, rating, file, image, relation, lookup, formula, rollup, json, vector

Записи API

GET /tables/:tableId/rows -- Получить записи таблицы Query: ?limit=50&offset=0&sort=column_id&order=asc

POST /tables/:tableId/rows -- Создать запись

Request Body:

{
  "values": {
    "column_id": "value"
  }
}

GET /rows/:id -- Получить запись по ID

PATCH /rows/:id -- Обновить запись

Request Body:

{
  "values": {
    "column_id": "new_value"
  }
}

DELETE /rows/:id -- Удалить запись

POST /tables/:tableId/rows/batch -- Массовое создание записей

Request Body:

{
  "rows": [
    { "values": {} },
    { "values": {} }
  ]
}

Представления API

GET /tables/:tableId/views -- Получить представления таблицы

POST /tables/:tableId/views -- Создать представление

Request Body:

{
  "name": "string",
  "type": "table|kanban|calendar|gallery",
  "config": "object"
}

PATCH /views/:id -- Обновить представление

DELETE /views/:id -- Удалить представление

Виджеты API

GET /dashboards/:dashboardId/widgets -- Получить виджеты дашборда

POST /dashboards/:dashboardId/widgets -- Создать виджет

Request Body:

{
  "type": "chart|stat|kanban|calendar|...",
  "config": "object",
  "position": { "x": 0, "y": 0, "w": 2, "h": 2 }
}

PATCH /widgets/:id -- Обновить виджет

DELETE /widgets/:id -- Удалить виджет

Типы виджетов

  • chart -- графики
  • stat -- статистика
  • kanban -- канбан-доска
  • calendar -- календарь
  • task_list -- список задач
  • table -- мини-таблица

Вебхуки API

GET /tables/:tableId/webhooks -- Получить вебхуки таблицы

POST /tables/:tableId/webhooks -- Создать вебхук

Request Body:

{
  "url": "string",
  "events": ["row.created", "row.updated", "row.deleted"],
  "secret": "string"
}

DELETE /webhooks/:id -- Удалить вебхук

События вебхуков

  • row.created -- создание записи
  • row.updated -- обновление записи
  • row.deleted -- удаление записи

Внешние источники API

GET /data-sources -- Получить список источников данных

POST /data-sources -- Создать внешний источник

Request Body:

{
  "name": "string",
  "type": "postgres|mysql|api",
  "connection": "object"
}

POST /data-sources/:id/sync -- Синхронизировать данные

DELETE /data-sources/:id -- Удалить источник

Vector API (Семантический поиск)

Что это?

Vector API позволяет создавать векторные эмбеддинги текста и искать похожие записи по смыслу, а не по точному совпадению слов. Использует OpenAI embeddings и PostgreSQL с расширением pgvector.

Параметр Значение
Модель text-embedding-ada-002
Размерность 1536 dimensions
Сходство Cosine similarity

POST /api/v3/ai/vector/embed -- Создать и сохранить эмбеддинг для текста

Request Body:

{
  "workspaceId": "number",
  "tableId": "number",
  "rowId": "number",
  "text": "string",
  "metadata": "object"
}

Пример запроса /embed:

{
  "workspaceId": 1,
  "tableId": 5,
  "rowId": 123,
  "text": "Смартфон Apple iPhone 15 Pro 256GB Blue Titanium",
  "metadata": {
    "category": "electronics",
    "price": 99999
  }
}

POST /api/v3/ai/vector/search -- Поиск похожих записей по тексту запроса

Request Body:

{
  "workspaceId": "number",
  "queryText": "string",
  "tableId": "number",
  "limit": "number (default: 10)",
  "metadataFilters": "object"
}

Пример запроса /search:

{
  "workspaceId": 1,
  "queryText": "телефон айфон синий",
  "tableId": 5,
  "limit": 5,
  "metadataFilters": {
    "category": "electronics"
  }
}

Пример ответа:

{
  "success": true,
  "results": [
    {
      "rowId": 123,
      "similarity": 0.94,
      "metadata": {
        "category": "electronics",
        "text_content": "Смартфон Apple iPhone 15 Pro 256GB Blue Titanium"
      }
    },
    {
      "rowId": 124,
      "similarity": 0.89,
      "metadata": {
        "text_content": "iPhone 15 Blue 128GB"
      }
    }
  ],
  "count": 2
}

POST /api/v3/ai/vector/batch -- Массовое создание эмбеддингов

Request Body:

{
  "workspaceId": "number",
  "items": [
    { "tableId": "number", "rowId": "number", "text": "string", "metadata": "object" }
  ]
}

POST /api/v3/ai/vector/generate-cell -- Создать эмбеддинг для векторной колонки с учетом формулы

Request Body:

{
  "tableId": "number",
  "rowId": "number",
  "columnId": "number"
}

Как работает /generate-cell

Этот эндпоинт читает настройки векторной колонки (formula, prefix, suffix), подставляет значения из других колонок строки, формирует итоговый текст и создает эмбеддинг.

  1. Формула колонки: Префикс: "Товар: " + Formula: {{title}} {{category}} + Суффикс: " в наличии"
  2. Данные строки: title: "iPhone 15", category: "Смартфоны"
  3. Итоговый текст: "Товар: iPhone 15 Смартфоны в наличии"
  4. Создание эмбеддинга через OpenAI API

GET /api/v3/ai/vector/stats/:workspaceId -- Получить статистику по эмбеддингам

Требования

  • OPENAI_API_KEY -- API ключ OpenAI в переменных окружения
  • PostgreSQL + pgvector -- база данных с расширением для векторов
  • База business_crm_vectors -- отдельная БД для хранения эмбеддингов

Примеры использования

Создание записи (cURL)

curl -X POST https://crm.hltrn.cc/api/tables/1/rows \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "values": {
      "name": "Новый клиент",
      "email": "client@example.com",
      "status": "new"
    }
  }'

JavaScript/Fetch

const response = await fetch('/api/tables/1/rows', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    values: {
      name: 'Новый клиент',
      email: 'client@example.com',
    }
  })
});

const newRow = await response.json();
console.log('Created row:', newRow.id);

Обработка ошибок

API возвращает стандартные HTTP коды и JSON с описанием ошибки:

Код Описание
200 OK -- успешно
201 Created -- создано
400 Bad Request -- ошибка запроса
401 Unauthorized -- не авторизован
404 Not Found -- не найдено
500 Server Error -- ошибка сервера

Формат ошибки:

{
  "error": true,
  "message": "Table not found",
  "code": "TABLE_NOT_FOUND"
}

AI Агенты

Интеллектуальные помощники, которые понимают ваши данные и помогают работать с ними. Агенты могут отвечать на вопросы, анализировать данные и выполнять задачи.

Что такое AI Агенты?

AI Агенты -- это настраиваемые AI-помощники на базе GPT-4, Claude или других моделей. Каждый агент имеет свою роль, знания и инструменты.

  • Персонализация -- Настройте системный промпт, модель и инструменты под свои задачи
  • Контекст данных -- Агент понимает структуру ваших таблиц и может работать с данными
  • Множество провайдеров -- OpenAI, Anthropic, Google, Ollama -- выбирайте подходящую модель
  • Мониторинг -- Отслеживание использования токенов, стоимости и качества ответов

Быстрый старт

  1. Создайте пространство "AI Agents" -- Или используйте существующее. В пространстве должны быть таблицы: Agents, Models, Providers, API Keys.
  2. Добавьте API ключ провайдера -- В таблицу API Keys добавьте ключ от OpenAI, Anthropic или другого провайдера.
  3. Создайте агента -- В таблице Agents создайте запись с именем, описанием, системным промптом и выбором модели.
  4. Начните диалог -- Нажмите на иконку чата в правом нижнем углу и выберите агента.

Настройка агента

  • name -- Имя агента для отображения в списке
  • description -- Краткое описание назначения агента
  • system_prompt -- Системный промпт, определяющий поведение и роль агента
  • model -- Связь с таблицей Models -- выбор AI модели
  • provider_id -- Связь с таблицей Providers -- выбор провайдера API
  • api_key_id -- Связь с таблицей API Keys -- ключ для авторизации
  • tools -- JSON массив доступных инструментов агента
  • is_active -- Checkbox -- активен ли агент для использования

AI агенты и векторный поиск

Семантический поиск данных

AI агенты могут использовать векторный поиск для интеллектуального анализа данных. Вместо точного совпадения слов, агент понимает смысл запроса и находит релевантные записи.

Пример 1: Поиск похожих товаров

Вопрос: "Найди товары похожие на iPhone 15"

Агент: Использует Vector API для поиска товаров с похожими характеристиками: смартфоны премиум-класса, большой экран, хорошая камера -> находит Samsung S24 Ultra, Google Pixel 8 Pro

Пример 2: Поиск документов по смыслу

Вопрос: "Где информация про работу с клиентами?"

Агент: Ищет документы семантически связанные с CRM, клиентским сервисом, продажами -> находит "CRM Руководство", "Обработка заявок", "Скрипты продаж"

Пример 3: Рекомендации

Вопрос: "Что еще может понравиться клиенту, который купил ноутбук для дизайна?"

Агент: Анализирует покупку через векторный поиск -> рекомендует графический планшет, внешний монитор 4K, мышь для дизайнеров, подписку Adobe Creative Cloud

Как включить векторный поиск для агента

  1. Создайте векторную колонку в нужной таблице
  2. Настройте формулу векторизации (какие поля включать)
  3. Добавьте инструмент vector_search агенту
  4. В системном промпте укажите, когда использовать векторный поиск

Поддерживаемые провайдеры

  • OpenAI -- GPT-4, GPT-4 Turbo, GPT-3.5
  • Anthropic -- Claude 3.5, Claude 3 Opus
  • Google -- Gemini 1.5 Pro, Gemini Flash
  • Ollama -- Llama 3.2, Mistral, CodeLlama

Логи сообщений

Все взаимодействия с агентами автоматически логируются в таблицу "Message Logs":

  • agent_name
  • user_id
  • model
  • message
  • response
  • tokens_in/out
  • status
  • timestamp

Советы

  • Системный промпт -- Четко определите роль агента. Например: "Ты аналитик продаж. Отвечай кратко и по делу."
  • Выбор модели -- GPT-4 Turbo для сложных задач, GPT-3.5 для простых -- экономьте токены разумно.
  • Переменные в промптах -- Используйте шаблоны вида {{table.column}} для динамической подстановки данных из таблиц.

AI Agents API

API для работы с AI-агентами, провайдерами и моделями. Позволяет управлять искусственным интеллектом в вашем рабочем пространстве.

Обзор возможностей

  • AI Агенты -- Создание и управление интеллектуальными помощниками
  • Чат с агентами -- Отправка сообщений и получение ответов от AI
  • Провайдеры -- OpenAI, Anthropic, Google, Ollama
  • Модели -- GPT-4, Claude, Gemini и другие

Базовый URL

https://crm.hltrn.cc/api/v3/ai

Агенты

GET /ai/agents -- Получить список всех агентов

GET /ai/agents/:spaceId -- Получить агентов для конкретного пространства

POST /ai/agents -- Создать нового агента

Request Body:

{
  "name": "string",
  "description": "string",
  "model": "gpt-4-turbo",
  "provider": "openai",
  "system_prompt": "string",
  "tools": ["string"]
}

PATCH /ai/agents/:id -- Обновить агента

Request Body:

{
  "name": "string",
  "model": "string",
  "system_prompt": "string"
}

DELETE /ai/agents/:id -- Удалить агента

Чат с агентом

POST /ai/chat -- Отправить сообщение агенту и получить ответ

Request Body:

{
  "agentId": "number",
  "message": "string",
  "conversationId": "string",
  "context": "object"
}

Пример ответа:

{
  "success": true,
  "response": "Привет! Я готов помочь вам с задачами...",
  "conversationId": "conv_abc123",
  "model": "gpt-4-turbo",
  "usage": {
    "promptTokens": 150,
    "completionTokens": 85,
    "totalTokens": 235
  }
}

GET /ai/conversations/:conversationId -- Получить историю диалога

DELETE /ai/conversations/:conversationId -- Удалить диалог

Провайдеры AI

GET /ai/providers -- Получить список провайдеров AI

Поддерживаемые провайдеры:

  • openai -- OpenAI (GPT-4, GPT-3.5)
  • anthropic -- Anthropic (Claude)
  • google -- Google (Gemini)
  • ollama -- Ollama (локальные модели)

POST /ai/providers -- Добавить провайдера

Request Body:

{
  "name": "string",
  "provider_key": "openai|anthropic|google|ollama",
  "base_url": "string",
  "is_active": true
}

PATCH /ai/providers/:id -- Обновить провайдера

DELETE /ai/providers/:id -- Удалить провайдера

Модели

GET /ai/models -- Получить список всех моделей

GET /ai/models?providerId=:id -- Получить модели конкретного провайдера

Популярные модели:

  • OpenAI: gpt-4-turbo, gpt-4o, gpt-3.5-turbo
  • Anthropic: claude-3-5-sonnet-20241022, claude-3-opus
  • Google: gemini-1.5-pro, gemini-1.5-flash
  • Ollama: llama3.2, mistral, codellama

POST /ai/models -- Добавить модель

Request Body:

{
  "provider_id": "number",
  "model_id": "gpt-4-turbo",
  "display_name": "GPT-4 Turbo",
  "context_window": 128000,
  "is_active": true
}

PATCH /ai/models/:id -- Обновить модель

DELETE /ai/models/:id -- Удалить модель

Обновление моделей

POST /ai/providers/:providerId/refresh-models -- Обновить список моделей от провайдера через API

Пример ответа:

{
  "success": true,
  "message": "Обновлено моделей: 17",
  "added": 12,
  "updated": 5,
  "models": [
    { "model_id": "gpt-4-turbo", "display_name": "GPT-4 Turbo" },
    { "model_id": "gpt-4o", "display_name": "GPT-4o" }
  ]
}

Важно: Для обновления моделей требуется настроенный API ключ провайдера в таблице API Keys. Поддерживается автоматическое обновление для OpenAI и Anthropic.

API Ключи для AI

API ключи провайдеров хранятся в таблице "API Keys" пространства "AI Agents".

Структура записи API Key:

{
  "provider": "openai",
  "key_name": "OpenAI API",
  "api_key": "sk-...",
  "is_active": true,
  "last_used": "2024-01-15"
}

Инструменты агентов

Агенты могут использовать инструменты для взаимодействия с CRM.

Инструмент Описание
get_workspace_info Получить информацию о пространствах, проектах и таблицах
query_table_data Выполнить запрос к данным таблицы
create_table Создать новую таблицу
create_row Добавить запись в таблицу
update_row Обновить запись в таблице
create_dashboard Создать дашборд
create_widget Добавить виджет на дашборд
search_records Поиск записей по критериям

Примеры использования

Отправить сообщение агенту (cURL)

curl -X POST https://crm.hltrn.cc/api/v3/ai/chat \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "agentId": 1,
    "message": "Покажи статистику продаж за этот месяц",
    "context": {
      "spaceId": 5,
      "tableId": 12
    }
  }'

JavaScript / Fetch

const response = await fetch('/api/v3/ai/chat', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    agentId: 1,
    message: 'Создай отчет по задачам',
    conversationId: 'conv_existing_id' // опционально
  })
});

const { response: aiResponse, usage } = await response.json();
console.log('AI ответил:', aiResponse);
console.log('Использовано токенов:', usage.totalTokens);

Обновить модели провайдера

// Получить свежий список моделей от OpenAI
const result = await fetch('/api/v3/ai/providers/1/refresh-models', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
});

const { added, updated, models } = await result.json();
console.log(`Добавлено: ${added}, обновлено: ${updated}`);

Обработка ошибок

Код Описание
400 Неверный запрос
401 Не авторизован
404 Агент не найден
500 Ошибка AI провайдера

Формат ошибки AI:

{
  "success": false,
  "error": "AI_PROVIDER_ERROR",
  "message": "OpenAI API rate limit exceeded",
  "details": {
    "provider": "openai",
    "model": "gpt-4-turbo"
  }
}