Получение доступа

Короткий ответ на вопрос, который партнёры задают чаще всего: да, ваши разработчики могут настраивать интеграции сами. Что именно понадобится, зависит от уровня.

Что вы хотите	Что нужно
Передавать данные внутрь / забирать наружу (уровень 1)	Креденшл сервисной учётной записи для tv-api и buildingId. Ставить ничего не надо.
Делать это из n8n (уровень 2)	Тот же креденшл плюс наш пакет нод из приватного реестра.
Написать модуль (уровень 3)	Учётная запись разработчика, ключ API песочницы и SDK из приватного реестра.

Креденшл для интеграции

Внешние системы аутентифицируются в tv-api через сервисную учётную запись Keycloak (OAuth2 client credentials) в реалме арендатора — не личным логином и не долгоживущим статическим ключом.

curl -s -X POST \
  "$KEYCLOAK/realms/tangovision/protocol/openid-connect/token" \
  -d grant_type=client_credentials \
  -d client_id="$CLIENT_ID" -d client_secret="$CLIENT_SECRET" | jq -r .access_token

Результат отправляйте как Authorization: Bearer … в каждом вызове. Токены короткоживущие — получайте новый при 401; ровно так и делает креденшл в n8n.

В токене должен быть клейм организации (tenant_id, либо organizationId / org_id): без него API фейлится закрыто — 403 No organization context, а не показывает данные другого арендатора. Проставление этого клейма — часть выдачи учётной записи, поэтому креденшл лучше запросить, а не собирать самостоятельно.

Какую роль просить

Что делает интеграция	Право	Просить роль
Читать слои, помещения, телеметрию	building.layers:read, чтение графа	user
Создавать слои, загружать значения	building.layers:write	manager
Регистрировать подписки на вебхуки	platform.webhooks:write	manager
Создавать и вести заявки	запись в сервис-деск	manager (или роль, ограниченная сервис-деском)

Берите самую узкую роль, покрывающую задачу: интеграции «только отчётность» достаточно user, а не manager.

Не building-graph-writer

Эта роль встречается в таблицах прав рядом с manager. Это внутренняя личность конвейера импорта IFC, и она обходит проверку принадлежности здания — кросс-арендаторная по замыслу. Вопреки названию, это не «узкая роль только на запись», и внешней интеграции её выдавать не следует.

Сначала песочница

Не разрабатывайте на продуктивном арендаторе заказчика. Песочницы по запросу дают изолированного арендатора с собственной базой, наполненным графом здания и полным tv-api — весь процесс описан в Песочницах по запросу, а самостоятельная регистрация и выпуск ключей tvk_… — в Учётной записи разработчика и на портале разработчика.

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

Что сегодня закрыто

Приватный реестр отвечает 401 на анонимные запросы

Пакеты @tv/* — и SDK, и ноды n8n — лежат на https://npm.k8s.tangovision.dev/, а он не отдаёт анонимные загрузки (проверено 04.08.2026). И токен реестра сегодня нельзя выпустить самому: портал разработчика выдаёт ключи API песочницы (tvk_…), это другой креденшл, и для установки пакетов он не годится.

Прямо:

Уровень	Блокируется реестром?
1 — HTTP	Нет. Ставить нечего: curl или любой HTTP-клиент, который у вас уже есть.
2 — n8n	Да, пока нет токена реестра: пакет нод берётся оттуда.
3 — модуль на SDK	Да, по той же причине.

Чтобы получить токен реестра, напишите на developers@tango.vision: почта учётной записи разработчика, организация, для которой делается интеграция, и какие пакеты нужны. Сегодня это ручной шаг с нашей стороны; лучше сказать об этом прямо, чем дать вам потратить полдня на установку, которая не может пройти.

Если вы делаете только уровень 1 — а он покрывает большинство интеграций — ничего из этого не нужно. Запрашивайте креденшл к tv-api и начинайте.

Когда токен получен, настройка .npmrc (включая работу с build-секретом в Docker) описана в Начале работы → Установка SDK.

Что прислать нам

Одно письмо разблокирует интеграцию. Укажите:

1. Кто: организация и почты разработчиков, у которых будут креденшлы.
2. Какие здания: название или buildingId, и это песочница или продуктив.
3. Что делает интеграция: грузит слой данных, шлёт телеметрию, создаёт заявки, принимает вебхуки — от этого зависит роль.
4. Где она работает: для вебхуков — публичный https-URL, который будет принимать доставки (он должен резолвиться публично, см. Данные из двойника).
5. Нужен ли доступ к реестру для SDK или нод n8n.

→ developers@tango.vision

Как проверить, что всё работает

# 1. Доступен ли API вообще? (токен не нужен)
curl -s https://tv-api.k8s.tangovision.dev/health

# 2. Работает ли токен и видит ли он здание?
curl -s -H "Authorization: Bearer $TOKEN" \
  "https://tv-api.k8s.tangovision.dev/api/v1/buildings/$BUILDING_ID/data-layers"

Коды читайте буквально, они различаются намеренно:

• 401 — токена нет, он истёк или выпущен не тем реалмом.
• 403 — токен валиден, но не хватает права, нет клейма организации (No organization context) либо здание принадлежит другой организации (Building does not belong to your organization).
• 404 — здания с таким id не существует вовсе. Обычно это устаревший id в конфиге.

Интерактивный справочник по API облачного контура — /api-docs. Там перечислены все пути, включая те, которых нет в этом разделе.