본문으로 건너뛰기
전체 사용 가이드

설정과 연결 관리 / 외부 연결

외부 앱과 장비에서 Nexia API 사용하기

개발자 API에서 사용자 앱과 무인 장비의 연결을 등록하고 권한, 명세, 요청·응답 내역을 확인합니다.

최근 확인 2026년 10월 28일

시작하기 전에

설정 → 기업 관리 → 데이터 및 연동 → 개발자 API를 여세요. 메뉴의 beta는 베타 기능임을 나타냅니다. 메뉴가 보이지 않으면 관리자에게 개발자 API 관리 권한과 기능 활성화 여부를 확인하세요.

개발자 API는 외부 프로그램에서 Nexia의 플랫폼·앱 업무 기능을 호출하는 기능입니다. Nexia가 다른 서비스에 접속하도록 설정하려면 외부 연결 가이드를 이용하세요. iOS, Android, .NET 등에서 일반 HTTP로 호출할 수 있으며 전용 SDK는 필수가 아닙니다.

관리 화면에 들어갈 수 있다고 모든 업무를 호출할 수 있는 것은 아닙니다. 연결에 허용한 기능과 실제 호출자의 업무·조직·레코드 권한이 모두 적용됩니다.

환경과 사용할 기능 확인하기

  1. 화면 위의 개발 샌드박스 또는 워크스페이스 표시와 API 주소를 확인합니다. 인증 정보는 발급한 환경에서만 사용합니다.
  2. API 명세에서 플랫폼 또는 앱을 선택합니다. 업무 대상별로 묶인 목록에서 기능명과 색상으로 구분된 HTTP 메서드를 확인하고 기능을 열어 파라미터, 요청, 응답과 필요 권한을 확인합니다.
  3. OpenAPI 다운로드로 연동 개발자에게 명세를 전달할 수 있습니다. 등록 시 사용 가능한 API가 자동으로 포함되며, 실제 호출 권한은 계정의 역할과 범위로 제한됩니다.

플랫폼과 앱의 기존 기능에서 목록과 명세를 구성하므로 같은 기능을 별도로 다시 등록할 필요는 없습니다. 개발 중인 앱은 릴리스 제출 전에도 선택된 샌드박스 실행에 반영된 기능을 사용할 수 있습니다. 소스만 수정하고 실행에 반영하지 않은 기능은 나타나지 않을 수 있습니다.

명세 보완 필요는 일부 입력·응답 정보가 없다는 뜻입니다. 동적 검증 조건까지 모두 문서화된 것은 아니므로 실제 호출의 오류도 확인하세요.

사용자가 로그인하는 앱 연결하기

  1. API 인증 정보 → 연결 등록에서 이름을 입력하고 사용자 로그인 · iOS / Android / 데스크톱을 선택합니다.
  2. 연동 개발자가 정한 로그인 후 돌아갈 주소를 입력하고 등록합니다.
  3. 발급된 클라이언트 ID, 사용자 로그인 주소, 토큰 발급 주소를 연동 개발자에게 전달합니다.
  4. 외부 앱에서 Nexia 로그인과 동의를 진행합니다. 해당 테넌트의 SSO를 사용하는 사용자는 기존 SSO 로그인 절차를 이용합니다.

연동 앱은 PKCE 인증 코드 흐름을 구현해야 합니다. 로그인한 사용자의 현재 권한으로 호출하며, 관리자의 권한을 대신 사용하지 않습니다.

로그인하지 않는 장비·서버 연결하기

패널 PC처럼 사람이 로그인하지 않는 장비에는 별도 기기·서비스 계정을 사용합니다. 자산을 등록하는 것만으로 API 인증이 생기지는 않습니다.

  1. 기기·서비스 계정 관리에서 계정 이름과 역할, 접근 범위를 선택합니다. 법인 또는 운영 조직 범위이면 대상도 선택하고 계정과 역할 등록을 누릅니다.

  2. 역할은 설정 → 역할에서 관리합니다. 역할 입력 아래의 역할 만들기 또는 역할 관리로 이동할 수 있습니다. 사용 가능한 API의 일반 업무 권한만 포함한 역할을 선택할 수 있습니다. 기업 전체 권한이 하나라도 포함되면 기업 전체만 선택할 수 있으며, 법인·운영 조직 권한만 포함한 역할은 해당 범위로 제한할 수 있습니다. 사용자 로그인 필요로 표시된 기능은 기기 계정으로 사용할 수 없습니다.

    역할 관리 권한이 있으면 역할 호환성 확인에서 원본 역할과 접근 범위를 선택해 유지·제외 권한과 제한되는 API를 확인할 수 있습니다. 역할 생성 권한도 있으면 확인한 권한으로 새 역할을 만듭니다. 원본 역할은 바뀌지 않습니다. App이 명세에 선언하지 않은 추가 권한은 미리 확인할 수 없으며 실제 호출 시 권한을 다시 검사합니다.

  3. API 인증 정보 → 연결 등록에서 기기·서버 자동 연결을 선택하고 만든 계정을 지정합니다.

  4. 등록 후 표시되는 클라이언트 ID와 비밀키를 안전한 인증 정보 저장소에 보관하고 저장했어요를 누릅니다. 비밀키는 이 화면을 닫으면 다시 볼 수 없습니다.

  5. 연동 프로그램은 토큰 발급 주소에서 클라이언트 인증으로 액세스 토큰을 발급받아 호출합니다. 비밀키를 공개 앱 코드나 누구나 읽을 수 있는 설정에 넣지 마세요.

기계는 지정한 역할과 범위로만 동작합니다. 계정을 만든 사람의 권한을 상속하지 않으며, 사람의 서명이나 사람에게 배정된 업무를 대신 처리할 수는 없습니다.

직접 호출하고 결과 확인하기

  1. 기능을 열고 직접 호출에 해당 연결의 액세스 토큰을 입력합니다. 클라이언트 ID가 아닌 인증 후 발급받은 토큰이 필요합니다. 명세가 있는 입력은 설명, 필수 여부, 형식과 예시를 확인하면서 채웁니다. 예시는 자동으로 전송되지 않습니다.
  2. 호출 실행을 누릅니다. 변경 요청은 확인 후 실행되며, 샌드박스에서도 실제 데이터가 변경됩니다.
  3. 응답과 요청 ID를 확인합니다. 응답을 받지 못했다면 처리 여부가 불확실하므로 즉시 재호출하지 말고 호출 내역을 먼저 확인하세요.

토큰은 화면에 영구 저장되지 않습니다. 중복 실행 방지 키는 해당 API가 지원하는 경우에만 효과가 있습니다.

목록에서 값 찾기가 표시되는 경로 식별자는 같은 토큰으로 목록을 조회해 값을 가져올 수 있습니다. 응답에서 API가 요구하는 식별자 필드와 대상을 선택하세요. 내부 ID와 공개 ID는 서로 다를 수 있습니다. 이번 응답의 최대 50개 항목만 표시하며, 다른 페이지나 검색 조건은 목록 API에서 확인합니다. 관리자 로그인 세션의 권한을 대신 사용하지 않습니다.

명세가 있는 조회 조건과 JSON 본문은 항목별로 입력할 수 있고, 복잡한 입력은 고급 JSON 편집으로 전환할 수 있습니다. 명세가 없으면 API 제공자에게 필요한 키·형식·식별자 조회 경로를 확인하세요. 외부 실행이나 권한 연결이 없거나 JSON 외의 본문만 지원하는 API는 직접 호출 폼 대신 실행할 수 없는 이유를 표시합니다.

호출 내역으로 문제 확인하기

API 호출 내역 표에서 최근 7일의 호출을 찾습니다. 요청 ID 검색, 열 정렬, 페이지 크기 변경을 지원하며, 행을 누르면 Inspector에서 상세 요청·응답, 상태 코드, 처리 시간, 요청 ID를 확인합니다. 입력값이 빠졌다면 검증 오류의 필드별 내용을 보고 수정하세요.

  • 401: 토큰 만료, 연결 해제, 계정 비활성화 또는 다른 환경의 인증 정보인지 확인합니다.
  • 403·404: 허용 기능, 현재 업무 권한, 대상 조직과 선택한 앱 실행을 확인합니다. 권한이 없는 기능은 목록이나 호출 대상에서 숨겨질 수 있습니다.
  • 422: 필수값과 입력 형식을 확인합니다.
  • 429: 요청 빈도를 줄이고 응답에 안내된 재시도 시간을 확인합니다.

인증 정보는 가려지고 본문은 JSON에 한해 64 KiB까지 저장됩니다. 바이너리, 스트리밍, 용량 초과, 잘못된 JSON은 본문 대신 미저장 사유를 표시합니다. 내역에 본문이 없다고 요청 자체가 실행되지 않은 것은 아닙니다.

연결 중지하기

특정 연결을 중지하려면 등록한 연결 → 연결 해제를 누르고 확인합니다. 해당 연결의 토큰이 무효화됩니다. 장비 자체의 접근을 중지하려면 기기·서비스 계정 관리 → 계정 비활성화를 사용합니다.

샌드박스가 만료되거나 사용자 테스트가 종료되면 그 임시 권한으로 발급된 인증도 더 이상 사용할 수 없습니다. 연동 구현과 명세의 기술적인 내용은 개발자 API 문서를 참고하세요.

같은 제품 역량의 사용 가이드

Nexia Cloud OS

외부 앱과 장비에서 Nexia API 사용하기

모바일 앱·데스크톱·패널 PC의 API 연결을 등록하고 실제 호출 결과를 확인합니다.