17. API интеграции и API-ключи

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

Кто может получить ключ API

Ключ API разрешает оператор для каждой учётной записи отдельно. Если ваша учётная запись получила разрешение, на странице Профиль появляется карточка Ключи API; без разрешения карточка не отображается. У одной учётной записи может быть одновременно не более 5 активных ключей.

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

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

На карточке Ключи API страницы Профиль нажмите кнопку Новый ключ.
Дайте ключу имя (например, название программы, которая будет его использовать).
Выберите область доступа: Чтение проектов даёт список проектов и данные проектов, Чтение документов даёт ведомости, объёмы и пакет чертежей. Указывайте только то, что программе действительно нужно.
Выберите срок действия: 30, 90 или 365 дней. Просроченный ключ больше не работает; вместо него вы создаёте новый.
Введите свой текущий пароль (для учётной записи без пароля нужен свежий вход). Для первого ключа примите условия использования API.

После создания ключ показывается только один раз: скопируйте его и сохраните в надёжном месте. Позже в списке видны только его префикс (avk_…), даты создания и окончания срока, последнее использование и число вызовов. О новом ключе мы также отправляем уведомление по электронной почте (без самого ключа).

Отзыв ключа

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

Советы по безопасности

Обращайтесь с ключом как с паролем: кто его знает, тот может читать ваши проекты в пределах заданной области доступа.
Храните его в хранилище секретов (менеджер паролей, переменная окружения сервера или секретная переменная CI), а не в исходном коде: не добавляйте его в репозиторий git, в общую таблицу или письмо.
Не используйте его в коде, работающем в браузере (веб-страница, расширение браузера): там его может прочитать любой. Место ключа — на сервере, в скрипте или в настольной программе.
Дайте каждой программе отдельный ключ с как можно более узкой областью доступа и коротким сроком действия; тогда отзыв одного ключа ничего другого не остановит.

Использование из программы

В заголовке запроса ключ отправляется как токен Bearer: Authorization: Bearer avk_…. Конечные точки находятся под /api/v1/ (например, GET /api/v1/projects), ответ — JSON. Точное описание в формате OpenAPI доступно по адресу /api/v1/openapi.json; большинство инструментов разработчика могут его импортировать.

Число вызовов ограничено для каждого ключа и учётной записи (по умолчанию 60 в минуту и 10 000 в сутки); при превышении сервер отвечает 429 — подождите немного. Вход на сайт (cookie) не открывает API, а ключ не выполняет вход в веб-интерфейс.