소개
Cams Biometric Gateway — Web API 3.0
The Cams Biometric Gateway is the universal Biometric API that connects any biometric attendance or access control machine with your application — ERP, HRMS, payroll, school management, custom software, or AI/automation workflow. It supports all major device brands and provides a standardised JSON-over-HTTP Biometric API regardless of the hardware.
38개 오퍼레이션 — 콜백 API 11개(장비 → 서버)와 RESTful API 27개(서버 → 장비). 모든 페이로드는 HTTP/HTTPS 상의 raw JSON입니다.
모든 생체인식 장비를 지원합니다. Cams 장비, 검증된 장비, 타사 브랜드(ZKTeco, Suprema, Hikvision, Anviz, Morpho/IDEMIA, Virdi, Mantra, Nitgen, Realtime/Startek, Biomax, Secugen, eSSL, Matrix COSEC 등)를 지원합니다. 사용 환경에 맞는
연결 모드를 선택하세요.
작동 방식
Biometric Gateway는 다음으로 구성됩니다.
게이트웨이 서버Cams Protocol Engine(프로토콜 변환, 데이터 정규화, 오프라인 캐싱, 인증)과 애플리케이션에 일관된 인터페이스를 제공하는 표준화 API 계층을 포함하는 클라우드 호스팅 플랫폼입니다.
Protocol Engine게이트웨이 서버의 핵심 엔진으로, 생체인식 장비와 통신하고 제조사별 프로토콜을 변환하며 안전한 데이터 트랜잭션 로깅과 ID 관리를 처리합니다.
Protocol Engine Lite사용자의 서버(Windows/Linux)에 설치할 수 있는 온프레미스 버전으로, LAN 전용 또는 자체 호스팅 환경에 적합합니다. API는 동일하며 로컬에 배포합니다.
연동 대상
OdooERPNextSAPMicrosoft Dynamics
ZohoBitrix24
OrangeHRMBayZatPalmHRuKnowva
FedenaTeachmintEduBricz
RazorPayPayruler
n8nMakeZapier
Claude (MCP)GeminiChatGPT
맞춤형 웹 앱
사용자의 애플리케이션
ERP
HRMS
급여
학교 ERP
AI 워크플로 (n8n, Zapier)
MCP — Claude · Gemini · ChatGPT
맞춤형 앱
Protocol Engine
보안 인증 처리
데이터 트랜잭션 로깅
프로토콜 변환
오프라인 캐시 & 큐
AES-256 암호화 · 인증 토큰 검증
표준화 API 계층
ID 관리
AI / MCP 연동
콜백 디스패처
REST 명령 라우터
데이터 정규화 · 다중 브랜드 프로토콜 지원
지문
·
얼굴 인식
·
손바닥 정맥
·
RFID 카드
·
PIN
·
QR / 바코드
·
GPS 추적
생체인식 장비 — 모든 브랜드 지원
Cams
ZKTeco
Suprema
Hikvision
Anviz
Morpho / IDEMIA
Virdi
Mantra
Nitgen
Realtime
Biomax
Secugen
eSSL
Matrix
+ 기타 다수
| API 유형 | 방향 | 지연 시간 | 사용 사례 |
|---|
| 콜백 API | 장비 → 사용자 서버 | 실시간 / 지연 없음 | 근태 기록 및 사용자 동기화 이벤트 수신 |
| RESTful API | 사용자 서버 → 장비 | 약 15초 | 사용자 추가/삭제, 로그 불러오기, 생체 정보 등록 |
소개
시작하기
세 단계로 연동할 수 있습니다. 콜백을 수신하려면 서버에 외부에서 접근 가능한 URL이 필요합니다.
1
콜백 URL 설정
API Monitor 포털에 로그인하여 서버의 공개 HTTPS URL을 장비의 콜백 URL로 설정합니다. API 엔진이 생체인식 이벤트를 이 엔드포인트로 실시간 POST합니다.
2
근태 기록 수신
엔드포인트는 raw JSON 본문이 담긴 POST를 수신합니다. 콜백 API에는 쿼리 매개변수가 필요하지 않습니다. AuthToken을 검증하고 기록 데이터를 파싱한 뒤 {"status":"done"}으로 응답하세요.
3
RESTful API로 사용자 및 장비 관리
API Monitor 계정에 제공된 RESTful 엔드포인트 URL로, stgid(Service Tag ID)를 쿼리 매개변수로 붙여 JSON 명령을 POST합니다. 엔진이 명령을 큐에 넣고, 장비는 약 15초 이내에 응답합니다.
엔드포인트 형식
| API 유형 | 메서드 | 전송 방법 |
|---|
| 콜백 API(인바운드) |
POST |
장비가 사용자가 설정한 URL로 POST합니다. raw JSON 본문이며 매개변수는 없습니다. |
| RESTful API(아웃바운드) |
POST |
RESTful 엔드포인트 URL(API Monitor 계정에서 확인)로 ?stgid=YOUR_SERVICE_TAG_ID와 raw JSON 본문을 붙여 POST합니다. |
콜백 요청에는 항상 즉시 응답하세요. 수신을 확인하려면 서버가 {"status":"done"}(HTTP 200)을 반환해야 합니다. 응답하기 전에 무거운 처리를 하지 말고 큐에 넣으세요.
문서
API 문서
레퍼런스는 주제별로 나뉘어 있습니다. 먼저 장비 호환성을 확인한 다음 콜백 및 REST 오퍼레이션을 살펴보세요.
지원 장비 및 연결 모드게이트웨이가 지원하는 장비, 각 장비의 연결 방식(Native Push 또는 Hybrid Push), 그리고 모드별로 사용할 수 있는 API 오퍼레이션을 설명합니다.
API 레퍼런스: 아키텍처, 필드, 상태 코드모든 오퍼레이션이 공통으로 사용하는 구성 요소: 요청 흐름, 공통 JSON 필드, 템플릿 유형, 상태 코드, 포트, 페이로드 암호화.
콜백 API: 장비에서 서버로 전달되는 실시간 이벤트장비가 콜백 URL로 보내는 모든 이벤트와 서버가 수신하는 JSON, 그리고 서버가 반환해야 하는 응답을 설명합니다.
RESTful API: 서버에서 장비로 보내는 명령서버가 게이트웨이를 통해 장비로 보내는 명령과 각 명령의 요청 및 응답 JSON을 설명합니다.
API 로컬 테스트배포하기 전에 개발 PC에서 장비 콜백을 수신하고 Postman으로 REST 명령을 테스트하는 방법을 설명합니다.
PHP 예제: 생체인식 근태 데이터를 MySQL에 저장근태 기록을 MySQL에 저장하는 PHP 콜백 핸들러의 동작 예제를 세 단계로 소개합니다.
AI 코드 생성 프롬프트프롬프트를 AI 어시스턴트에 복사하여 사용 중인 기술 스택에 맞는 연동 코드를 생성하세요.
FAQ, SDK 및 비용연동 담당자가 자주 묻는 질문과 SDK 및 API 요금 체계를 안내합니다.
