Интеграции: разработка или настройка?

Если у вас уже работает система эксплуатации, историзатор АСУЗ или мониторинг инженерных систем и вы хотите, чтобы эти данные появились на графе здания, — в большинстве случаев это настройка, а не проект разработки.

Весь этот раздел написан для такого читателя: для того, кто не пишет модуль и не собирается. (Если всё-таки собираетесь — вам в Начало работы.)

Три уровня и чего каждый реально стоит

	Что вы делаете	Кто делает	Трудоёмкость
1. Отправлять данные по HTTP	Ваша система шлёт значения с идентификатором помещения на один эндпоинт. Без SDK, без пакетов, без модуля.	Тот, кто сопровождает исходную систему	Часы. Один эндпоинт, одна форма payload.
2. No-code конструктор сценариев	Собираете сценарий в n8n с нашими нодами Building OS: расписание, повторы, преобразования, ветвления — всё в интерфейсе.	Инженер эксплуатации	Часы, и ни строки кода.
3. Свой модуль на SDK	Только когда нужен свой экран внутри платформы и своя логика за ним.	Команда разработки	Дни плюс релизный цикл.

Типовой случай — уровень 1. «Наши заявки и показания датчиков должны быть на плане и раскрашивать помещения» — это один эндпоинт на каждый набор данных. Платформенный код не пишет никто: ни вы, ни мы.

Уровень 3 существует потому, что некоторые партнёры действительно хотят своего продуктового интерфейса внутри Building OS. Это не входной билет для того, чтобы передать данные.

Какой уровень нужен вам

• «Хочу, чтобы статус аренды / занятость / CO₂ по помещениям раскрашивали план» → уровень 1, Данные в двойник.
• «Мониторинг инженерных систем передаёт давление и температуру, хочу видеть их вживую на двойнике» → уровень 1 (телеметрия), та же страница.
• «То же самое, но без крон-задач и логики повторов» → уровень 2, тот же контракт, но из n8n. (Показания могут приходить и по MQTT — см. Данные в двойник.)
• «Когда заявка меняет статус у вас, наша система должна об этом узнать» → Данные из двойника — прочитайте до проектирования: наружу сегодня отдаётся меньше, чем принимается внутрь, и там прямо сказано, где границы.
• «Заявки должны жить в обеих системах и не расходиться» → В обе стороны: это в первую очередь про то, чья запись главная, и решить это надо до кода.
• «Хочу своё рабочее место со своими экранами внутри Building OS» → уровень 3: Ваш первый модуль.

Как выглядит «один эндпоинт»

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

# 1. Создать слой (однократно)
curl -X POST "$TV_API/api/v1/buildings/$BUILDING_ID/data-layers" \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"key":"fm-open-tickets","name":"Открытые заявки","valueType":"NUMBER"}'

# 2. Загрузить значения (сколько угодно раз) — ключи это идентификаторы помещений
curl -X PUT "$TV_API/api/v1/buildings/$BUILDING_ID/data-layers/$LAYER_ID/values" \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"keyBy":"externalId","values":{"3lPQxG$0v9zRZ1mB7kYtE2":4,"1aBcDe$FgHiJkLmNoPqRs":0}}'

Это вся интеграция для слоя «сколько открытых заявок в помещении». Полный контракт — типы значений, ограничения на пакетную загрузку, что возвращается — на странице Данные в двойник.

Где проходит граница

Делаем мы	Делаете вы
Граф здания: помещения, этажи, оборудование и их идентификаторы.	Решаете, какая ваша запись какому помещению соответствует.
Эндпоинты, их авторизацию, валидацию и хранение.	Вызываете их — по своему расписанию, из своей системы.
Отрисовку слоя на 2D-плане и на BIM-модели.	Выбираете тип значения и (по желанию) легенду.
Выдаём креденшлы и песочницу.	Храните креденшлы в своём менеджере секретов.

Чтобы добавить слой, не нужен наш инженер на созвоне и не нужно ждать релиза платформы. Как только у вас есть креденшл и buildingId, всё описанное в этом разделе вам доступно.

В этом разделе

• Данные в двойник — как передать данные внутрь: слои по помещениям и временные ряды с датчиков.
• Данные из двойника — вебхуки, живой сокет и честный разбор того, что наружу пока не отдаётся.
• В обе стороны — синхронизация заявок и выбор главной системы.
• Идентификаторы — как строка из вашей базы находит нужное помещение. Именно здесь интеграции ломаются.
• Получение доступа — креденшлы, песочница и то, что сегодня закрыто.