본문으로 건너뛰기

키카드 인코더 문제 해결

빠른 해결

먼저 네트워크와 전원을 확인한 뒤, 카드 한 장으로 다시 인코딩해 보세요. 약 2분이면 됩니다.

이 안내서는 흔한 키카드 인코더 문제를 해결하는 데 도움이 됩니다.

빠른 참고​

보이는 내용발생 이유할 일
인코더가 응답하지 않음전원 또는 네트워크 문제연결 상태 확인
"We could not determine the room for this reservation."PMS 객실 조회에서 사용할 수 있는 객실을 반환하지 않음객실 확인 재시도
카드 인코딩 실패카드 유형 또는 장치 문제카드와 장치 확인
평이한 문장의 키카드 실패 메시지AVA가 벤더, 객실, 세션 오류를 정리해서 표시함메시지 읽기
"UserCredentialsNotProvided.NotApplicable"Saflok 자격 증명이 없거나 불완전함Saflok 자격 증명 추가
Saflok/Ambiance 인코딩 실패 또는 시간 초과Windows Agent, Ambiance 인코더 서비스, 또는 장치가 오프라인 상태Saflok/Ambiance 인코더 다시 시작
"Please create a new keycard first, then use Duplicate for any extra cards."Saflok이 예약에 대한 기존 활성 등록을 찾지 못함첫 키카드 누락 수정
다중 객실 Saflok/Ambiance 카드에 객실 수준 ID가 필요함선택한 객실에 아직 자체 하위 예약이 없음선택한 객실 확인
"The keycard encoder is temporarily offline. Please approach the Front Desk for assistance."인코더에 활성 세션이 없음인코더 세션 확인
원시 DoorLock generate fail 또는 internal error 텍스트가 표시됨기술적인 room-access 페이로드가 모달까지 전달됨일반 재시도 경로 사용
"Request timezone does not match the hotel timezone" 또는 "Hotel timezone configuration is invalid"호텔 시간대가 없거나 유효하지 않거나 요청 메타데이터와 충돌함Opera 시간대 설정 확인
인코더 유형 변경이 유지되지 않음이전 저장으로 인코더 상태가 섞여 있음인코더 유형 다시 저장
"Test Connection" 실패(Be-Tech) 또는 에이전트가 계속 오프라인Base URL, 어댑터, 또는 서비스 문제Be-Tech 연결 수정
Be-Tech 클라이언트 또는 서비스가 재시작이나 수동 중지 후 중지됨에이전트가 로컬 벤더 클라이언트를 복구 중임Be-Tech 복구 대기
"Make sure the Be-Tech client program is running on the encoder computer."Windows Agent가 502 벤더 비가용 응답을 반환함Be-Tech 클라이언트 프로그램 확인
"Test Connection" 실패(GreatLocks)저장된 GreatLocks 서버 정보가 없거나 오래됨GreatLocks 연결 수정
GreatLocks에서 인코더를 선택하라고 요청함여러 GreatLocks 서버 또는 에이전트를 사용할 수 있음GreatLocks 인코더 선택
GreatLocks 인벤토리가 로드되지 않음에이전트 터널, 서버 레코드, 또는 인벤토리 소스 문제GreatLocks 인벤토리 동기화 확인
PMS 인코더 검색 결과가 없음PMS 공급업체가 틀렸거나, PMS가 단말을 노출하지 않음PMS 검색 확인
Opera 라우트가 모호하거나 불완전함Opera가 중복되거나 누락된 Door Lock 라우팅 세부 정보를 반환함Opera 라우트 세부 정보 수정
카드 읽기 중 "OPERAWS-FOF01920"이 표시됨오래되었거나 잘못된 인터페이스 값이 Opera로 전송됨Opera 라우트 새로 고침
카드 읽기 중 "OPERAWS-FOF00199"가 표시됨Opera가 구성된 Door Lock System에 연결할 수 없음Door Lock 연결 확인
PMS 카드 읽기를 사용할 수 없음읽기 설정, PMS 기능, 또는 활성 인코더 문제PMS 카드 읽기 확인
카드가 감지되지 않음리더가 카드를 찾지 못함카드 다시 삽입
카드 유형이 지원되지 않음카드가 있지만 인코더가 유형을 인식하지 못함지원되는 카드 사용
카드를 읽을 수 없음카드가 있지만 인코더가 데이터를 읽지 못함다른 카드 시도
Opera 카드 읽기에 일반 오류가 표시됨Opera가 비어 있거나 잘못된 카드 응답을 반환함Opera 카드 응답 확인
PMS 키오스크가 인코더를 확인하지 못함Device Model과 기존 키오스크 매핑에서 서로 다른 레이블을 사용함PMS 키오스크 매핑 확인
"Service URL is required" (LockSDK)직접 모드에서는 인코더마다 Service URL이 필요함LockSDK Service URL 추가
LockSDK 에이전트가 Not registered로 표시됨인코더별 에이전트 장치가 아직 없음LockSDK 에이전트 등록
Heartbeat Monitor가 저장 후 꺼짐현재 호텔 세션에서 저장이 유지되지 않음Heartbeat Monitor 다시 저장
Heartbeat가 unreachable로 표시됨에이전트 오프라인 또는 터널 문제에이전트 상태 확인
Heartbeat가 unknown으로 표시됨AVA가 인코더 상태를 확인하지 못함알 수 없음 상태 확인
Heartbeat가 상태 또는 터널 오류를 보고함진단 확인 또는 에이전트 터널이 실패함보고된 오류 확인
인코더가 계속 사용할 수 없음 상태임동적 목록이 아직 에이전트를 끊긴 상태로 봄실시간 인코더 상태 확인
Windows Agent가 Not connected로 표시됨에이전트가 실행되지 않거나 설치가 불완전함에이전트 다시 연결
"This Windows Agent is too old to read keycards"설치된 에이전트에 Read Keycard가 포함되지 않음Windows Agent 업데이트
"The encoder tunnel is offline"Universal Encoder Agent 터널을 사용할 수 없음인코더 터널 다시 연결
Windows가 권한을 요청함트레이 서비스 제어에 상승 권한이 필요함UAC 프롬프트 승인

예약 객실을 확인할 수 없음​

보이는 현상: 인코더를 선택한 후 AVA에 "We could not determine the room for this reservation."가 표시됩니다.

이유: 인증된 PMS 조회에서 사용할 수 있는 객실 식별자를 반환하지 않았습니다.

해결:

  1. 예약 또는 Operations View를 새로고칩니다.
  2. PMS에서 예약에 객실이 배정되어 있는지 확인합니다.
  3. 예약, 체크인 또는 키 관리 흐름을 다시 시작합니다.
  4. AVA가 요청하면 온라인 인코더를 선택합니다.
  5. PMS에서 객실을 배정한 후에도 메시지가 다시 표시되면 지원팀에 문의합니다.

AVA는 긴 AVA PMS 식별자를 포함해 유효한 PMS 객실 식별자를 허용합니다. PMS 객실 식별자를 직접 줄이거나 수정하지 마세요.

인코더가 응답하지 않음​

보이는 현상: AVA에서 인코더가 오프라인으로 보이거나 응답이 없습니다.

해결:

  1. 인코더의 전원과 케이블을 확인합니다.
  2. 키오스크와 인코더 사이의 네트워크 연결을 확인합니다(직접 연결만 해당).
  3. 서버 IP와 포트가 올바른지 확인합니다.
  4. 인코더 소프트웨어를 다시 시작합니다.

카드 인코딩이 안 됨​

보이는 현상: 키카드 쓰기가 실패하거나 빈 카드가 만들어집니다.

해결:

  1. 카드 유형이 인코더와 일치하는지 확인합니다.
  2. 카드를 다시 넣고 재시도합니다.
  3. 새 빈 카드로 시험합니다.
  4. Enable guest selection이 꺼져 있으면 키오스크가 올바른 인코더로 라우팅되는지 확인합니다.
  5. Enable guest selection이 켜져 있으면 게스트가 키오스크에서 온라인 인코더를 선택하는지 확인합니다.

정리된 인코딩 실패​

보이는 현상: 예약 모달에 원시 벤더 문자열 대신 짧고 평이한 문장이 표시됩니다.

이유: AVA는 이제 정리된 Saflok, Be-Tech, Opera, 그리고 내부 세션 실패를 먼저 보존한 뒤 표시합니다. 구조화된 메시지를 우선 사용하고, 필요하면 예전 벤더 문자열 파싱으로 되돌아갑니다. HTTP 504 room-access 시간 초과도 KEYCARD_VENDOR_TIMEOUT으로 같은 경로를 따릅니다. 직원 알림과 관련 로그 세부 정보도 같은 정규화된 실패 범주를 사용합니다. 예를 들어 카드가 삽입된 오류는 No card detected로 보고되지 않습니다.

해결:

  1. 짧은 메시지를 먼저 읽습니다.
  2. 지원 화면에서 userMessage, errorCode, retriable, 벤더 이름, 그리고 안전한 upstream 세부 정보를 확인합니다.
  3. 지원팀에 문의할 때 그 정보를 사용합니다.
  4. 메시지에 따라 아래의 가장 가능성 높은 해결책을 적용합니다.
    • Occupied room: 예약을 새로고친 뒤 다시 시도합니다.
    • Encoder offline: 전원, 네트워크, 또는 에이전트 상태를 확인합니다.
    • No card detected: 카드를 다시 넣고 위치를 확인합니다.
    • Unsupported card type: 이 인코더가 지원하는 카드 유형을 사용합니다.
    • Card could not be read: 다른 카드를 시도하고 손상 여부를 확인합니다.
    • No active session: 인코더 세션을 다시 연결합니다.
    • Missing mapping: 객실 매핑이 올바른지 확인합니다.
    • Invalid room or date: 숙박 날짜와 객실 배정을 확인합니다.
    • Vendor auth, gateway, or timeout: 벤더 접근을 확인하거나 나중에 다시 시도합니다.
    • HTTP 504 timeout: 잠시 기다렸다가 다시 시도합니다.
    • Invalid request: 올바른 예약을 다시 열고 재시도합니다.
  5. retriable가 true면 새로고침 후 다시 시도합니다.
  6. retriable가 false면 먼저 매핑 또는 벤더 문제를 수정합니다.
이전 방식 폴백 유지

오래된 응답은 여전히 예전 벤더 문자열을 표시할 수 있습니다. AVA는 이 파싱 경로를 유지해 과거 로그와 구형 연동도 계속 읽을 수 있게 합니다.

Opera 시간대 불일치​

보이는 현상: PMS가 객실 키를 반환하기 전에 키카드 흐름이 중지됩니다. "Request timezone does not match the hotel timezone" 또는 "Hotel timezone configuration is invalid"가 표시될 수 있습니다.

이유: AVA는 Opera 키카드 유효성을 UTC가 아니라 숙소의 현지 벽시계 시간으로 지정합니다. 호텔 시간대가 없거나 유효하지 않으면 안전을 위해 실패합니다. 요청 시간대 데이터가 충돌하는 경우에도 실패합니다.

해결:

  1. Settings → Essentials → Hotel Basic Details로 이동합니다.
  2. Timezone이 유효하고 숙소 현지 시계와 일치하는지 확인합니다.
  3. 변경했다면 저장합니다.
  4. 예약을 새로고치거나 키카드 흐름을 다시 엽니다.
  5. 키카드 요청을 다시 시도합니다.

Saflok/Ambiance 인코딩이 동작하지 않음​

보이는 현상: 키카드 인코딩이 실패하거나 시간 초과되고, 키오스크가 Saflok/Ambiance 인코더의 응답이 없다고 표시합니다.

해결: 아래 세 가지 점검을 순서대로 진행하세요. 각 단계는 다음 단계로 넘어가기 전에 흔한 원인을 하나씩 제거합니다.

자동 Saflok 복구

Saflok PMSI가 느리게 시작하거나 나중에 재시작되면 AVA는 10초마다 준비 상태를 다시 확인합니다. 잠시 기다렸다가 에이전트를 다시 설치하기 전에 새로고침하세요.

1. Windows Agent가 AVA에 연결되어 있는지 확인​

  1. Settings → Room Access → Keycard Encoding으로 이동합니다.

  2. 이 인코더의 Windows Agent 카드를 찾습니다.

  3. 상태가 Connected이고 Last Seen 시간이 최근인지 확인합니다.

    Windows Agent에 Connected와 최근 Last Seen 시간이 표시됨

  4. 에이전트가 Not connected이면 계속하기 전에 Windows Agent가 연결되지 않음을 따릅니다. Saflok PMSI가 아직 시작 중이라면 10초 기다렸다가 한 번 새로고침한 뒤에 재설치를 고려하세요.

2. Ambiance에서 인코더가 온라인인지 확인​

에이전트는 연결되어 있지만 인코딩이 계속 실패하면 Ambiance 서버에 로그인해 인코더 장치를 확인합니다.

  1. Ambiance를 열고 Device Management → Encoders로 이동합니다.

  2. 이 키오스크의 인코더(예: Vouch 인코더)를 찾습니다.

  3. Status가 Online인지 확인합니다.

    Ambiance Device Management에 인코더 Status: Online이 표시됨

  4. 인코더가 Offline이면 다음 단계로 넘어가 인코더 서비스를 다시 시작합니다.

3. Ambiance Encoder Service 다시 시작​

Ambiance에서 인코더가 오프라인이면 Ambiance 서버가 설치된 컴퓨터에서 인코더 서비스를 다시 시작합니다.

  1. Ambiance 서버가 실행 중인 컴퓨터에서 Windows 키를 누르거나 Start 메뉴를 클릭합니다.

  2. services manager를 입력하고 결과에서 Ambiance Services Manager를 엽니다.

  3. 서비스 목록에서 Ambiance Encoder Service를 선택합니다.

    Ambiance Services Manager에서 Ambiance Encoder Service가 선택됨

  4. Stop(빨간 사각형) 버튼을 클릭합니다.

  5. 서비스 상태가 Stopped로 바뀔 때까지 몇 초 기다립니다.

  6. Start(빨간 재생) 버튼을 클릭합니다.

  7. State가 Running으로 돌아오는지 확인합니다.

  8. 다시 Ambiance Device Management → Encoders로 돌아가 인코더가 Online인지 확인합니다.

  9. 키오스크에서 테스트 카드를 인코딩합니다.

재시작이 효과적인 이유

네트워크 순간 끊김이나 긴 유휴 기간 후에 인코더 서비스가 물리 인코더와의 연결을 잃을 수 있습니다. 서비스를 중지했다가 다시 시작하면 링크를 다시 맺게 됩니다.

Saflok 첫 키카드가 없어 중복 키카드를 만들 수 없음​

보이는 현상: AVA에 "Please create a new keycard first, then use Duplicate for any extra cards."가 표시됩니다.

이유: Saflok이 해당 예약에 대한 활성 등록 또는 키카드 레코드를 찾지 못했습니다. 중복 카드는 AVA가 추가 카드를 만들기 전에 먼저 성공한 첫 키카드가 있어야 합니다.

해결:

  1. 예약의 첫 키카드를 만듭니다.
  2. 첫 인코딩이 성공적으로 완료될 때까지 기다립니다.
  3. 첫 키카드가 생긴 뒤에만 Duplicate를 선택합니다.
  4. 오류가 다시 나오면 예약에 Ambiance의 활성 등록이 여전히 있는지 확인합니다.
  5. 중복 요청을 다시 시도합니다.
보이면 안 되는 것

메시지에 원시 ReservationNotFound 또는 SOAP fault 세부 정보가 보이면 안 됩니다.

Saflok/Ambiance 다중 객실 키카드에는 객실 수준 예약 ID가 필요함​

보이는 현상: 다중 객실 숙박의 한 객실에 대한 카드를 인코딩하려고 하면 AVA가 흐름을 멈춥니다.

이유: Saflok/Ambiance의 중복 카드는 선택한 객실의 하위 예약 ID를 사용합니다. 그 객실에 아직 고유 ID가 없으면 즉시 실패 오류가 표시됩니다.

해결:

  1. 예약을 열고 원하는 정확한 객실 행을 선택합니다.
  2. 객실이 방금 분리되거나 이동된 경우 PMS 동기화를 기다립니다.
  3. 그 객실이 PMS에서 자체 하위 예약으로 존재하는지 확인합니다.
  4. 다시 Encode Keycard를 시도합니다.

인코더에 활성 세션이 없음​

보이는 현상: AVA에 "The keycard encoder is temporarily offline. Please approach the Front Desk for assistance."가 표시됩니다.

이유: 현재 인코더에 활성 세션이 없습니다. AVA는 이를 오프라인 준비 상태 문제로 처리합니다.

해결:

  1. 인코더의 전원이 켜져 있고 연결되어 있는지 확인합니다.
  2. Settings → Room Access → Keycard Encoding을 새로고칩니다.
  3. 인코더가 Online 또는 Connected로 표시되는지 확인합니다.
  4. 세션이 다시 연결된 뒤 인코딩을 다시 시도합니다.
  5. 그래도 실패하면 다른 인코더를 사용하거나 지원팀에 문의합니다.

모달에 원시 room-access 페이로드가 표시됨​

보이는 현상: 모달에 DoorLock generate fail! 또는 internal error 같은 원시 텍스트가 표시됩니다.

이유: AVA가 기술적인 room-access blob을 잡았습니다. 이제 원시 페이로드를 보여 주는 대신 일반 재시도 메시지로 되돌아갑니다.

해결:

  1. 모달을 닫습니다.
  2. 몇 초 기다립니다.
  3. 키카드를 다시 인코딩합니다.
  4. 같은 메시지가 계속 나오면 인코더가 온라인인지 확인합니다.
  5. 여전히 실패하면 다른 인코더로 전환하거나 지원팀에 문의합니다.

Saflok 자격 증명이 제공되지 않음​

보이는 현상: 키카드 인코딩 중 "UserCredentialsNotProvided.NotApplicable"가 표시됩니다.

해결:

  1. Settings → Room Access → Keycard Encoding으로 이동합니다.
  2. Encoder Type을 Saflok으로 설정합니다.
  3. Encoder Credentials에 Username과 Password를 입력합니다.
  4. 직접 통신이 켜져 있으면 PMSI Server URL도 입력합니다.
  5. Save를 클릭합니다.
  6. Test Connection을 클릭한 뒤 테스트 카드를 하나 인코딩합니다.

인코더 유형 변경이 유지되지 않음​

보이는 현상: 한 인코더 유형을 선택했지만 다른 인코더가 계속 활성 상태입니다.

해결:

  1. Settings → Room Access → Keycard Encoding으로 이동합니다.
  2. Keycard Encoder Settings에서 원하는 인코더 유형을 선택합니다.
  3. 한 번만 Save를 클릭하고 성공 메시지를 기다립니다.
  4. 페이지를 새로고치고 해당 인코더 유형만 활성 상태인지 확인합니다.
  5. 문제가 반복되면 유형을 바꾸고 저장한 뒤, 다시 원래 유형으로 바꿔 저장합니다.

PMS 인코더 검색 결과가 없음​

보이는 현상: Load Encoders를 클릭했지만 AVA에 PMS 단말이 표시되지 않습니다.

이유: PMS 공급업체 설정이 숙소와 맞지 않거나, PMS가 인코더 단말을 노출하지 않습니다.

해결:

  1. Settings → Room Access → Keycard Encoding으로 이동합니다.
  2. PMS vendor가 숙소와 일치하는지 확인합니다.
  3. 다시 Save를 클릭합니다.
  4. Physical Encoder Devices로 돌아가 Load Encoders를 클릭합니다.
  5. 목록이 여전히 비어 있으면 PMS 연동이 활성 상태인지 확인합니다.
  6. PMS가 여전히 단말을 노출하지 않으면 공급업체 이름과 숙소 이름을 포함해 지원팀에 문의합니다.

PMS 카드 읽기를 사용할 수 없음​

보이는 현상: Entitlements에 Start scanning이 표시되지 않거나 실제 키카드 읽기를 사용할 수 없다고 표시됩니다.

이유: 읽기가 비활성화되어 있거나, PMS 어댑터가 지원하지 않거나, 기능 조회를 일시적으로 사용할 수 없습니다. PMS 카드 읽기에는 활성 PMS 인코더도 필요합니다.

해결:

  1. Settings → Room Access → Keycard Encoding으로 이동합니다.
  2. PMS Integration을 선택합니다.
  3. Enable PMS Encoder Integration이 켜져 있는지 확인합니다.
  4. PMS 공급업체가 숙소와 일치하는지 확인합니다.
  5. 검색된 인코더가 Active인지 확인합니다.
  6. Enable physical keycard reading을 켠 다음 Save를 클릭합니다.
  7. Entitlements를 다시 로드하고 Start scanning이 표시되는지 확인합니다.
  8. 읽기를 사용할 수 없는 동안에는 Look up by room 또는 Look up by confirmation number를 사용합니다.

PMS 카드 읽기는 PMS 전송을 직접 사용합니다. Universal Encoder Agent 세션은 필요하지 않습니다. 경고가 계속 표시되면 PMS 어댑터가 아직 읽기 지원을 알리지 않는 것일 수 있습니다.

Opera 라우트가 모호하거나 불완전함​

보이는 현상: 인코더를 로드한 후에도 Opera 카드 읽기를 사용할 수 없습니다.

이유: Opera가 중복되거나 불완전한 워크스테이션, 인코더, 인터페이스 또는 outbound-code 세부 정보를 반환했습니다. AVA는 잘못된 Door Lock 라우트로 카드 읽기를 보내지 않도록 실패를 안전하게 처리합니다.

해결:

  1. Settings → Room Access → Keycard Encoding으로 이동합니다.
  2. PMS vendor가 Opera인지 확인합니다.
  3. 원하는 인코더가 Active인지 확인합니다.
  4. Load Encoders를 클릭한 다음 올바른 단말이 표시되면 Add Selected를 클릭합니다.
  5. Opera 관리자에게 중복되거나 누락된 Door Lock 인터페이스 세부 정보를 수정해 달라고 요청합니다.
  6. 인코더 카탈로그가 수정되면 Entitlements를 다시 로드합니다.
  7. 그동안 Look up by room 또는 Look up by confirmation number을 사용합니다.

Opera에서 정확한 단일 라우트를 확인한 후에도 라우트를 사용할 수 없으면 지원팀에 문의합니다.

Opera 인터페이스 검증 오류​

보이는 현상: 카드 읽기에 OPERAWS-FOF01920 또는 인터페이스 번호 검증 오류가 표시됩니다.

이유: Opera가 요청의 인터페이스 값을 거부했습니다. 인코더 세부 정보가 변경된 후 이전 라우트가 캐시되어 있으면 이런 일이 발생할 수 있습니다.

해결:

  1. Settings → Room Access → Keycard Encoding으로 이동합니다.
  2. Opera 인코더의 워크스테이션과 인코더 ID가 실제 장치와 일치하는지 확인합니다.
  3. Load Encoders를 클릭한 다음 현재 단말에 대해 Add Selected를 클릭합니다.
  4. 인코더가 Active인지 확인합니다.
  5. Entitlements를 다시 로드한 다음 Start scanning을 다시 시도합니다.
  6. 스캔이 계속 실패하면 Look up by room 또는 Look up by confirmation number을 사용합니다.

AVA는 SL01 같은 값을 사용해 Door Lock 라우트를 선택합니다. 실제 읽기에는 라우트의 숫자 outbound code를 사용합니다. 인터페이스 값을 직접 변환하거나 수정하지 마세요.

현재 인코더를 다시 로드한 후에도 OPERAWS-FOF01920이 반환되면 지원팀에 문의합니다.

Opera Door Lock System 시간 초과​

보이는 현상: 카드 읽기에 OPERAWS-FOF00199 또는 Door Lock System 시간 초과가 표시됩니다.

이유: Opera는 요청을 수락했지만 구성된 Door Lock System에 연결할 수 없습니다. 이는 카드 누락 결과가 아니라 운영상의 연결 문제입니다.

해결:

  1. Saflok 인터페이스와 인코더의 전원이 켜져 있는지 확인합니다.
  2. 숙소 네트워크가 Door Lock System에 연결되는지 확인합니다.
  3. Opera Door Lock 인터페이스가 온라인인지 확인합니다.
  4. 카드를 다시 넣고 Start scanning을 한 번 시도합니다.
  5. 인터페이스가 오프라인인 동안에는 Look up by room 또는 Look up by confirmation number을 사용합니다.
  6. Opera 관리자에게 Door Lock System과 인코더 연결을 확인해 달라고 요청합니다.

이 오류를 No card detected로 처리하지 마세요. 인터페이스가 온라인인데도 계속 시간 초과되면 지원팀에 문의합니다.

지원되지 않는 카드 유형​

보이는 현상: AVA에 카드 유형이 지원되지 않거나 인식되지 않는다고 표시됩니다.

이유: 카드가 삽입되어 있지만 이 인코더가 유형을 인식하지 못합니다. 카드가 없는 경우와는 다릅니다.

해결:

  1. 인코더에서 카드를 제거합니다.
  2. 이 인코더에 승인된 카드 유형을 사용하는지 확인합니다.
  3. 지원되는 빈 카드를 인코더에 놓습니다.
  4. 키카드를 다시 인코딩합니다.
  5. 메시지가 다시 표시되면 관리자에게 인코더와 카드 설정을 확인해 달라고 요청합니다.

AVA가 지원되지 않는 카드 유형을 식별한 경우 카드를 계속 위치 조정하지 마세요.

카드를 읽을 수 없음​

보이는 현상: AVA에 카드를 읽을 수 없거나 카드 읽기가 실패했다고 표시됩니다.

이유: 카드가 삽입되어 있지만 인코더가 데이터를 읽지 못합니다. 카드가 손상되었거나 호환되지 않거나 잘못 놓였을 수 있습니다.

해결:

  1. 인코더에서 카드를 제거합니다.
  2. 카드에 눈에 보이는 손상이 있는지 확인합니다.
  3. 올바른 면이 위를 향하도록 카드를 다시 넣습니다.
  4. 오류가 다시 표시되면 지원되는 다른 카드를 시도합니다.
  5. 알고 있는 여러 카드도 읽지 못하면 지원팀에 문의합니다.

카드가 감지되지 않음​

보이는 현상: PMS 카드 스캔을 시작한 후 AVA가 카드가 감지되지 않았다고 보고합니다.

이유: 리더가 인코더에서 카드를 찾지 못했습니다. 지원되지 않는 카드 유형 또는 읽을 수 없는 카드와는 다릅니다.

해결:

  1. 리더에서 카드를 제거합니다.
  2. 올바른 면이 위를 향하도록 카드를 다시 넣습니다.
  3. 리더가 완료될 때까지 기다린 다음 스캔을 다시 시도합니다.
  4. 카드가 계속 읽히지 않으면 Look up by room 또는 Look up by confirmation number을 사용합니다.
  5. 알고 있는 여러 카드에서도 카드 없음이 반환되면 지원팀에 문의합니다.

Opera 카드 읽기에 일반 오류가 표시됨​

보이는 현상: Opera가 HTTP 200을 반환한 후 AVA에 일반 PMS 키카드 읽기 실패가 표시됩니다.

이유: Opera는 이전 유효성 필드 대신 출발 날짜와 시간 범위를 반환할 수 있습니다. AVA는 비어 있지 않은 범위를 허용하고 그 종료 시간을 카드 체크아웃 시간으로 사용합니다. 비어 있거나 형식이 잘못된 범위는 계속 유효하지 않은 것으로 처리됩니다.

해결:

  1. 카드가 Opera에서 인코딩되었고 예상한 예약에 속하는지 확인합니다.

  2. 카드를 다시 넣고 Start scanning을 다시 선택합니다.

  3. AVA가 객실 없이 카드를 읽으면 Look up by room 또는 Look up by confirmation number을 사용합니다.

  4. 일반 오류가 계속되면 수동 조회를 사용하고 Opera 관리자에게 카드 데이터를 확인해 달라고 요청합니다.

  5. 스캔 시각, 숙소, 인코더 이름을 포함해 지원팀에 문의합니다.

    ✓ 유효한 Opera 카드는 Opera가 객실을 포함하지 않아도 읽은 데이터로 표시되어야 합니다.

PMS 키오스크 인코더 매핑을 확인하지 못함​

보이는 현상: Physical Encoder Devices에 인코더가 표시되지만 PMS 키오스크에서 카드를 인코딩할 수 없습니다.

이유: 키오스크의 Device Model 매핑과 기존 키오스크 매핑에서 서로 다른 레이블을 사용할 수 있습니다. AVA는 먼저 Device Model 매핑을 사용하고, 이후 기존 매핑으로 대체합니다.

해결:

  1. Settings → Kiosk → Device Routing으로 이동합니다.

  2. 영향을 받는 키오스크를 찾아 대상 인코더 매핑을 확인합니다.

  3. Settings → Room Access → Keycard Encoding으로 이동합니다.

  4. Physical Encoder Devices에서 일치하는 PMS 인코더가 Active인지 확인합니다.

  5. 대상이 변경되었다면 인코더의 현재 PMS 이름으로 매핑을 저장합니다.

  6. 키오스크에서 테스트 카드 한 장을 다시 인코딩합니다.

    ✓ AVA가 키오스크를 활성 PMS 인코더로 확인하고 요청을 전송해야 합니다.

인코더가 Physical Encoder Devices에 없으면 PMS 인코더 검색 결과가 없음을 따릅니다.

Be-Tech 연결 테스트 실패​

보이는 현상: Test Connection이 실패하거나 버튼이 계속 비활성화됩니다.

직접 Base URL을 의도적으로 구성했거나 일반적인 Be-Tech 요청 실패가 보일 때 이 항목을 사용합니다. 클라이언트 프로그램 메시지가 보이면 Be-Tech 클라이언트 프로그램을 사용할 수 없음을 사용하세요.

Be-Tech 연결 가능 여부 확인

AVA는 일부 Be-Tech 배포에서 확인 메서드를 지원하지 않으므로 405 응답을 연결 가능으로 처리합니다. 401, 404, 5xx 응답은 사용할 수 없는 상태로 처리합니다.

해결:

  1. Base URL이 http:// 또는 https://로 시작하는지 확인합니다.
  2. Be-Tech 서비스가 인코더 워크스테이션에서 실행 중인지 확인합니다.
  3. 워크스테이션과 키오스크가 같은 네트워크에 있는지 확인합니다.
  4. Windows Agent를 사용하는 경우 에이전트 카드가 Connected인지 확인합니다.
  5. Hotel Name, Chain No, Workstation, Reader No를 다시 입력합니다.
  6. Test Connection을 다시 클릭합니다.

Be-Tech 클라이언트 또는 서비스가 재시작이나 수동 중지 후 중지됨​

보이는 현상: Windows 재시작 또는 수동 중지 후 Be-Tech 클라이언트나 서비스가 중지되어 있습니다. AVA에 인코더를 잠시 사용할 수 없다고 표시될 수 있습니다.

이유: Be-Tech 클라이언트는 Windows Agent와 별도로 시작될 수 있습니다. 이제 트레이가 설치된 클라이언트를 감지하고 서비스를 자동으로 복구합니다.

해결:

  1. 인코더 컴퓨터에서 Windows Agent 서비스를 실행 상태로 유지합니다.
  2. 트레이에 Be-Tech 복구 알림이 표시될 때까지 잠시 기다립니다.
  3. Be-Tech 클라이언트 서비스가 다시 실행 중이라는 알림이 표시될 때까지 기다립니다.
  4. Settings → Room Access → Keycard Encoding을 새로고칩니다.
  5. 에이전트와 인코더가 Connected 또는 Online으로 표시되는지 확인합니다.
  6. 키카드 작업을 다시 시도합니다.
자동 재시도

복구에 실패하면 트레이가 자동으로 다시 시도합니다. 복구가 계속 실패할 때만 트레이의 Restart 작업을 사용합니다.

호텔에 Be-Tech 설치가 여러 개 있으면 배포 관리자에게 BETECH_CLIENT_PATH를 문의합니다. 이 경로는 신뢰할 수 있는 Program Files 설치를 가리켜야 합니다.

Be-Tech 클라이언트 프로그램을 사용할 수 없음​

보이는 현상: AVA에 "Make sure the Be-Tech client program is running on the encoder computer."가 표시됩니다.

이유: Windows Agent가 Be-Tech의 벤더 비가용 502 응답을 반환했습니다. AVA는 이제 그 경우를 위한 직접 메시지를 표시합니다.

해결:

  1. 인코더 컴퓨터로 이동합니다.
  2. Be-Tech 클라이언트 프로그램이 실행 중인지 확인합니다.
  3. 중지되어 있으면 클라이언트 프로그램을 다시 시작합니다.
  4. 클라이언트 프로그램이 이미 실행 중이면 Windows Agent를 다시 시작합니다.
  5. Test Connection을 다시 클릭합니다.
다른 Be-Tech 실패

Be-Tech request failed가 보이면 Be-Tech 연결 테스트 실패를 따르세요. 직접 클라이언트 프로그램 메시지는 502 벤더 비가용 응답에만 적용됩니다.

GreatLocks 연결 테스트 실패​

보이는 현상: GreatLocks 서버 세부 정보를 편집한 뒤 Test Connection이 실패합니다.

해결:

  1. Settings → Room Access → Keycard Encoding으로 이동합니다.
  2. GreatLocks 서버에 XHLSI Server IP Address와 TCP Port가 있는지 확인합니다.
  3. 다시 Save를 클릭합니다.
  4. 이전 설정을 업데이트한 경우 기존 서버 레코드를 유지합니다.
  5. 다시 Test Connection을 클릭합니다.

GreatLocks 인코더 선택이 필요함​

보이는 현상: GreatLocks 상태 또는 구성 작업에서 인코더를 선택하라는 메시지가 표시됩니다.

이유: 각 Universal Encoder Agent는 하나의 GreatLocks 인코더를 제공합니다. 여러 서버 또는 에이전트를 사용할 수 있을 때 AVA는 대상을 안전하게 선택할 수 없습니다.

해결:

  1. Settings → Room Access → Keycard Encoding으로 이동합니다.
  2. Physical Encoder Devices를 엽니다.
  3. 각 GreatLocks 행에 정확히 하나의 Encoder ID가 있는지 확인합니다. 실제 인코더마다 서로 다른 ID를 사용합니다.
  4. 필요한 Windows PC에 연결된 인코더를 선택합니다.
  5. 해당 에이전트가 Online인지 확인합니다.
  6. 저장한 다음 상태, 구성 또는 테스트 작업을 다시 실행합니다.
인코더별 상태

각 GreatLocks 인코더는 자체 실시간 상태를 유지합니다. 온라인 에이전트 하나가 다른 인코더를 온라인으로 만들지는 않습니다.

GreatLocks 인벤토리가 로드되지 않음​

보이는 현상: GreatLocks에서 건물, 층, 또는 객실 인벤토리가 비어 있습니다.

이유: GreatLocks 터널이 오프라인이거나 인벤토리 소스에 접근할 수 없습니다.

해결:

  1. Settings → Room Access → Keycard Encoding으로 이동합니다.
  2. GreatLocks 서버 레코드가 저장되어 있는지 확인합니다.
  3. GreatLocks 인코더가 여러 개 있으면 이 인벤토리에 연결된 인코더를 선택합니다.
  4. 해당 인코더의 에이전트 터널이 정상 연결인지 확인합니다.
  5. 다시 Test Connection을 클릭합니다.
  6. 연결이 돌아오면 페이지를 새로고칩니다.

LockSDK Service URL이 필요함​

보이는 현상: 저장이 막히거나 인코더 양식에 "Service URL is required."가 표시됩니다.

해결:

  1. Settings → Room Access → Keycard Encoding으로 이동합니다.
  2. LockSDK를 선택합니다.
  3. Physical Encoder Devices를 열고 인코더를 편집합니다.
  4. http://127.0.0.1:8092 같은 유효한 Service URL을 입력합니다.
  5. Save를 클릭한 뒤 Test Connection을 실행합니다.

LockSDK 에이전트가 등록되지 않음​

보이는 현상: LockSDK 인코더 카드가 Windows Agent에서 Not registered로 표시됩니다.

해결:

  1. Physical Encoder Devices에 LockSDK 인코더가 있는지 확인합니다.
  2. Windows Agent로 이동해 해당 인코더 카드를 찾습니다.
  3. 카드가 새 항목이면 Download Windows Agent를 클릭하고, 이미 있으면 Reinstall을 클릭합니다.
  4. 패키지를 풀고 연결된 Windows PC에서 .bat 파일을 실행합니다.
  5. 상태를 새로고침하고 카드가 Not registered에서 Connected 또는 Not connected로 바뀌는지 확인합니다.
  6. Advanced options는 View Logs, Rotate Secret, Delete에만 사용합니다. Rotate Secret는 현재 에이전트를 분리하기 전에 확인 대화상자를 엽니다.

Heartbeat Monitor가 저장 후 꺼짐​

보이는 현상: Heartbeat Monitor를 켜고 Save를 눌렀는데 다시 꺼집니다.

해결:

  1. Settings → Room Access → Keycard Encoding으로 이동합니다.
  2. Encoding Options → Advanced options를 엽니다.
  3. Heartbeat Monitor를 켭니다.
  4. 한 번만 Save를 클릭하고 성공 메시지를 기다립니다.
  5. 페이지를 새로고치고 Heartbeat Monitor가 여전히 켜져 있는지 확인합니다.
  6. 그래도 꺼지면 호텔 전환 후 설정이 저장되지 않음을 따릅니다.

Heartbeat 실패​

보이는 현상: Heartbeat Monitor가 unreachable로 표시됩니다.

해결:

  1. 키오스크/PC에서 에이전트가 실행 중인지 확인합니다.
  2. Registered Agents에서 온라인 상태와 터널 도달 가능 여부를 확인합니다.
  3. 에이전트 로그에서 오류를 확인합니다.
  4. 필요하면 에이전트를 다시 설치합니다.
상태 의미

Online은 AVA가 인코더와 터널을 확인했음을 의미합니다. Offline은 AVA가 인코더를 사용할 수 없음을 확인했음을 의미합니다. Unknown은 AVA가 인코더 상태를 확인하지 못했음을 의미합니다. Unknown이라고 해서 인코더가 오프라인이라는 뜻은 아닙니다.

인코더 상태가 unknown으로 표시됨​

보이는 현상: 에이전트 세션과 터널은 정상인데 Heartbeat Monitor에 unknown이 표시됩니다.

이유: 선택적 벤더 진단을 사용하지 못할 수 있습니다. 선택적 Saflok Ambiance 자격 증명이 없으면 상태를 확인하지 못할 수 있습니다.

해결:

  1. Registered Agents를 확인하고 에이전트가 연결되어 있는지 확인합니다.
  2. Last Seen이 최근이고 터널에 연결할 수 있는지 확인합니다.
  3. unknown만을 근거로 에이전트를 다시 시작하거나 재설치하지 마세요.
  4. 인코더가 여전히 작동하는지 확인해야 하면 키카드 하나를 테스트합니다.
  5. 상태 오류가 계속되거나 인코딩이 실패하면 지원팀에 문의합니다.

Heartbeat 상태 또는 터널 오류​

보이는 현상: Heartbeat에서 상태 오류 또는 터널 실패가 보고됩니다.

해결:

  1. 전체 메시지를 읽고 인코더 상태 또는 터널 중 무엇을 가리키는지 기록합니다.
  2. status error인 경우 벤더 진단을 확인하고 정확한 메시지를 캡처합니다.
  3. tunnel failure인 경우 에이전트가 실행 중이고 Last Seen이 최근인지 확인합니다.
  4. Settings → Room Access를 새로고치고 상태를 다시 확인합니다.
  5. 오류가 계속되거나 키카드 인코딩이 실패하면 지원팀에 문의합니다.

실시간 인코더 상태가 일치하지 않음​

보이는 현상: 인코더는 구성된 것처럼 보이지만 예약 모달에서는 여전히 사용할 수 없음으로 표시됩니다.

이유: AVA는 에이전트가 연결되어 있고 터널에 도달 가능할 때만 online으로 표시합니다. 이 상태가 이제 동적 인코더 선택에도 사용됩니다.

해결:

  1. Registered Agents에서 인코더 카드를 확인합니다.
  2. 장치가 연결되어 있고 터널이 도달 가능한지 확인합니다.
  3. 먼저 에이전트 또는 네트워크 문제를 해결합니다.
  4. Settings → Room Access를 새로고칩니다.
  5. 인코딩을 다시 시도합니다.
  6. 설정 페이지의 Status: 줄을 다시 확인합니다.

Windows Agent가 너무 오래되어 키카드를 읽을 수 없음​

보이는 현상: Read Keycard가 "This Windows Agent is too old to read keycards. Update the Universal Encoder Agent, then try again."와 함께 실패합니다.

이유: 이전 Universal Encoder Agent 빌드에는 Saflok 읽기 API가 노출되지 않습니다. 그러면 AVA가 에이전트 대신 호텔 PC의 기본 웹 페이지에 접근합니다.

해결:

  1. Settings → Room Access → Keycard Encoding으로 이동합니다.
  2. Windows Agent가 outdated로 표시되면 Reinstall 전에 Update를 클릭합니다.
  3. 에이전트가 다시 연결될 때까지 기다립니다.
  4. Read Keycard를 다시 시도합니다.

인코더 터널이 오프라인임​

보이는 현상: Read Keycard에 "The encoder tunnel is offline. Start the Universal Encoder Agent, then try again."가 표시됩니다.

이유: 인코더 컴퓨터가 Universal Encoder Agent 터널을 통해 AVA에 연결할 수 없습니다. 업데이트가 필요한 오래된 에이전트와는 다른 문제입니다.

해결:

  1. Settings → Room Access → Keycard Encoding으로 이동합니다.
  2. Saflok Windows Agent 카드를 찾습니다.
  3. 인코더 컴퓨터에서 Universal Encoder Agent를 시작합니다.
  4. 에이전트가 Connected로 표시되고 Last Seen 시간이 최근으로 바뀔 때까지 기다립니다.
  5. Read Keycard를 다시 시도합니다.
  6. 에이전트가 계속 오프라인이면 Windows Agent가 연결되지 않음을 따릅니다.

Windows Agent가 연결되지 않음​

보이는 현상: 상태가 Not connected 또는 "Never online"으로 표시됩니다.

해결:

  1. 다운로드한 zip을 열고 download-installer.bat을 실행합니다.
  2. 설치 파일 .exe가 내려받아지면 그 파일을 실행합니다.
  3. Windows PC에 인터넷이 연결되어 있는지 확인합니다.
  4. 필요하면 Windows Agent 카드에서 Reinstall을 클릭합니다.
  5. Be-Tech 설정이면 로컬 어댑터 서비스도 실행 중인지 확인합니다. Be-Tech 상태는 재시작 후 최대 5분까지 걸릴 수 있습니다.
  6. Registered Agents 상태를 새로고칩니다.
  7. Settings → Room Access로 돌아가 **Status:**가 online으로 바뀌는지 확인합니다.
동적 인코더 목록

에이전트가 연결되고 터널에 도달 가능하면 동적 인코더 목록에 Online이 표시되어야 합니다. 하위 인코더 카드가 여전히 오프라인처럼 보이면 페이지를 새로고치고 먼저 에이전트를 확인하세요.

Windows Agent 서비스 작업에 권한 필요​

보이는 현상: Start, Stop, 또는 Restart를 클릭하면 Windows가 관리자 권한을 요청합니다.

이유: 트레이 버튼이 Windows 서비스를 제어하려면 상승 권한이 필요합니다.

해결:

  1. UAC 프롬프트에서 Yes를 클릭합니다.
  2. 관리자 권한이 없으면 관리자에게 승인해 달라고 요청합니다.
  3. 프롬프트를 취소했다면 작업을 다시 시도합니다.

키오스크 라우팅 규칙이 보이지 않음​

보이는 현상: Room Access 아래나 예전 Kiosk to Encoder Routing 섹션에서 라우팅 규칙을 찾을 수 없습니다.

해결:

  1. Settings → Kiosk로 이동합니다.
  2. Device Routing을 엽니다.
  3. 수동 라우팅 규칙을 보이게 하려면 Enable guest selection을 끕니다.
  4. Physical Encoder Devices에 장치를 하나 이상 추가합니다.

아직 막혔나요?​

다음 경우 success@vouch-technologies.com으로 문의하세요.

  • ❌ 전원과 네트워크를 확인한 뒤에도 인코더가 계속 오프라인임
  • ❌ Be-Tech 클라이언트 프로그램이 계속 중지됨
  • ❌ 여러 키오스크에서 카드 인코딩이 실패함
  • ❌ Heartbeat가 30분 이상 비정상 상태임

포함하면 좋은 정보:

  • 인코더 유형과 모델
  • 정확한 Be-Tech 오류 메시지
  • Windows Agent 또는 직접 Base URL 중 무엇을 쓰는지
  • Registered Agents와 Heartbeat Monitor 스크린샷
  • 문제가 시작된 시각