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, а ключ не здійснює вхід до вебінтерфейсу.