17. API integrasi dan kunci API

API integrasi memungkinkan program, spreadsheet, atau skrip Anda sendiri membaca data proyek secara otomatis: daftar proyek, daftar kabel dan material, tabel sirkuit dan daftar terminal panel distribusi, rekapitulasi kuantitas, serta penyusunan paket gambar. API ini hanya-baca: tidak pernah mengubah gambar atau proyek.

Siapa yang bisa mendapatkan kunci API

Akses API diaktifkan per akun oleh operator. Setelah akun Anda mendapat akses, kartu Kunci API muncul di halaman Profil; tanpa akses, kartu itu tersembunyi. Satu akun dapat memiliki paling banyak 5 kunci aktif sekaligus.

Kunci melihat proyek yang sama dengan Anda: milik Anda sendiri, dan atas permintaan juga proyek yang dibagikan kepada Anda. Untuk proyek yang dibagikan, daftar dan rekapitulasi hanya diberikan jika pembagian tersebut mengizinkan ekspor.

Membuat kunci

Di kartu Kunci API pada halaman Profil, klik Kunci baru.
Beri kunci sebuah nama (misalnya nama program yang akan menggunakannya).
Pilih Cakupan: Baca proyek memberikan daftar proyek dan data proyek, Baca dokumen memberikan daftar, rekapitulasi, dan paket gambar. Pilih hanya yang benar-benar dibutuhkan program.
Pilih Kedaluwarsa: 30, 90, atau 365 hari. Kunci yang kedaluwarsa tidak berfungsi lagi; buat kunci baru sebagai gantinya.
Masukkan kata sandi Anda saat ini (akun tanpa kata sandi memerlukan login ulang yang baru). Untuk kunci pertama, setujui ketentuan penggunaan API.

Setelah dibuat, kunci ditampilkan hanya sekali: salin dan simpan di tempat yang aman. Selanjutnya daftar hanya menampilkan awalannya (avk_…), beserta tanggal pembuatan dan kedaluwarsa, penggunaan terakhir, dan jumlah panggilan. Kami juga mengirim pemberitahuan e-mail tentang kunci baru (tanpa kuncinya).

Mencabut kunci

Tombol Cabut di samping kunci membuatnya langsung tidak dapat dipakai; tindakan ini tidak dapat dibatalkan. Cabut kunci jika sudah tidak dipakai, jika program yang memakainya dihentikan, atau jika Anda curiga kunci bocor.

Tips keamanan

Perlakukan kunci seperti kata sandi Anda: siapa pun yang mengetahuinya dapat membaca proyek Anda dalam cakupannya.
Simpan di penyimpanan rahasia (pengelola kata sandi, variabel lingkungan server, atau rahasia CI), bukan di kode sumber: jangan pernah memasukkannya ke repositori git, spreadsheet bersama, atau e-mail.
Jangan gunakan di kode yang berjalan di browser (halaman web, ekstensi browser): di sana siapa pun dapat membacanya. Tempat kunci adalah di server, dalam skrip, atau di program desktop.
Beri setiap program kunci tersendiri dengan cakupan tersempit dan masa berlaku singkat, sehingga mencabut satu kunci tidak menghentikan yang lain.

Penggunaan dari program

Kunci dikirim di header permintaan sebagai token Bearer: Authorization: Bearer avk_…. Endpoint berada di bawah /api/v1/ (misalnya GET /api/v1/projects) dan menjawab dalam JSON. Deskripsi lengkap dalam format OpenAPI tersedia di /api/v1/openapi.json; sebagian besar alat pengembang dapat mengimpornya.

Jumlah panggilan dibatasi per kunci dan per akun (secara default 60 per menit dan 10.000 per hari); jika melebihi, server menjawab dengan 429, jadi tunggu sebentar. Login di situs web (cookie) tidak membuka API, dan kunci tidak membuat Anda login ke antarmuka web.