키카드 인코더 문제 해결

빠른 해결

먼저 네트워크와 전원을 확인한 뒤, 단일 카드 인코딩을 다시 시도하세요. 보통 2분이면 끝납니다.

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

빠른 참고

보이는 현상	발생 이유	조치
인코더가 응답하지 않음	전원 또는 네트워크 문제	연결 확인
카드가 인코딩되지 않음	카드 유형 또는 장치 문제	카드와 장치 확인
일반 언어의 키카드 실패 메시지	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 payload가 모달을 통과함	일반 재시도 경로 사용
인코더 유형 변경이 유지되지 않음	이전 저장으로 인해 인코더 상태가 섞임	인코더 유형 다시 저장
"Test Connection" 실패(Be-Tech) 또는 에이전트가 계속 오프라인	Base URL, 어댑터, 서비스 문제	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 재고 동기화 확인
"Service URL is required" (LockSDK)	직접 모드에서 인코더마다 Service URL이 필요함	LockSDK Service URL 추가
LockSDK 에이전트가 Not registered로 표시됨	인코더별 에이전트 장치가 아직 없음	LockSDK 에이전트 등록
Heartbeat Monitor가 저장 후 꺼짐	현재 호텔 세션에서 저장이 유지되지 않음	Heartbeat Monitor 다시 저장
Heartbeat가 unreachable로 표시됨	에이전트 오프라인 또는 터널 문제	에이전트 상태 확인
인코더가 계속 사용할 수 없음	동적 목록이 에이전트를 여전히 연결 끊김으로 봄	실시간 인코더 상태 확인
Windows Agent가 Not connected로 표시됨	에이전트가 실행되지 않거나 설치가 불완전함	에이전트 다시 연결
Windows가 권한을 요청함	트레이 서비스 제어에 권한 상승이 필요함	UAC 프롬프트 승인

인코더가 응답하지 않습니다

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

해결:

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

카드가 인코딩되지 않습니다

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

해결:

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

정규화된 인코딩 실패

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

이유: AVA는 이제 정규화된 Saflok, Be-Tech, Opera, 내부 세션 실패를 먼저 보존한 뒤 화면에 표시합니다. 구조화된 메시지를 우선 사용하고, 필요할 때만 이전 벤더 문자열 파싱으로 되돌아갑니다.

해결:

1. 짧은 메시지를 먼저 읽습니다.
2. 지원 화면에서 userMessage, errorCode, 벤더 이름, 안전한 세부 정보를 찾습니다.
3. 지원팀에 문의할 때 그 정보를 사용합니다.
4. 메시지를 아래의 가장 가능성 높은 해결책과 맞춥니다.
   • Occupied room: 예약을 새로고친 뒤 다시 시도합니다.
   • Encoder offline: 전원, 네트워크, 에이전트 상태를 확인합니다.
   • Failed detect/write: 카드를 다시 넣거나 새 빈 카드를 사용합니다.
   • No active session: 인코더 세션을 다시 연결합니다.
   • Missing mapping: 객실 매핑이 올바른지 확인합니다.
   • Invalid room or date: 숙박 날짜와 객실 배정을 확인합니다.
   • Vendor auth, gateway, or timeout: 벤더 접근을 확인하거나 나중에 다시 시도합니다.
   • Invalid request: 올바른 예약을 다시 열고 재시도합니다.

이전 대체 경로는 계속 사용됩니다

이전 응답은 여전히 레거시 벤더 문자열로 표시될 수 있습니다. AVA는 이 파싱 경로를 유지해 과거 로그와 이전 연동도 계속 올바르게 읽을 수 있게 합니다.

Saflok/Ambiance 인코딩이 작동하지 않습니다

보이는 현상: 키카드 인코딩이 실패하거나 타임아웃되거나, 키오스크가 Saflok/Ambiance 인코더에서 응답이 없다고 보고합니다.

해결: 아래 3가지 확인을 순서대로 진행합니다. 다음 단계로 넘어가기 전에 각 항목이 흔한 원인을 하나씩 배제합니다.

Saflok 자동 복구

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

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

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

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

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

   

4. 에이전트가 Not connected이면 계속하기 전에 Windows Agent not connected를 따릅니다. Saflok PMSI가 아직 시작 중이었다면, 10초 기다린 뒤 한 번 새로고치고 재설치 전 상황을 확인합니다.

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

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

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

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

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

   

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

3. Ambiance Encoder Service 재시작

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

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

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

3. 서비스 목록에서 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 오류 세부 정보가 보이면 안 됩니다.

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 payload가 모달에 표시됩니다

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

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

해결:

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. 문제가 반복되면 유형을 바꾸고 저장한 뒤, 다시 원래 유형으로 돌아가 저장합니다.

Be-Tech 테스트 연결이 실패합니다

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

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

해결:

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 클라이언트 프로그램을 사용할 수 없습니다

보이는 현상: 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 test connection fails를 따릅니다. 직접 클라이언트 프로그램 메시지는 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에서 건물, 층, 객실 재고가 계속 비어 있습니다.

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

해결:

1. Settings → Room Access → Keycard Encoding으로 이동합니다.
2. GreatLocks 서버 레코드가 저장되어 있는지 확인합니다.
3. 에이전트 터널 연결이 정상인지 확인합니다.
4. Test Connection을 다시 클릭합니다.
5. 연결이 복구되면 페이지를 새로고칩니다.

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은 AVA가 현재 에이전트를 분리하기 전에 확인 대화상자를 엽니다.

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. 그래도 꺼지면 Settings Not Saving After Switching Hotels를 따릅니다.

Heartbeat 실패

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

해결:

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

실시간 인코더 상태가 일치하지 않습니다

보이는 현상: 인코더는 설정된 것처럼 보이지만 예약 모달에서는 계속 사용할 수 없음으로 표시됩니다.

이유: AVA는 에이전트가 연결되어 있고 터널에 접근 가능할 때만 online을 표시합니다. 이 상태가 이제 동적 인코더 선택의 기준이 됩니다.

해결:

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

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 클라이언트 프로그램이 계속 중지됨
• ❌ 여러 키오스크에서 카드 인코딩이 실패함
• ❌ 30분 넘게 Heartbeat 상태가 불안정함

포함하면 좋은 정보:

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

관련 안내

• 키카드 인코더 개요
• 키카드 인코더 설정
• Keycard Guest Instructions