본문으로 건너뛰기

가상 장치 이벤트 로그 연동하기

가상 장치 기능을 사용하면, 근태 관리 기능을 연동할 때 모바일 앱이나 타사 서비스에서 발생한 출근, 퇴근 등의 이벤트를 BioStar X에 직접 기록할 수 있습니다. 실제 물리적 장치 없이도 이벤트 로그를 체계적으로 관리할 수 있어 외부 시스템과의 연동에 유용합니다.

언제 사용하나요?​

다음과 같은 상황에서 가상 장치 이벤트 로그 연동 기능을 사용하세요.

  • 외부 근태 관리 시스템의 이벤트를 BioStar X에서 통합 관리해야 할 때

  • 모바일 앱이나 외부 시스템에서 발생한 출입 기록(Punch Log)을 BioStar X에 직접 저장해야 할 때(데이터베이스 연동 없이 출근/퇴근 이벤트 기록)

  • 타사 애플리케이션이나 서비스에서 BioStar X API를 통해 직접 이벤트를 전송해야 할 때

시작하기 전에​

이벤트 로그 API 라이선스가 활성화되어 있어야 합니다. 라이선스 정책에 대한 자세한 내용은 다음 문서를 참고하세요.

알아두기

라이선스 적용에 대한 자세한 내용은 다음 문서를 참고하세요.

가상 장치 등록​

  1. 런처 페이지에서 설정을 클릭하세요.

  2. 화면 왼쪽 사이드바에서 장치를 클릭하세요.

  3. 장치 목록에서 화면 오른쪽 상단의 버튼을 클릭한 후 가상 장치 추가를 선택하세요.

  4. 가상 장치 추가 화면이 나타나면 설정 정보를 입력하세요.

    • 장치 이름: 가상 장치의 이름을 입력하세요.

    • 장치 그룹: 가상 장치를 할당할 그룹을 선택하세요.

    • 장치 ID: 가상 장치의 고유 ID를 입력하세요. 기존 장치 ID와 중복되지 않는 범위 내에서 지정해야 합니다.

    • 설명: 가상 장치에 대한 설명을 입력하세요.

  5. 가상 장치를 등록하려면 화면 오른쪽 하단의 확인 버튼을 클릭하세요.

알아두기

  • 장치 ID는 100000~999999 범위 내에서 지정할 수 있습니다. 기존 슈프리마 장치 ID와 중복되지 않는 범위 내에서 지정해야 합니다.

  • 이미 생성한 장치 ID의 값은 수정할 수 없습니다.

장치 그룹 관리​

가상 장치도 일반 장치와 동일하게 장치 그룹 기능을 사용할 수 있습니다.

  • 기존 장치들과 동일한 그룹에 배치할 수 있습니다.

  • 그룹 권한이 있으면 해당 그룹 내 가상 장치에도 권한을 부여할 수 있습니다.

알아두기

장치 그룹에 대한 자세한 내용은 다음 문서를 참고하세요.

가상 장치 제약 사항​

  • 가상 장치는 다음 메뉴에서만 표시됩니다.

    • 설정 → 장치

    • 모니터링 메뉴의 모든 이벤트 로그 조회 및 이벤트 로그 미리보기

    • 데이터 메뉴의 이벤트 로그 조회

  • 가상 장치는 출입문 및 고급 출입 통제에서 출입 제어 기능을 사용할 수 없습니다.

  • 근태 관리 설정을 위한 장치로 지정할 수 없습니다.

  • 모니터링 메뉴의 사이드바에서 장치 목록으로 표시되지 않습니다.

  • 장치 제어 기능을 사용할 수 없습니다.

  • 멀티 커뮤니케이션 서버 라이선스의 장치 수에 포함되지 않습니다.

API를 통한 이벤트 로그 기록​

지원 이벤트 유형​

다음 이벤트 유형만 기록할 수 있습니다.

  • 출입 허용 (Access granted: 4088)

  • 출입 거부 (Access denied: 6400)

API Parameters​

이벤트 로그 기록 시 다음 파라미터를 제공해야 합니다.

파라미터설명필수 여부
dev_id등록된 가상 장치 ID만 허용필수
evtAccess Granted 또는 Access Denied필수
datetime이벤트 발생 시간필수
user_id사용자 ID필수
tna_key지정된 값으로만 입력 가능선택
Request example
{
    "packet_device_id" : 100003, // required
    "is_virtual_device" : "true", // required
    "events":[ //4088 access granted, 6400 access denied
        {
            "dev_id": 100003, // required
            "evt": 6400, // required
            "datetime": "2025-08-21T14:12:00Z", // required
            "user_id": "2", // required
            "tna_key": "1"
        },
        {
            "dev_id": 100003,
            "evt": 6400,
            "datetime": "2025-08-21T14:13:01Z",
            "user_id": "2",
            "tna_key": "1"
        }
    ]
}
Response example
{
    "Response": {
        "code": "0",
        "link": "https://support.supremainc.com/en/support/home",
        "message": "Success"
    }
}
알아두기

  • 단일 API 호출로 하나의 가상 장치에 대한 여러 이벤트 로그를 한번에 기록할 수 있습니다.

  • API 사용에 대한 자세한 내용은 다음 문서를 참고하세요.

이벤트 로그 조회​

가상 장치를 통해 기록된 이벤트 로그는 메뉴에서 조회할 수 있습니다.

  • 모니터링: 모든 이벤트 조회 및 필터, 이벤트 프리뷰

  • 데이터: 모든 이벤트 조회 및 필터

알아두기

  • 모니터링 메뉴에서 이벤트 조회에 대한 자세한 내용은 다음 문서를 참고하세요.

  • 데이터 메뉴에 대한 자세한 내용은 다음 문서를 참고하세요.

감사 추적​

이벤트 로그 기록 시 아래 예시와 같이 감사 추적이 기록됩니다.

Access Granted, 2025/08/05 03:37:49, 12층 출입문 외부, Administrator(1)
알아두기

  • 이벤트를 일괄로 기록하더라도 각 이벤트마다 개별 감사 추적 항목이 생성됩니다.

  • 감사 추적에 대한 자세한 내용은 다음 문서를 참고하세요.

문제 해결​

가상 장치 추가 버튼이 보이지 않는 경우​

이벤트 로그 API 라이선스를 활성화했는지 확인하세요.

API 호출이 실패하는 경우​

  • 이벤트 로그 API 라이선스를 활성화했는지 확인하세요.

  • 장치 ID가 등록된 가상 장치인지 확인하세요.

  • API 파라미터 형식이 올바른지 확인하세요.

이벤트가 조회되지 않는 경우​

  • 기록한 장치가 올바른 가상 장치 ID인지 확인하세요.

  • 이벤트 필터에서 해당 가상 장치가 선택되어 있는지 확인하세요.

  • 이벤트 기록 시 오류가 발생하지 않았는지 감사 추적을 확인하세요.

이 페이지가 도움이 되었나요?