API 로컬 테스트
배포하기 전에 개발 PC에서 장비 콜백을 수신하고 Postman으로 REST 명령을 테스트하는 방법을 설명합니다.
로컬 테스트(서버 배포 없이)
운영 서버에 배포하지 않고 로컬 개발 PC에서 콜백 연동을 테스트하려면, Cams Protocol Engine이 콜백 데이터를 POST할 수 있도록 로컬 PC를 인터넷에서 접근 가능하게 만들어야 합니다.
옵션 A: 공인 IP + 포트 포워딩
인터넷 회선에 공인(고정) IP 주소가 있다면 외부 포트를 로컬 애플리케이션으로 포워딩할 수 있습니다.
공인 IP 확인
whatismyip.com에 접속하거나 터미널에서 curl ifconfig.me를 실행하여 공인 IP 주소를 확인해 두세요.
라우터에서 포트 포워딩 설정
라우터 관리 페이지에 로그인합니다. 외부 포트(예: 8080)를 로컬 PC의 내부 IP와 애플리케이션이 실행 중인 포트(예: 3000, 5000, 8080)로 포워딩합니다.
콜백 URL 설정
API Monitor에서 콜백 URL을 다음과 같이 설정합니다:http://YOUR_PUBLIC_IP:8080/callback
테스트
생체인식 장비에서 기록을 발생시킵니다. Cams Protocol Engine이 콜백 데이터를 공인 IP로 POST하고, 라우터가 이를 로컬 애플리케이션으로 전달합니다.
옵션 B: 터널링 도구 (공인 IP 불필요)
공인 IP가 없거나 포트 포워딩을 설정할 수 없다면 터널링 서비스를 사용해 로컬 서버를 인터넷에 노출하세요.
| 도구 | 명령 | 비고 |
|---|---|---|
| ngrok | ngrok http 3000 | 무료 요금제 제공. 공개 HTTPS URL을 즉시 발급해 줍니다. |
| Cloudflare Tunnel | cloudflared tunnel --url localhost:3000 | 무료. 빠른 터널은 계정이 필요 없습니다. |
| localhost.run | ssh -R 80:localhost:3000 ssh.localhost.run | 설치가 필요 없습니다. SSH로 동작합니다. |
로컬 애플리케이션 시작
콜백 서버를 로컬에서 실행합니다(예: php -S localhost:8080, node server.js, python app.py).
터널 시작
터널링 도구를 실행합니다. https://abc123.ngrok-free.app 같은 공개 URL이 출력됩니다.
콜백 URL 설정
API Monitor에서 콜백 URL을 터널 URL로 설정합니다:https://abc123.ngrok-free.app/callback
테스트
기록을 발생시키세요. 콜백이 터널을 통해 로컬 PC로 실시간 전달됩니다.
URL 테스트
운영을 시작하기 전에 Postman으로 엔드포인트를 검증하세요. 27개 RESTful 오퍼레이션이 모두 미리 구성된 Collection을 제공합니다.
Postman Collection
다운로드하여 Postman으로 가져오세요. base_url, stgid, auth_token 변수를 설정하면 바로 테스트를 시작할 수 있습니다.
Collection 가져오기
Postman 열기 → Import → 다운로드한 .json 파일을 끌어다 놓습니다. 27개 RESTful 오퍼레이션이 모두 카테고리별로 묶여 표시됩니다.
변수 설정
Collection의 Variables 탭으로 이동하여 다음을 설정합니다:
base_url = RESTful 엔드포인트 URL(API Monitor에서 확인)
stgid = 장비의 Service Tag ID
auth_token = 장비의 AuthToken
요청 보내기
원하는 오퍼레이션을 선택하고 JSON 본문을 사용자의 값으로 수정한 뒤 Send를 누르세요. 응답이 위에 문서화된 형식과 일치하는지 확인하세요.
Postman 예시
아래는 Postman에서 샘플 API 요청을 구성한 스크린샷입니다. 메서드를 POST로 설정하고, RESTful 엔드포인트 URL 뒤에 ?stgid=를 붙여 입력한 다음 raw JSON 본문을 사용하세요.
{"status":"done"}을 반환하는지 확인하세요.