FAQ, SDK 및 비용

연동 담당자가 자주 묻는 질문과 SDK 및 API 요금 체계를 안내합니다.

추가 정보

자주 묻는 질문

Cams Biometrics Web API 3.0 연동에 관해 자주 묻는 질문입니다.

일반

Q: Cams Biometric Gateway와 생체인식 API는 무엇인가요?
Cams Biometric Gateway는 모든 웹 애플리케이션이 생체인식 근태 및 출입 통제 장비와 실시간으로 통신할 수 있게 해 주는 생체인식 API를 제공하는 범용 클라우드 플랫폼입니다. 장비 SDK나 고정 IP 없이 콜백(인바운드) API와 RESTful(아웃바운드) API에 걸쳐 38개 오퍼레이션을 지원합니다.
Q: 연동하려면 SDK가 필요한가요?
아니요. Cams는 SDK를 제공하지 않으며 필요로 하지도 않습니다. 모든 통신은 JSON 페이로드를 사용하는 표준 HTTP/HTTPS POST 요청으로 이루어집니다. HTTP 호출을 할 수 있는 언어라면 무엇이든 사용할 수 있습니다.
Q: 어떤 프로그래밍 언어를 지원하나요?
JSON을 담은 HTTP POST를 보내고 받을 수 있는 언어라면 PHP, Python, Java, C#, Node.js, Go, Ruby 등 무엇이든 가능합니다. 7개 언어용 AI 코드 생성 프롬프트를 제공합니다.
Q: Cams Protocol Engine이란 무엇인가요?
생체인식 장비와 사용자 서버 사이에 위치하는 클라우드 미들웨어입니다. 프로토콜 변환, 데이터 정규화, 오프라인 캐싱을 처리하며, 장비 브랜드나 모델에 관계없이 일관된 JSON API를 제공합니다.
Q: API Monitor란 무엇인가요?
API Monitor는 콜백 URL 설정, AuthToken 관리, Security Key 설정, 장비 상태 확인, RESTful 엔드포인트 URL과 Service Tag ID 확인을 할 수 있는 관리자 포털입니다.

장비 호환성

Q: 어떤 생체인식 장비를 지원하나요?
모든 Cams Biometrics 장비(camsbiometrics.com/product에 등록)는 Native Push로 전체 API를 지원합니다. developer.camsbiometrics.com에서 검증된 장비도 Native Push를 완전히 지원합니다.
Q: Cams 장비가 아닌 장비(ZkTeco, eSSL, BioMax 등)도 이 API를 사용할 수 있나요?
네, Protocol Update를 하면 가능합니다. Cams 장비가 아니거나 검증되지 않은 장비는 Hybrid Push로 동작합니다. 연결 모드와 하드웨어 기능에 따라 일부 기능이 제한될 수 있습니다.
Q: Native Push와 Hybrid Push의 차이는 무엇인가요?
Native Push: 제한 없는 전체 API 지원으로 38개 오퍼레이션이 모두 동작합니다. Cams 장비와 검증된 장비에서 사용할 수 있습니다.
Hybrid Push: Cams 장비가 아니거나 검증되지 않은 장비용입니다. 사용 가능한 기능은 통신 모드(SDK, DB 풀, 파일 처리)에 따라 달라집니다. 연결 모드를 참조하세요.
Q: 어떤 생체인식 방식을 지원하나요?
지문, 얼굴 인식, 손바닥 정맥, RFID/근접 카드, 숫자 PIN/비밀번호, 홍채 인식, 체온 측정(장비에 따라 다름).
Q: 사용 중인 장비에서 일부 API 기능이 동작하지 않습니다. 왜 그런가요?
(a) 연결 모드 때문일 수 있습니다 — DB 풀과 파일 처리 모드는 근태 푸시만 지원하며 RESTful API는 지원하지 않습니다. 또는 (b) 하드웨어 제한 때문일 수 있습니다 — 일부 장비 모델은 펌웨어 수준에서 특정 기능을 지원하지 않을 수 있습니다. 사용 중인 하드웨어로 테스트하고 Cams 지원팀에 문의하세요.

콜백 API (장비 → 서버)

Q: 콜백 API란 무엇인가요?
콜백 API는 생체인식 장비의 실시간 이벤트를 사용자 서버로 전달합니다. 기록이 발생하거나 장비에서 사용자가 변경되면 Cams Protocol Engine이 설정된 콜백 URL로 JSON 페이로드를 즉시 POST합니다.
Q: 서버는 무엇으로 응답해야 하나요?
내부 처리가 실패하더라도 항상 HTTP 상태 200과 함께 {"status":"done"}을 반환하세요. Cams Protocol Engine을 절대 블로킹하지 마세요. 무거운 처리는 비동기 실행을 위해 큐에 넣으세요.
Q: 기록이 발생했을 때 서버가 오프라인이면 어떻게 되나요?
Biometric Gateway가 모든 이벤트를 캐시했다가 서버가 다시 온라인이 되면 자동으로 전달합니다. 데이터가 손실되지 않습니다.
Q: 중복 기록은 어떻게 처리하나요?
UserID + LogTime 조합을 사용하여 서버에서 중복 감지 로직을 구현하세요. 오프라인 복구나 네트워크 재시도 중에 동일한 기록이 다시 전송될 수 있습니다.
Q: 어떤 기록 유형을 지원하나요?
CheckIn, CheckOut, BreakOut, BreakIn, OverTimeIn, OverTimeOut, MealIn, MealOut. InputType 필드에는 사용된 생체인식 방식(Fingerprint, Face, Palm, Card, Password)이 표시됩니다.
Q: How do user templates work in Callbacks?
When a user is updated on the device (operations #3–#9), templates may arrive one at a time or in groups across multiple callbacks. Each callback only carries templates that changed — not the full set. Your server must merge/upsert by Type + Index as the unique key. Never overwrite all templates on a single callback.
Q: 근태 사진을 받을 수 있나요?
네. 오퍼레이션 #10 RealTimeAttendancePhoto가 기록 시점에 촬영된 Base64 인코딩 JPEG 스냅샷을 전달합니다. 이는 기록 로그 콜백(#11)과 별개이며 카메라를 지원하는 장비에서 사용할 수 있습니다.
Q: 콜백에 체온과 마스크 감지 정보가 포함되나요?
네, 장비가 지원하는 경우 포함됩니다. PunchLog 객체에는 Temperature(체온 측정값)와 FaceMask(불리언 — 마스크 착용 감지 여부)가 포함됩니다.

RESTful API (서버 → 장비)

Q: RESTful API란 무엇인가요?
RESTful API를 사용하면 서버에서 생체인식 장비로 명령을 보낼 수 있습니다 — 사용자 추가/삭제, 로그 불러오기, 생체 정보 등록, 접근 제어 등입니다. API Monitor 계정에서 확인한 엔드포인트 URL로 JSON을 POST합니다.
Q: RESTful 엔드포인트 URL은 어디서 확인하나요?
API Monitor 계정에 로그인하세요. RESTful 엔드포인트 URL과 Service Tag ID(stgid)가 표시되어 있습니다.
Q: RESTful 명령의 지연 시간은 얼마나 되나요?
약 15초입니다. Biometric Gateway가 명령을 큐에 넣고 장비가 다음에 연결될 때 전달합니다(온라인 장비는 거의 상시 연결되어 있습니다).
Q: LoadLog의 최대 날짜 범위는 얼마인가요?
요청당 최대 30일을 권장합니다. 더 긴 기간은 연속된 기간으로 나누어 여러 번 요청하세요.
Q: 여러 생체 템플릿을 가진 사용자를 한 번에 추가할 수 있나요?
네. Template 배열에는 여러 항목을 넣을 수 있습니다. 예를 들어 오퍼레이션 #27은 Card + Fingerprint + Password + Face + Palm + UserPhoto를 가진 사용자를 한 번의 요청으로 추가합니다.
Q: RESTful 명령을 보냈을 때 장비가 오프라인이면 어떻게 되나요?
Biometric Gateway가 명령을 큐에 넣고 장비가 다시 연결되면 자동으로 전달합니다. 제한 시간 내에 장비가 응답하지 않으면 상태 코드 5(Device Offline)를 받게 됩니다.
Q: 명령 결과는 어떻게 확인하나요?
RESTful 응답에는 StatusCode 필드가 포함됩니다. 코드 0은 성공을 의미합니다. 전체 오류 코드와 의미는 응답 상태 코드를 참조하세요.
Q: 지문 등록을 원격으로 시작할 수 있나요?
네. 오퍼레이션 #35 EnrollFingerPrint가 장비에서 등록 세션을 시작합니다. 다만 손가락을 스캔하려면 사용자가 장비 앞에 직접 있어야 합니다.

보안 및 네트워킹

Q: 콜백에 HTTPS를 사용할 수 있나요?
네. 443번 포트에서 유효한 SSL 인증서를 사용하는 HTTPS를 완전히 지원하며 운영 환경에 권장합니다.
Q: 암호화는 필수인가요?
아니요. AES-256 암호화는 선택 사항입니다. 활성화하려면 API Monitor에서 Security Key를 설정하세요. 활성화하면 모든 JSON 페이로드가 Base64 인코딩과 함께 AES/ECB/PKCS5PADDING으로 암호화/복호화됩니다.
Q: 콜백이 정말 Cams에서 온 것인지 어떻게 검증하나요?
모든 콜백에는 AuthToken 필드가 포함됩니다. 이를 API Monitor에 설정한 토큰과 비교하고, 일치하지 않는 요청은 거부하세요.
Q: 어떤 포트를 열어야 하나요?
운영 환경에서는 80번(HTTP) 또는 443번(HTTPS) 포트를 사용합니다. 8123번 포트는 테스트 전용입니다. 지원 포트를 참조하세요.
Q: 서버에 배포하지 않고 로컬에서 테스트하려면 어떻게 하나요?
공인 IP와 포트 포워딩, 또는 ngrok 같은 터널링 도구를 사용하세요. 단계별 안내는 로컬 테스트를 참조하세요.

데이터 및 설계 고려 사항

Q: API는 어떤 데이터 형식을 사용하나요?
모든 요청과 응답은 UTF-8 인코딩의 raw JSON입니다. Content-Type: application/json 헤더를 사용하세요. 폼 인코딩은 사용하지 않습니다.
Q: 어떤 타임스탬프 형식을 사용하나요?
YYYY-MM-DD HH:mm:ss GMT +OFFSET(예: 2020-09-17 07:48:22 GMT +0530)입니다. Time 필드는 UTC이며, 장비 로컬 타임스탬프(LogTime, OperationTime 등)는 다른 시간대 오프셋을 사용할 수 있습니다.
Q: 오프라인 기록과 소급 데이터는 어떻게 처리해야 하나요?
시간 순서와 다르게 도착하는 기록도 수용하도록 애플리케이션을 설계하세요. 장비가 오프라인이었다면 다시 연결된 후 캐시된 기록을 푸시합니다. 근태 상태를 소급하여 업데이트해야 할 수도 있습니다(예: "결근"으로 표시된 사용자를 "출근"으로 변경).
Q: 사용자가 여러 장비를 사용하는 경우 IN/OUT은 어떻게 판단하나요?
사용자의 모든 기록을 전체 장비에 걸쳐 LogTime 기준으로 정렬한 다음 업무 로직을 적용하세요. 사용자가 서로 다른 장비에서 기록하는 경우 단일 장비의 Type 필드(CheckIn/CheckOut)에만 의존하지 마세요.
Q: OperationID란 무엇이며 어떻게 사용해야 하나요?
각 오퍼레이션의 고유한 문자열 식별자입니다. 인바운드 콜백의 경우 Biometric Gateway가 생성합니다. 아웃바운드 RESTful 요청의 경우 요청마다 고유한 값(UUID 또는 타임스탬프 기반)을 생성하세요. 응답이 같은 값을 그대로 반환하므로 요청과 응답 쌍을 대응시킬 수 있습니다.
Q: 생체 템플릿은 어떻게 저장되고 전송되나요?
생체 데이터(지문, 얼굴, 손바닥, 사용자 사진)는 Template 객체의 Data 필드에 Base64로 인코딩됩니다. 지문과 얼굴 템플릿에는 Size(바이트 길이)와 Index(슬롯 번호)도 포함됩니다. 카드 번호와 PIN은 일반 문자열입니다.

요금 및 라이선스

Q: API 라이선스는 어떻게 부여되나요?
생체인식 장비 1대당 부여됩니다. 첫해에는 API Activation + 연간 라이선스가 필요하고, 이후에는 연간 라이선스 갱신만 필요합니다. 요금은 API 비용을 참조하세요.
Q: API 라이선스가 만료되면 어떻게 되나요?
라이선스가 갱신될 때까지 해당 장비의 API 통신이 중단됩니다. 기존 데이터에는 영향이 없지만 새로운 콜백이나 RESTful 명령은 처리되지 않습니다.
Q: 온프레미스 옵션이 있나요?
네. Protocol Engine Lite를 사용자의 서버(Windows/Linux)에 설치하여 LAN 전용 또는 자체 호스팅 환경에서 사용할 수 있습니다. 자세한 내용은 sales@camsbiometrics.com으로 문의하세요.
추가 정보

생체인식 근태 SDK

Cams는 기존 방식의 SDK를 제공하지 않습니다. 모든 오퍼레이션은 표준 HTTP 콜백 및 RESTful API를 사용하므로 라이브러리 설치가 필요 없습니다.

SDK가 필요 없습니다. 통신은 콜백 URL과 RESTful HTTP 엔드포인트를 사용하는 Cams Protocol Engine을 통해서만 이루어집니다.

덕분에 모든 웹 플랫폼과 간단하게 연동할 수 있습니다:

OpenERPERPNextZoho PeopleSAPTallyHRAPPOdoo맞춤형 웹 앱
추가 정보

API 비용

API 라이선스는 생체인식 장비 1대당 청구됩니다. 첫해 = 활성화 + 라이선스, 이후 = 라이선스 갱신만.

서비스USD비고
Native Push — Cams 및 검증된 장비
API Activation$120장비당 1회.
연간 API 라이선스$60 – $120매년 갱신이 필요합니다.
Protocol Update (Cams 장비 아님)$120 – $2801회. Cams 장비가 아닌 장비에서 Cams 프로토콜을 활성화합니다.
Hybrid Push — ZKTeco, eSSL 및 모든 타사 브랜드
API Activation$150장비당 1회.
연간 API 라이선스$90 – $150매년 갱신이 필요합니다.
Hybrid Connector (미검증)$150 – $3001회. Hybrid Push를 사용하는 미검증 장비에 필요합니다.
하드웨어 및 기타
하드웨어$220 – $720모델에 따라 다릅니다.
Protocol Engine Lite(온프레미스) — LAN 전용 또는 자체 호스팅 환경용. 비용: $500–$10,000. 자세한 내용은 영업팀에 문의하세요.