Support Hub/API & Integrations/Python, Node.js, PHP로 생체인식 콜백 수신기 구축하기
Translated from the English article and reviewed by a person. Read the English original
Developer

Python, Node.js, PHP로 생체인식 콜백 수신기 구축하기

Python, Node.js, PHP로 생체인식 콜백 수신기 구축하기

콜백 수신기는 모든 지문, 얼굴 또는 카드 스캔을 자체 시스템의 기록으로 바꿔 주는 작은 코드 조각입니다. Cams Biometrics Gateway는 검증된 각 스캔을 JSON 요청으로 서버에 전송하며, 서버는 수신 확인을 위해 응답합니다. 이 수신기를 처음부터 직접 작성할 필요는 없습니다. Cams는 Python, Node.js, PHP용 AI Code Generator Prompts를 제공합니다. 이 프롬프트를 Claude나 ChatGPT 같은 AI 어시스턴트에 붙여 넣으면 콜백 수신기, REST 클라이언트, 테스트 인터페이스가 포함된 완전한 작동 파일을 얻을 수 있습니다. 이 튜토리얼에서는 수신기가 수행해야 할 작업, 사용 언어에 맞게 수신기를 생성하는 방법, 구성 방법, 실제 운영 전에 테스트하는 방법을 설명합니다.

01 · 여섯 가지 작업

콜백 수신기의 역할

사용하는 언어와 관계없이 모든 생체인식 콜백 수신기는 동일한 여섯 가지 작업을 수행합니다. 생성된 코드를 점검할 때도 이 항목을 확인하면 됩니다.

작업 의미 중요한 이유
1. 요청 수락 원시 JSON 본문이 포함된 HTTP/HTTPS POST 수신 Gateway가 각 이벤트를 전달하는 방식입니다
2. 토큰 검증 AuthToken을 예상되는 콜백 토큰과 대조하여 확인 다른 누군가가 URL로 가짜 출결 데이터를 전송하는 것을 막습니다
3. 이벤트 유형별 라우팅 RealTime 내부의 키를 확인하고 그에 맞게 처리 모든 콜백이 출결 스캔은 아닙니다. 일부는 사진이나 사용자 변경 사항을 알려 줍니다
4. 중복 건너뛰기 OperationID를 사용하여 이미 저장한 이벤트는 무시 같은 이벤트가 다시 전달되어도 기록이 두 번 생성되지 않습니다
5. 저장 및 로그 기록 필요한 필드를 저장하고 모든 콜백을 기록 HRMS, 급여 또는 대시보드가 사용할 기록을 생성합니다
6. 완료 응답 HTTP 200과 함께 {“status”:”done”} 반환 이벤트가 안전하게 도착했음을 Gateway에 알립니다

02 · 데이터 이해하기

수신하게 될 페이로드

가장 일반적인 콜백은 누군가 스캔할 때마다 전송되는 출결 로그입니다. 이 샘플을 sample.json으로 저장하세요. 나중에 수신기를 테스트할 때 사용합니다.

Callback API, 수신기로 전송되는 PunchLog 요청

{
  "RealTime": {
    "OperationID": "9nu1wak5616p",
    "LabelName": "Burj Khalifa",
    "SerialNumber": "ZHM11xxxxxxxx",
    "PunchLog": {
      "Type": "CheckOut",
      "Temperature": "36.8",
      "FaceMask": false,
      "InputType": "Fingerprint",
      "UserId": "2",
      "LogTime": "2020-09-17 07:48:22 GMT +0530"
    },
    "AuthToken": "COJJ7eiIPBGUfmIQPvh2PJWWDLX7OuKs",
    "Time": "2020-09-17 04:19:03 GMT +0000"
  }
}

모든 콜백을 처리한 후 수신기는 HTTP 200과 함께 정확히 다음 본문을 반환해야 합니다:

Callback API, 수신기가 반환해야 하는 응답

{ "status": "done" } (HTTP 200)

콜백 이벤트 유형

모든 콜백은 RealTime 객체 안에 담겨 도착합니다. 수신기는 다음 키 중 어떤 키가 있는지 확인하여 처리 방법을 결정합니다:

RealTime 내부의 키 보고 내용
PunchLog 출결 스캔: 누가, 출근 또는 퇴근, 언제, 어떤 방식으로 스캔했는지
UserUpdated 장치에서 사용자 정보가 업데이트됨

개발자가 놓치기 쉬운 두 가지 세부 사항

세부 사항 주의할 점
응답 키는 소문자입니다 값 done과 함께 status를 소문자로 반환하세요. RESTful API 응답의 대문자로 시작하는 Status 필드를 복사하지 마세요
LogTime 형식 LogTime은 2020-09-17 07:48:22 GMT +0530와 같은 형태입니다. 장치의 시간 오프셋이 포함된 실제 스캔 시간입니다. 오프셋을 적용하여 파싱한 후 출결 시간으로 사용하세요

03 · AI가 코드 작성하기

AI Code Generator Prompts로 수신기 생성하기

Cams는 지원되는 서버 언어마다 바로 사용할 수 있는 프롬프트 파일을 제공합니다. 각 프롬프트에는 Cams Web API 3.0 사양 요약과 무엇을 구축해야 하는지에 대한 명확한 지침이 포함되어 있습니다. 이를 AI 어시스턴트에 붙여 넣으면 어시스턴트가 사용 환경에 맞는 단일 파일 구현 코드를 완성해 줍니다.

1

프롬프트 파일 다운로드

다음 섹션에서 사용할 언어를 선택하고 .txt 프롬프트 파일을 다운로드하세요.

2

AI 어시스턴트에 붙여 넣기

Claude, ChatGPT, Copilot 또는 모든 AI 코딩 도구를 열고 프롬프트 내용 전체를 붙여 넣으세요.

3

완전한 작동 파일 받기

AI가 단일 파일을 생성합니다. 구성 값을 설정하고, 배포한 다음 실행하세요.

생성된 각 파일에 포함된 항목 기능
콜백 수신기 원시 POST 본문을 읽고, AuthToken을 검증하고, 이벤트 유형별로 라우팅하며, 모든 콜백을 기록하고, 출결 로그를 저장하고, 출결 사진을 저장하며, done으로 응답합니다
REST 클라이언트 범용 요청 함수와 27개 RESTful 작업 모두를 위한 래퍼 함수(AddUser, DeleteUser, ResendAllUser, UpdateAccessTime 등)
HTML 테스트 인터페이스 구성 필드, 작업 드롭다운, 요청 템플릿이 미리 채워진 JSON 편집기, 응답 뷰어, 최근 콜백 목록이 있는 브라우저 페이지

호스팅된 문서가 우선입니다

각 프롬프트는 AI에게 Cams Web API 문서 전체를 읽고, 작업, JSON 스키마, 필드 이름, 응답 코드에 대한 공식 출처로 취급하도록 지시합니다. 프롬프트 요약 내용이 호스팅된 문서와 충돌하는 경우 문서가 우선합니다.

04 · 언어 선택하기

Python, Node.js, PHP용 프롬프트

각 프롬프트는 해당 언어에 맞는 관용적 코드를 최소한의 종속성으로 생성하도록 조정되어 있습니다.

Python

Flask, SQLite, 표준 라이브러리만 사용

Python 프롬프트 받기

Node.js

Express, JSON 파일 저장소

Node.js 프롬프트 받기

PHP

순수 PHP, SQLite, Composer 사용 안 함

PHP 프롬프트 다운로드

Minimal API를 사용하는 C# (.NET 8), 내장 HttpServer를 사용하고 종속성이 없는 Java, net/http와 표준 라이브러리만 사용하는 Go, Sinatra와 SQLite를 사용하는 Ruby용 프롬프트도 제공됩니다. 모든 프롬프트는 Cams Web API 문서의 AI Code Generator Prompts 섹션에서 찾을 수 있습니다. 프롬프트 받기.

05 · 설정할 세 가지 값

생성된 파일 구성하기

생성된 파일의 상단에는 구성 블록이 있습니다. PHP 버전은 다음과 같으며, 다른 언어도 동일한 세 가지 값을 사용합니다:

구성 블록, PHP 버전

$CONFIG = [
    'base_url'            => 'https://YOUR_RESTFUL_ENDPOINT_URL',
    'stgid'               => 'YOUR_SERVICE_TAG_ID',
    'auth_token'          => 'YOUR_AUTH_TOKEN',
];
설정 입력할 내용
base_url Cams API Monitor 계정의 RESTful 엔드포인트 URL
stgid 서비스 태그 ID.
auth_token 발신 RESTful 요청에 포함되고, 수신 콜백 요청의 AuthToken과 대조되는 AuthToken입니다.

공유 코드에 토큰을 넣지 마세요

간단한 테스트라면 구성 블록에 값을 직접 입력해도 괜찮습니다. 운영 환경에 적용하기 전에는 토큰을 환경 변수나 비밀 관리 도구로 옮기세요. 그래야 버전 관리 시스템이나 공유 파일에 토큰이 남지 않습니다.

구성을 마치고 공개 HTTPS 주소에 배포한 후에는 해당 주소를 Cams Gateway의 Callback URL로 설정하세요. 이후에는 검증된 모든 스캔이 실시간으로 수신기에 도달합니다.

06 · 장치를 연결하기 전에 테스트하기

수신기 테스트하기

콜백 수신기를 테스트하는 데 생체인식 장치는 필요하지 않습니다. 일치하는 콜백 토큰을 사용하여 cURL로 샘플 페이로드를 직접 보내고 응답을 확인하면 됩니다.

터미널, 테스트 콜백 전송

# 샘플 페이로드를 sample.json으로 저장한 다음 수신기로 전송하세요:
curl -X POST https://YOUR_SERVER/YOUR_CALLBACK_PATH \
  -H "Content-Type: application/json" \
  -d @sample.json

# 예상 응답 (HTTP 200):
# {"status":"done"}
테스트 전송할 내용 예상 결과
유효한 이벤트 AuthToken을 auth_token 값으로 설정한 sample.json done과 함께 HTTP 200 반환, 출결 기록 저장됨
중복 이벤트 같은 요청을 두 번째로 전송 done과 함께 HTTP 200 반환, 두 번째 기록은 저장되지 않음
잘못된 토큰 다른 AuthToken을 설정한 sample.json 거부되며 아무것도 저장되지 않음
출근 이벤트 Type을 CheckIn으로 변경한 sample.json 출근으로 저장됨
RESTful 작업 내장 HTML 테스트 인터페이스를 사용하여 작업 전송 Status와 StatusCode가 포함된 응답

생성된 HTML 테스트 인터페이스를 사용하면 RESTful 기능을 쉽게 시험해 볼 수 있습니다. 파일을 브라우저에서 열고, 드롭다운에서 작업을 선택하고, 미리 채워진 JSON을 조정한 후 전송하세요. 같은 페이지의 최근 콜백 뷰어에서 테스트 콜백이 수신되었는지 확인할 수 있습니다.

07 · 운영 체크리스트

운영 시작 전 검토하기

AI가 생성한 코드는 빠르고 신뢰할 수 있는 출발점이지만, 다른 모든 코드와 마찬가지로 실제 직원 데이터를 처리하기 전에 검토해야 합니다.

항목 완료 기준
코드 검토 완료 개발자가 생성된 파일을 읽고 각 섹션의 역할을 이해함
HTTPS 전용 수신기는 유효한 인증서가 있는 HTTPS로만 접근 가능함
토큰 보호 AuthToken이 환경 변수나 비밀 관리 도구에 저장됨
중복 처리 OperationID를 저장하고 확인하여 반복 전달된 이벤트를 무시함
적합한 저장소 소규모 환경에서는 JSON 파일 저장소로 충분하며, 대규모 배포에서는 운영용 데이터베이스로 전환할 수 있음
테스트 인터페이스 보호 공개 서버에서 HTML 테스트 페이지에 비밀번호가 설정되어 있거나 비활성화되어 있음
사진 신중하게 처리 디스크에 저장된 출결 사진은 접근이 통제되고 필요한 기간 동안만 보관됨
모니터링 구축 오류와 비정상적인 콜백 양은 자체 모니터링에서 기록되고 알림이 발생함

업무 규칙은 다른 곳에 두세요

수신기의 역할은 수락, 검증, 라우팅, 저장, 확인 응답입니다. 누가 지각했는지 판단하거나, 초과 근무를 계산하거나, 알림을 보내는 일은 HRMS, ERP 또는 자동화 도구처럼 저장된 이벤트를 읽는 시스템의 몫입니다. 역할이 명확한 수신기는 보안을 유지하고 관리하기가 더 쉽습니다.

자주 묻는 질문

직접 코드를 작성해야 하나요?

대부분의 경우 그럴 필요가 없습니다. AI Code Generator Prompts는 완전한 작동 파일을 생성합니다. 구성 값 세 가지를 설정하고, 배포한 다음 테스트하면 됩니다. 다만 운영 환경에 적용하기 전에는 개발자가 코드를 검토해야 합니다.

어떤 AI 어시스턴트가 프롬프트와 호환되나요?

Claude, ChatGPT, Copilot을 포함한 모든 유능한 AI 코딩 어시스턴트에서 사용할 수 있습니다. 어시스턴트가 전체 사양을 파악할 수 있도록 프롬프트 내용 전체를 한 번에 붙여 넣으세요.

RESTful 엔드포인트 URL과 서비스 태그 ID는 어디에서 찾나요?

두 가지 모두 Cams API Monitor 계정에서 확인할 수 있습니다. RESTful 요청은 엔드포인트 URL에 ?stgid= 를 붙이고 그 뒤에 서비스 태그 ID를 넣어 전송합니다.

중복 이벤트에 done으로 응답하는 이유는 무엇인가요?

이미 저장했더라도 이벤트는 안전하게 도착했기 때문입니다. done으로 응답하면 Gateway에 같은 이벤트를 다시 보낼 필요가 없음을 알릴 수 있습니다.

목록에 없는 언어를 사용할 수 있나요?

예. 콜백 수신기는 HTTPS POST를 수락하고 JSON을 반환하기만 하면 됩니다. 프롬프트는 작업을 빠르게 시작하기 위한 방법이며, 그런 기능을 지원하는 모든 언어에서 같은 API를 사용할 수 있습니다.

결론: 오후 한나절이면 프롬프트에서 실시간 출결까지

생체인식 콜백 수신기는 작지만, 검증된 모든 스캔을 HRMS, 급여, 대시보드, 자동화를 위한 실시간 데이터로 바꾸는 핵심 요소입니다. Cams AI Code Generator Prompts를 사용하면 빈 화면에서 처음부터 만들 필요가 없습니다. Python, Node.js 또는 PHP용 프롬프트를 내려받아 AI 어시스턴트에 붙여 넣고, 값 세 가지를 설정한 후 테스트하세요. 그다음 검토하고 보안을 적용하면 실시간 출결 데이터가 흐르기 시작합니다.

Cams Biometrics Gateway는 수신기에 필요한 이벤트를 제공합니다. Callback API는 15개 이상의 브랜드 장치에서 검증된 모든 스캔을 하나의 일관된 JSON 형식으로 실시간 전송하며, RESTful API는 생성된 클라이언트가 호출할 수 있는 27개 작업을 제공합니다. 모든 통신은 인증 토큰 검증과 선택적 AES-256 암호화를 적용하여 HTTP/HTTPS로 이루어집니다. CamsBiometrics.com에서 플랫폼을 살펴보고, 모든 AI Code Generator Prompt를 포함한 전체 Web API 문서를 확인하세요: 프롬프트 받기.

 

Was this article helpful?