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를 사용할 수 없으며, 키로 웹 인터페이스에 로그인할 수도 없습니다.