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, затова изчакайте малко. Входът в уебсайта (бисквитка) не отваря API, а ключът не ви вписва в уеб интерфейса.