Документация Формулы
Разделы документации

Руководство

Обзор руководства

Бизнес-процессы и задачи

Бизнес-процессы и задачи

РАЗРАБОТКА

Страницы и внешний API

Материал для тех, кто собирается писать код поверх платформы: собственные страницы и интеграции из внешних систем.

Если вам нужны только готовые экраны внутри системы — это Страницы (внешние и внутренние). Здесь — то, что нужно программисту.

Страницы (HTML / CSS / JS)Свои экраны внутри системы и публичные страницы
КомпонентыПереиспользуемые библиотеки JS
Модули объектовСерверная и клиентская логика объекта
formApiЕдиный API для страниц, компонентов и модулей
Внешний REST APIЧтение и запись данных из чужих систем
ПланировщикФоновые задачи по расписанию

# Где что лежит

АртефактРаздел Конструктора
СтраницыСтраницы
КомпонентыКомпоненты
ПланировщикПланировщик
Модули объектовСправочники/Документы/… → вкладка Модуль

Подробнее: Компоненты, Планировщик, Модуль объекта.


# Адреса страниц

Вид страницыАдрес
ВнешняяURL, заданный в Свойства страницы → URL страницы (например /my-custom-page)
Внутренний объектОткрывается вкладкой внутри системы; произвольного URL нет
Публичная (без авторизации)Тот же URL внешней страницы, но доступна без входа

Публичная страница может читать только те объекты, которые перечислены в Публичные данные (ID через запятую), и только на чтение, с ограничением частоты запросов.

Важно

Для публичных страниц HTML проходит через очистку по белому списку: теги <script>/<style>, атрибут style и обработчики вида onclick="…" вырезаются. Логику навешивайте через addEventListener в коде страницы, стили — во вкладке CSS.


# formApi — единый API

formApi доступен в JS страницы, в компонентах и в модулях объектов. В модуле объекта это глобальная переменная — объявлять её не нужно.

# Работа с текущей формой

МетодЧто делает
getValue(поле)Прочитать значение поля
setValue(поле, значение)Записать значение поля
setFieldState(поле, настройки)Изменить видимость, доступность, обязательность поля
getTabularSection(имя)Получить табличную часть
preloader(вкл/выкл)Показать/скрыть индикатор загрузки

# Диалоги и навигация

МетодЧто делает
showAlert(текст, настройки)Показать сообщение
showConfirm(текст)Спросить подтверждение, вернуть «да/нет»
showPage(имя, настройки, параметры)Открыть страницу
getContext()Получить контекст: текущего пользователя

# Данные

МетодЧто делает
read(ссылка)Прочитать запись
readList(тип, имя, отбор)Прочитать список
create(тип, имя, данные)Создать запись
update(ссылка, данные)Изменить запись
delete(ссылка)Удалить запись
post(имя, id)Провести документ
unpost(имя, id)Отменить проведение

# Почта и ИИ

МетодЧто делает
Почта(кому, html, тема)Отправить письмо
ai(запрос)Спросить ИИ-ассистента

На страницах недоступны методы, привязанные к объекту: getValue, setValue, setFieldState, preloader, getTabularSection. Страница не привязана к конкретной записи.

# Пример

javascript
document.addEventListener('DOMContentLoaded', async () => {
  const ctx = formApi.getContext();
  const rows = await formApi.readList('Справочник', 'Номенклатура', {});
  const box = document.getElementById('list');
  if (box) box.innerHTML = rows.map(r => `<div>${r.Наименование}</div>`).join('');
});

# Порядок выполнения кода

ПорядокЧто подключается
1Глобальные стили
2formApi
3HTML страницы
4Внешние CSS/JS (ваши ссылки)
5Модуль страницы (ваш JavaScript)

Компоненты, подключённые к странице, выполняются до модуля страницы. В модуле объекта компоненты выполняются до кода модуля.


# Внешний REST API

Внешний API позволяет сторонним системам читать и изменять данные платформы.

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

ШагДействие
1POST /api/external/login с телом { "username": "...", "password": "..." }
2В ответ приходит токен
3Дальше токен передаётся в заголовке Authorization: Bearer <токен>

Токены — JWT (HS256). Отозванные сессии не проходят проверку. Вход защищён ограничением частоты попыток.

# Адреса

МетодАдресЧто делает
GET/api/external/{Тип}/{objectId}Список записей
POST/api/external/{Тип}/{objectId}Создать запись
GET/api/external/{Тип}/{objectId}/{recordId}Прочитать запись
PUT/api/external/{Тип}/{objectId}/{recordId}Изменить запись
DELETE/api/external/{Тип}/{objectId}/{recordId}Удалить запись

{Тип} — человекочитаемый тип: Справочник, Документ, Регистр, Отчет.

# Параметры списка

ПараметрЧто делает
_sort=Поле:asc / :descСортировка
_page=1Номер страницы
_limit=25Записей на страницу
_fields=Поле1,Поле2Только указанные поля
Поле=значениеФильтр по точному значению
Поле[gt]=значениеБольше
Поле[gte]=значениеБольше или равно
Поле[lt]=значениеМеньше
Поле[lte]=значениеМеньше или равно
Поле[ne]=значениеНе равно
Поле[contains]=текстСодержит подстроку

# Права и защита

МеханизмКак работает
Права на объектПроверяются по группам пользователя: read_access, write_access, delete_access
АдминистраторГруппа admin обходит проверки прав
По умолчаниюЕсли строки прав нет — доступ запрещён
Ограничение частотыПо IP и по пользователю
Служебные поля__proto__, constructor, prototype, _markedForDeletion, _rowVersion и подобные не принимаются от клиента

Подробнее о правилах прав — Права и роли.


# Планировщик для разработчика

ПонятиеЗначение
Точка входа компонентаonSchedule(formApi, schedulerTask)
Резервная точка входаmain, если onSchedule не определена
РежимыОднократно / многократно / непрерывно
ЖурналХранятся последние 50 запусков

Подробнее — Планировщик задач.


# Ограничения и правила

ПравилоПочему
Не используйте eval и динамическое исполнение в публичных страницахКод вырезается санитайзером
Не храните секреты в HTML/JS страницыСтраница может быть публичной
Проверяйте права на стороне сервераКлиентские проверки легко обойти
Не пишите в регистры напрямую из отчётовИспользуйте документы и правила проведения
Числовые вычисления — через Выражение реквизитаТак надёжнее и быстрее, чем код
Обработчики событий — через addEventListenerИнлайновые обработчики удаляются

# Куда смотреть дальше

ТемаДокумент
Страницы в КонструктореСтраницы
Модуль объекта и обработчикиМодуль объекта
КомпонентыКомпоненты
ПланировщикПланировщик задач
Печатные формыПечатные формы
Отчёты: наборы данныхОтчёты
Права доступаПрава и роли
ИИ-агентВозможности агента