17. Entegrasyon API’si ve API anahtarları

Entegrasyon API'si, kendi programınızın, tablonuzun veya betiğinizin proje verilerinizi otomatik olarak okumasını sağlar: proje listesi, kablo ve malzeme listeleri, dağıtım panolarının devre tablosu ve klemens listesi, metraj dökümü ve çizim paketinin oluşturulması. API salt okunurdur: çizimi ve projeyi hiçbir zaman değiştirmez.

API anahtarını kim alabilir

API erişimi, işletmeci tarafından hesap bazında etkinleştirilir. Hesabınıza erişim verildiğinde Profil sayfasında API anahtarları kartı görünür; erişim yoksa kart gizlidir. Bir hesabın aynı anda en fazla 5 etkin anahtarı olabilir.

Anahtar, sizinle aynı projeleri görür: kendi projelerinizi ve istek üzerine sizinle paylaşılanları. Paylaşılan bir projede listeler ve metraj, yalnızca paylaşım dışa aktarmaya izin veriyorsa döndürülür.

Anahtar oluşturma

Profil sayfasındaki API anahtarları kartında Yeni anahtar düğmesine tıklayın.
Anahtara bir ad verin (örneğin onu kullanacak programın adı).
Kapsamı seçin: Projeleri okuma proje listesini ve proje verilerini, Belgeleri okuma ise listeleri, metrajı ve çizim paketini verir. Yalnızca programın gerçekten ihtiyaç duyduğunu seçin.
Son kullanma süresini seçin: 30, 90 veya 365 gün. Süresi dolan anahtar çalışmaz; onun yerine yeni bir tane oluşturun.
Geçerli parolanızı girin (parolası olmayan bir hesap için yeni bir oturum açma gerekir). İlk anahtarınızda API kullanım koşullarını kabul edin.

Oluşturulduktan sonra anahtar yalnızca bir kez gösterilir: kopyalayın ve güvenli bir yerde saklayın. Daha sonra listede yalnızca ön eki (avk_…) görünür; yanında oluşturma ve son kullanma tarihleri, son kullanım ve çağrı sayısı yer alır. Yeni anahtar için ayrıca bir e-posta bildirimi de göndeririz (anahtarın kendisi olmadan).

Anahtarı iptal etme

Kartta anahtarın yanındaki İptal et düğmesi anahtarı hemen kullanılamaz hale getirir; bu işlem geri alınamaz. Anahtarı artık kullanmıyorsanız, onu kullanan programı kaldırıyorsanız veya sızdığından şüphe ediyorsanız anahtarı iptal edin.

Güvenlik ipuçları

Anahtara parolanız gibi davranın: onu bilen herkes, kapsamı dahilinde projelerinizi okuyabilir.
Kaynak kodda değil, bir gizli bilgi deposunda tutun (parola yöneticisi, sunucunun ortam değişkeni veya CI'ın gizli değişkeni): git deposuna eklemeyin, paylaşılan tabloya veya e-postaya da koymayın.
Tarayıcıda çalışan kodda kullanmayın (web sayfası, tarayıcı eklentisi): orada herkes onu okuyabilir. Anahtarın yeri bir sunucu, bir betik veya bir masaüstü programıdır.
Her programa, mümkün olan en dar kapsamlı ve kısa süreli kendi anahtarını verin; böylece bir anahtarı iptal etmek başka hiçbir şeyi durdurmaz.

Programdan kullanma

Anahtar, istek başlığında Bearer belirteci olarak gönderilir: Authorization: Bearer avk_…. Uç noktalar /api/v1/ altındadır (örneğin GET /api/v1/projects) ve JSON ile yanıt verir. OpenAPI biçimindeki tam açıklama /api/v1/openapi.json adresinde bulunur; çoğu geliştirici aracı onu içe aktarabilir.

Çağrı sayısı anahtar başına ve hesap başına sınırlıdır (varsayılan olarak dakikada 60 ve günde 10.000); bunun üzerinde sunucu 429 ile yanıt verir, bu durumda biraz bekleyin. Web sitesine oturum açmak (çerez) API'yi açmaz ve bir anahtar sizi web arayüzünde oturum açtırmaz.