17. Integrációs API és API-kulcsok

Az integrációs API arra jó, hogy a saját programod, táblázatod vagy szkripted gépi úton olvassa ki a projektjeid adatait: a projektlistát, a kábel- és anyagjegyzéket, az elosztók áramköri táblázatát és sorkapocs-jegyzékét, a mennyiségkimutatást és a tervcsomag összeállítását. Az API csak olvas: a rajzot és a projektet nem módosítja.

Ki kaphat API-kulcsot

Az API-kulcsot az üzemeltető engedélyezi fiókonként. Ha a fiókod engedélyt kapott, a Profil oldalon megjelenik az API-kulcsok kártya; enélkül a kártya nem látszik. Egy fióknak egyszerre legfeljebb 5 aktív kulcsa lehet.

A kulcs ugyanazokat a projekteket látja, mint te: a sajátjaidat, és kérésre azokat, amelyeket megosztottak veled. Megosztott projekt jegyzékeit és kimutatását csak akkor adja ki, ha a megosztás az exportálást is engedi.

Kulcs létrehozása

1. A Profil oldal API-kulcsok kártyáján kattints az Új kulcs gombra.
2. Adj a kulcsnak nevet (például annak a programnak a nevét, amelyik használni fogja).
3. Válaszd ki a hatókört: a Projektek olvasása a projektlistát és a projektek adatait adja, a Dokumentumok olvasása a jegyzékeket, a kimutatást és a tervcsomagot. Csak azt add meg, amire a programnak tényleg szüksége van.
4. Válaszd ki a lejáratot: 30, 90 vagy 365 nap. A lejárt kulcs nem működik tovább; helyette újat hozol létre.
5. Add meg a jelenlegi jelszavad (jelszó nélküli fióknál friss belépés kell). Az első kulcsnál fogadd el az API-használat feltételeit.

A létrehozás után a kulcs egyetlen egyszer látszik: másold ki, és tedd biztonságos helyre. Később csak az előtagja (avk_…) látszik a listában, a létrehozás és a lejárat dátumával, az utolsó használattal és a hívások számával. Az új kulcsról e-mailes értesítést is küldünk (a kulcs nélkül).

Kulcs visszavonása

A kártyán a kulcs mellett a Visszavonás gombbal a kulcs azonnal használhatatlanná válik; ez nem vonható vissza. Vond vissza a kulcsot, ha már nem használod, ha a programot, amelyik használta, megszünteted, vagy ha gyanítod, hogy kiszivárgott.

Biztonsági tanácsok

• A kulcsot kezeld úgy, mint a jelszavad: aki ismeri, a megadott hatókörben olvashatja a projektjeidet.
• Tárold titoktárolóban (jelszókezelő, a szerver környezeti változója vagy a CI titkos változója), ne a forráskódban: ne kerüljön a git-repóba, megosztott táblázatba vagy e-mailbe.
• Ne használd böngészőből futó kódban (weboldal, böngészőbővítmény): ott bárki kiolvashatja. A kulcs szerveren, szkriptben vagy asztali programban a helye.
• Minden programnak legyen saját kulcsa, a lehető legszűkebb hatókörrel és rövid lejárattal; így egy kulcs visszavonása nem állít le mást.

Használat programból

A kérés fejlécében a kulcs Bearer tokenként megy: Authorization: Bearer avk_…. A végpontok a /api/v1/ alatt vannak (például GET /api/v1/projects), a válasz JSON. A pontos leírás OpenAPI-formában a /api/v1/openapi.json címen érhető el; ezt a legtöbb fejlesztői eszköz be tudja olvasni.

A hívások száma kulcsonként és fiókonként is korlátozott (alapból percenként 60, naponta 10 000); a túllépésre a szerver 429-es választ ad, ilyenkor várj egy kicsit. A webes belépés (süti) az API-t nem nyitja meg, és a kulcs a webes felületre nem léptet be.