API 레퍼런스: 아키텍처, 필드, 상태 코드
모든 오퍼레이션이 공통으로 사용하는 구성 요소: 요청 흐름, 공통 JSON 필드, 템플릿 유형, 상태 코드, 포트, 페이로드 암호화.
빠른 답변
두 가지 API 흐름은 무엇인가요?
콜백 API는 장비에서 (Cams Biometric Gateway를 통해) 서버로 이벤트를 실시간으로 전송합니다. RESTful API는 서버에서 장비로 명령을 보낼 수 있게 하며, 응답은 약 15초 안에 도착합니다. 서버가 오프라인이면 엔진이 콜백을 캐시하고, REST 명령은 장비가 다시 연결될 때까지 대기열에 저장됩니다.
RESTful API는 어떤 상태 코드를 반환하나요?
숫자 StatusCode: 0 성공, 1 잘못된 요청 데이터, 2 잘못된 Service Tag ID, 3 잘못된 요청, 4 잘못된 암호화, 5 장비 오프라인, 6 작업 시간 초과, 7 잘못된 auth token, 8 이미 존재하는 사용자, 9 사용자를 찾을 수 없음, 10 템플릿 오류, 11 장비 메모리 가득 참, 13 잘못된 보안 키, 15 지원되지 않는 기능, 999 알 수 없는 오류. 콜백 응답은 항상 {"status":"done"}을 사용합니다.
상태 코드 5(장비 오프라인)는 무엇을 의미하나요?
대상 장비가 현재 Biometric Gateway에 연결되어 있지 않습니다. 상태 코드 5를 참조하세요.
요청을 어떻게 인증하나요?
모든 요청에는 장비 하나를 식별하고 API Monitor 포털에서 설정하는 32자 토큰인 AuthToken이 포함됩니다. 수신하는 모든 콜백에서 이를 검증하세요. REST 호출은 장비를 stgid(Service Tag ID) 쿼리 매개변수로도 전달합니다. 공통 필드를 참조하세요.
서버에는 어떤 포트가 필요한가요?
운영 환경에는 80번(HTTP) 또는 443번(HTTPS) 포트를 사용하며, 유효한 인증서가 있는 HTTPS를 권장합니다. 8123번(HTTP) 포트는 테스트 전용입니다. 지원 포트를 참조하세요.
페이로드는 어떻게 암호화되나요?
암호화는 선택 사항입니다. 활성화하면 페이로드는 PKCS5 패딩을 사용하는 ECB 모드의 AES-256(AES/ECB/PKCS5PADDING)을 사용하고, API Monitor에서 설정한 Security Key를 키로 사용하며, HTTP 전송을 위해 Base64로 인코딩됩니다. 수신 콜백의 복호화와 송신 REST 본문의 암호화에는 동일한 키를 사용하세요. 암호화를 참조하세요.
여러 콜백에 걸쳐 도착하는 템플릿은 어떻게 처리하나요?
병합하세요. 각 콜백에는 추가되거나 변경된 템플릿만 포함됩니다. 템플릿의 고유 키는 Type + Index이므로 이 쌍을 기준으로 upsert하고, 사용자의 전체 템플릿 집합을 절대 교체하지 마세요. 템플릿 유형을 참조하세요.
어떤 템플릿 유형이 있나요?
Card, Password, Fingerprint, Face, Palm, UserPhoto가 있습니다. Fingerprint, Face, Palm 템플릿은 Base64로 인코딩되며, 지문 인덱스는 0–9 범위입니다.
API 아키텍처
| 항목 | 콜백 API | RESTful API |
|---|---|---|
| 시작 주체 | 장비 / Biometric Gateway | 사용자 서버 |
| 방향 | 장비 → 사용자 서버 | 사용자 서버 → 장비 |
| 지연 시간 | 실시간 (밀리초) | 약 15초 |
| 트리거 | 장비에서 발생한 생체인식 이벤트 | 사용자 코드에서 보내는 HTTP POST |
| 사용자의 역할 | 수신 후 응답 | 명령 전송 후 응답 폴링/대기 |
| 응답 본문 | {"status":"done"} | {"Status":"done","OperationID":"…","StatusCode":0} |
| 오프라인 시 동작 | 엔진이 캐시하고 서버가 다시 온라인이 되면 전달 | 엔진이 큐에 보관하고 장비가 다시 연결되면 전달 |
공통 필드
콜백과 RESTful의 모든 요청은 다음 최상위 필드를 공통으로 사용합니다.
"j95xfejt3vr1"). RESTful 응답은 동일한 OperationID를 반환하므로 요청과 응답을 매칭할 수 있습니다.YYYY-MM-DD HH:mm:ss GMT +0000입니다. 페이로드 내의 장비 로컬 타임스탬프는 다른 시간대 오프셋을 사용할 수 있습니다.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 |
응답 상태 코드
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 | 테스트 전용. 개발 중에 임시로 사용할 수 있는 비표준 포트입니다. |
샘플 데이터
38개 오퍼레이션 전체의 샘플 요청 및 응답 페이로드는 위의 각 오퍼레이션 섹션에 문서화되어 있습니다. 한눈에 보려면:
암호화
선택적으로 AES-256 암호화를 활성화하면 Cams Protocol Engine과 사용자 서버 간에 교환되는 모든 데이터를 암호화할 수 있습니다.
AES/ECB/PKCS5PADDING).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");