API 레퍼런스: 아키텍처, 필드, 상태 코드

모든 오퍼레이션이 공통으로 사용하는 구성 요소: 요청 흐름, 공통 JSON 필드, 템플릿 유형, 상태 코드, 포트, 페이로드 암호화.

API 레퍼런스

API 아키텍처

항목	콜백 API	RESTful API
시작 주체	장비 / Biometric Gateway	사용자 서버
방향	장비 → 사용자 서버	사용자 서버 → 장비
지연 시간	실시간 (밀리초)	약 15초
트리거	장비에서 발생한 생체인식 이벤트	사용자 코드에서 보내는 HTTP POST
사용자의 역할	수신 후 응답	명령 전송 후 응답 폴링/대기
응답 본문	`{"status":"done"}`	`{"Status":"done","OperationID":"…","StatusCode":0}`
오프라인 시 동작	엔진이 캐시하고 서버가 다시 온라인이 되면 전달	엔진이 큐에 보관하고 장비가 다시 연결되면 전달

API 레퍼런스

공통 필드

콜백과 RESTful의 모든 요청은 다음 최상위 필드를 공통으로 사용합니다.

AuthTokenString. 특정 장비의 요청을 식별하고 인증하는 32자리 토큰입니다. API Monitor 포털에서 설정합니다. 수신하는 모든 콜백에서 이 값을 검증하세요.

OperationIDString. 이 오퍼레이션 인스턴스를 고유하게 식별하는 ID입니다(예: "j95xfejt3vr1"). RESTful 응답은 동일한 OperationID를 반환하므로 요청과 응답을 매칭할 수 있습니다.

TimeString. 이벤트가 처리된 시각의 UTC 타임스탬프이며 형식은 YYYY-MM-DD HH:mm:ss GMT +0000입니다. 페이로드 내의 장비 로컬 타임스탬프는 다른 시간대 오프셋을 사용할 수 있습니다.

stgid (쿼리 매개변수)String. Service Tag ID — RESTful API 호출의 대상 장비를 식별합니다. API Monitor 계정에서 확인한 엔드포인트에 URL 쿼리 매개변수로 전달합니다: POST https://<your-endpoint>?stgid=YOUR_TAG_ID.

템플릿 유형

생체 정보와 인증 정보는 Template 배열로 전달됩니다. 각 항목에는 Type 필드가 있습니다:

템플릿 병합 동작 — 콜백 핸들러 구현 시 중요
장비에서 사용자 데이터가 푸시될 때(콜백 오퍼레이션 #3–#9) 템플릿은 여러 콜백에 나뉘어 한 건씩 또는 그룹으로 도착할 수 있습니다. 각 콜백에는 사용자의 전체 템플릿 세트가 포함되지 않으며, 추가되거나 변경된 템플릿만 포함됩니다.

서버는 수신한 템플릿을 해당 사용자의 기존 저장 템플릿과 병합해야 합니다. 각 템플릿의 고유 키는 Type + Index입니다. 예:
• 콜백 1이 Fingerprint Index 0과 함께 도착 → 저장
• 콜백 2가 Face Index 0 + Card와 함께 도착 → 병합하고 지문을 덮어쓰지 않음
• 콜백 3이 Fingerprint Index 0(새 데이터)과 함께 도착 → Index 0의 기존 지문을 업데이트
콜백에서 모든 템플릿을 교체하지 마세요. 항상 Type + Index 기준으로 upsert하세요.

유형	설명	주요 추가 필드
`Card`	RFID / 근접 카드 번호	`Data`(카드 번호 문자열)
`Password`	숫자 PIN	`Data`(PIN 문자열)
`Fingerprint`	지문 템플릿 — Base64로 인코딩된 바이너리	`Index`(손가락 인덱스 0–9), `Size`, `Data`
`Face`	얼굴 템플릿 — Base64로 인코딩된 JPEG 또는 바이너리	`Index`, `Size`, `Data`
`Palm`	손바닥 정맥 템플릿 — Base64로 인코딩된 바이너리	`Index`, `Data`
`UserPhoto`	사용자 프로필 사진 — Base64로 인코딩된 JPEG	`Data`

API 레퍼런스

응답 상태 코드

RESTful API 응답에는 숫자 StatusCode가 포함됩니다. 콜백 API 응답은 결과와 관계없이 항상 간단한 {"status":"done"} 형식을 사용합니다.

코드	상태	설명
`0`	성공	오퍼레이션이 정상적으로 완료되었습니다.
`1`	잘못된 요청 데이터	JSON 본문의 형식이 올바르지 않거나 잘못된 값이 포함되어 있습니다.
`2`	잘못된 Service Tag ID	`stgid` 쿼리 매개변수가 등록된 어떤 장비와도 일치하지 않습니다.
`3`	잘못된 요청	요청 구조가 예상되는 오퍼레이션 형식과 일치하지 않습니다.
`4`	잘못된 암호화	페이로드 암호화(AES-256)를 복호화할 수 없습니다. 암호화 키를 확인하세요.
`5`	장비 오프라인	대상 장비가 현재 Biometric Gateway에 연결되어 있지 않습니다.
`6`	오퍼레이션 시간 초과	장비가 제한 시간 내에 명령에 응답하지 않았습니다.
`7`	잘못된 인증 토큰	요청의 `AuthToken`이 장비에 설정된 토큰과 일치하지 않습니다.
`8`	이미 존재하는 사용자	장비에 이미 존재하는 UserID에 대해 추가 오퍼레이션이 시도되었습니다.
`9`	사용자를 찾을 수 없음	지정한 UserID가 장비에 존재하지 않습니다.
`10`	템플릿 오류	생체 템플릿 데이터가 손상되었거나 지원되지 않는 형식입니다.
`11`	장비 메모리 부족	장비가 최대 사용자 수 또는 템플릿 용량에 도달했습니다.
`13`	잘못된 보안 키	API Monitor에 설정된 보안 키가 일치하지 않습니다.
`15`	지원되지 않는 기능	요청한 오퍼레이션은 이 장비 모델 또는 통신 모드에서 지원되지 않습니다.
`999`	알 수 없는 오류	예기치 않은 오류가 발생했습니다. OperationID와 함께 Cams 지원팀에 문의하세요.

추가 정보

지원 포트

실시간 근태 정보를 수신하려면 서버가 Cams Protocol Engine에서 접근할 수 있는 HTTP(S) 엔드포인트를 노출해야 합니다.

포트	프로토콜	용도
`80`	HTTP	운영 환경. 콜백 URL을 80번 포트에 바인딩합니다. API Monitor에서 설정하며 기록이 발생할 때마다 자동으로 호출됩니다.
`443`	HTTPS	운영 환경(보안). 유효한 SSL 인증서를 사용하는 HTTPS입니다. 운영 환경에 권장됩니다.
`8123`	HTTP	테스트 전용. 개발 중에 임시로 사용할 수 있는 비표준 포트입니다.

HTTPS를 권장합니다. 운영 환경에서는 유효한 SSL 인증서와 함께 HTTPS를 사용하세요. 서버 재시작 없이 자동 갱신되도록 구성하세요.

추가 정보

샘플 데이터

38개 오퍼레이션 전체의 샘플 요청 및 응답 페이로드는 위의 각 오퍼레이션 섹션에 문서화되어 있습니다. 한눈에 보려면:

이 페이지위의 각 오퍼레이션 섹션에는 샘플 데이터가 포함된, 바로 복사해 쓸 수 있는 요청 및 응답 JSON이 있습니다.

이전 샘플 페이지biometric-web-api-sample-request-response.html — 오퍼레이션별 드롭다운 선택기 제공.

추가 정보

암호화

선택적으로 AES-256 암호화를 활성화하면 Cams Protocol Engine과 사용자 서버 간에 교환되는 모든 데이터를 암호화할 수 있습니다.

알고리즘AES-256, ECB 모드, PKCS5 패딩(AES/ECB/PKCS5PADDING).

키 설정API Monitor에서 키를 Security Key로 설정합니다. 설정하면 모든 raw JSON 페이로드가 암호화됩니다.

인코딩암호화된 페이로드는 안전한 HTTP 전송을 위해 Base64로 인코딩됩니다.

Java 예제

암호화 / 복호화 (Java)

// Encryption
Cipher cipher = Cipher.getInstance("AES/ECB/PKCS5PADDING");
SecretKeySpec keySpec = new SecretKeySpec(securityKey.getBytes("UTF-8"), "AES");
cipher.init(Cipher.ENCRYPT_MODE, keySpec);
String encrypted = Base64.getEncoder().encodeToString(cipher.doFinal(rawJson.getBytes("UTF-8")));

// Decryption
cipher.init(Cipher.DECRYPT_MODE, keySpec);
byte[] decoded = Base64.getDecoder().decode(encryptedPayload);
String decrypted = new String(cipher.doFinal(decoded), "UTF-8");

중요: 암호화를 활성화한 경우 수신하는 콜백 페이로드를 복호화하고, 송신하는 RESTful 요청 본문은 동일한 키로 암호화하세요.