Внешний API

Платформа предоставляет REST API для интеграции с внешними системами: сайтами, мобильными приложениями, чат-ботами, CRM и любыми другими сервисами. Через API можно создавать записи в документах и календарях — так же, как это делает пользователь вручную.

Как работает авторизация

Все запросы к API должны быть авторизованы. Есть два способа:

Способ 1 — API-токен (рекомендуется для интеграций)

Токен передаётся в заголовке каждого запроса:

Authorization: Bearer ваш_токен_здесь

Способ 2 — сессионная кука

Сначала выполняется вход через /api/auth/login, затем кука из ответа передаётся в последующих запросах. Подходит для скриптов и браузерных клиентов.

Где создать API-токен

Токены привязываются к конкретному пользователю и наследуют все его права. Чем меньше прав у пользователя — тем безопаснее токен.

Путь: Администрирование → Пользователи → открыть карточку пользователя → раздел «API-токены»

Там же можно:

Создать новый токен (нужно придумать название, например «Сайт» или «Бот»)
Видеть когда токен использовался последний раз
Отозвать токен — он немедленно перестанет работать

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

Свои токены может видеть и создавать сам пользователь (не только администратор).

API для документов

Документ — это запись с полями, табличными частями и статусами (черновик, активный, проведённый и т.д.).

Создать запись

POST /api/records/{id_сущности}
Authorization: Bearer ваш_токен
Content-Type: application/json
{
  "поле1": "значение1",
  "поле2": "значение2"
}

В URL указывается числовой id сущности (документа). Найти его можно в адресной строке при открытии настроек сущности, или на странице «Пример API запроса» в настройках уведомлений.

По умолчанию запись создаётся со статусом active. Чтобы создать черновик:

POST /api/records/{id_сущности}?status=draft

Пример запроса (заявка с сайта):

curl -X POST https://ваш-сайт.ru/api/records/5 \
  -H "Authorization: Bearer abcdef123456..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Иван Иванов",
    "phone": "+79001234567",
    "service": "Стрижка",
    "comment": "Хочу запись на вечер"
  }'

Ответ при успехе (HTTP 201):

{
  "id": 42,
  "status": "active",
  "data": {
    "name": "Иван Иванов",
    "phone": "+79001234567",
    "service": "Стрижка",
    "comment": "Хочу запись на вечер"
  }
}

Типы значений полей

Тип поля	Что передавать	Пример
Текст, многострочный	Строка	`"Иван Иванов"`
Число	Число	`1500`
Дата	Строка `ГГГГ-ММ-ДД`	`"2026-04-15"`
Дата и время	Строка `ГГГГ-ММ-ДД ЧЧ:ММ:СС`	`"2026-04-15 10:00:00"`
Телефон	Строка, любой формат	`"+79001234567"` или `"89001234567"`
Email	Строка	`"mail@example.com"`
Ссылка (URL)	Строка	`"https://example.com"`
Да/Нет	`true` или `false`	`true`
Выпадающий список, радио	Строка — точное значение варианта	`"Наличные"`
Цветные статусы	Строка — точное название варианта	`"Подтверждено"`
Связь с сущностью	Числовой id записи или вложенный объект	`3` или `{...}`
Пользователь	Числовой id пользователя	`1`

Поля типа «Автономер», «Формула», «Агрегат», «Подстановка» заполняются системой автоматически — их передавать не нужно.

Вложенные объекты для полей-связей

Если поле является связью с другим справочником (тип «Связь с сущностью»), можно вместо готового id передать объект с данными — платформа автоматически создаст новую запись в нужном справочнике и подставит её id.

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

Пример: документ «Заявки» имеет поле «Клиент», которое ссылается на справочник «Контрагенты». Вместо id клиента можно передать его данные напрямую:

curl -X POST https://ваш-сайт.ru/api/records/5 \
  -H "Authorization: Bearer abcdef123456..." \
  -H "Content-Type: application/json" \
  -d '{
    "service": "Стрижка",
    "comment": "Хочу запись на вечер",
    "client": {
      "name": "Иван Иванов",
      "phone": "+79001234567",
      "email": "ivan@example.com"
    }
  }'

Платформа создаст новую запись в справочнике «Контрагенты» с переданными полями и автоматически проставит её id в поле «Клиент» заявки.

Важные ограничения:

Глубина вложенности — один уровень. Внутри вложенного объекта нельзя снова передать объект — только скалярные значения: строки, числа, булевы значения.
Валидация и нормализация полей (телефон, email и т.д.) применяется и к вложенному объекту так же, как к основной записи.
Если целевой справочник требует обязательные поля — они должны быть заполнены во вложенном объекте, иначе запрос вернёт ошибку.
Каждый раз создаётся новая запись в справочнике, дедупликация не выполняется автоматически. Если нужно найти существующую запись — сначала найдите её id через GET /api/records/{id_справочника}?q=Иван.

Получить запись

GET /api/records/{id_сущности}/{id_записи}
Authorization: Bearer ваш_токен

Получить список записей

GET /api/records/{id_сущности}?page=1&limit=50
Authorization: Bearer ваш_токен

Дополнительные параметры: q — поиск по тексту.

API для календаря

Календарь в платформе — это представление поверх обычного документа. Чтобы создать запись в календаре, нужно создать запись в том документе, который является источником для этого календаря.

Какой документ является источником — видно в настройках календаря (поле «Источник данных»).

Создать запись в календаре

Запрос такой же, как для документа — на id документа-источника:

POST /api/records/{id_документа_источника}
Authorization: Bearer ваш_токен
Content-Type: application/json
{
  "поле_начала": "2026-04-15 10:00:00",
  "поле_конца": "2026-04-15 11:00:00",
  "поле_ресурса": 2,
  "имя_клиента": "Иван Иванов"
}

Проверка конфликтов работает автоматически. Если в настройках календаря включён режим «Блокировать» — при попытке создать запись на уже занятое время API вернёт ошибку.

Ответ при конфликте (HTTP 409):

{
  "error": "Конфликт в расписании: слот уже занят"
}

В режиме «Предупреждать» конфликт не блокирует создание — запись сохранится.

Получить слоты календаря

GET /api/calendar/{id_календаря}?from=2026-04-14&to=2026-04-20
Authorization: Bearer ваш_токен

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

Уведомления на почту при создании через API

Платформа умеет автоматически отправлять письмо при каждом создании записи через API-токен. Это полезно когда через сайт приходит заявка — нужный сотрудник сразу получает уведомление.

Важно: уведомления отправляются только при запросах через Bearer-токен. При создании записей вручную через интерфейс письма не уходят.

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

Страница настройки открывается двумя способами:

Структура данных → нужная сущность → иконка письма ✉ в правом углу шапки
Прямой адрес: /meta/entities/{id}/notifications

Доступно только для документов, календарей и аренды. При редактировании сущности.

На странице настраивается:

Получатели — адреса через запятую, куда придёт письмо:

manager@company.ru, admin@company.ru

Тема письма — поддерживает переменные из полей записи:

Новая заявка от {{name}} — {{phone}}

Текст письма — поддерживает те же переменные:

Имя: {{name}}
Телефон: {{phone}}
Услуга: {{service}}
Комментарий: {{comment}}

Доступные переменные:

{{id}} — числовой id созданной записи (всегда)
{{status}} — статус записи (всегда)
{{имя_поля}} — значение любого поля из шапки документа

Даты автоматически форматируются в читаемый вид: 15.04.2026 и 15.04.2026 10:00.

Если письмо не отправилось (нет связи с почтовым сервером, неверные настройки) — запись всё равно создаётся. Ошибка отправки не блокирует ответ API.

Настройка почтового сервера (SMTP)

Уведомления отправляются через почтовый сервер, который настраивается один раз для всей платформы.

Путь: Администрирование → иконка шестерёнки ⚙ на странице уведомлений → «Настройки SMTP»

Или со страницы уведомлений любой сущности — кнопка шестерёнки в шапке.

Что нужно заполнить:

Поле	Описание	Пример
Сервер	Адрес SMTP-сервера	`smtp.yandex.ru`
Порт	Порт подключения	`465` (SSL) или `587` (STARTTLS)
Логин	Почтовый адрес или логин	`noreply@company.ru`
Пароль	Пароль от почтового ящика	—
Отправитель (email)	Адрес в поле «От»	`noreply@company.ru`
Отправитель (имя)	Имя в поле «От»	`Платформа Уни`
STARTTLS	Тип шифрования	включить для порта 587

Безопасность

Права токена = права пользователя. Для интеграций рекомендуется создавать отдельного пользователя с минимально необходимыми правами: только create на нужный документ.

Токен не восстанавливается. Если потеряли — отзовите старый и создайте новый.

Не храните токен в открытом виде в исходном коде или в публичных репозиториях. Используйте переменные окружения или защищённые хранилища секретов.

Все действия через токен фиксируются с признаком token в системе — при необходимости можно отследить откуда пришла запись.

Платформа Уни · v0.9.9.8