콜백 이벤트
카플랫 API 콜백 이벤트 종류와 처리 방법을 설명합니다.
카플랫에서는 예약 또는 차량 상태가 변경될 때 콜백 을 통해 실시간 알림을 받아볼 수 있습니다.
콜백은 데이터 변경 시 서버 간에 이벤트를 실시간으로 전달하는 메커니즘입니다.
1. 콜백 이벤트 종류
카플랫이 전송하는 콜백 이벤트는 다음과 같습니다. 이벤트별 요청 본문 스펙은 각 이벤트의 API 레퍼런스를 참고해주세요.
| 이벤트 | HTTP 메서드 | 경로 |
|---|---|---|
| 예약 정보 등록 이벤트 | POST | /events/reservation |
| 예약 정보 업데이트 이벤트 | PUT | /events/reservation/{id} |
| 예약 차량 변경 이벤트 | PUT | /events/reservation/{id}/car-change |
| 예약 반납 연장 이벤트 | PUT | /events/reservation/{id}/extension |
| 하이패스 결제 정보 전달 | POST | /events/hipass |
2. 콜백 URL 등록하기
2.1 API 키 신청
- API 키 신청: 카플랫 API 연동 관리 페이지에서 API 키 신청을 진행합니다.
- 승인 대기: 승인 결과는 관리자 검토 후 신청 시 입력한 이메일로 알려드립니다.
2.2 콜백 URL 및 이벤트 설정
API 키 신청 승인 완료 후, 상세정보 페이지에서 콜백 설정을 등록 및 관리할 수 있습니다:
- 상세정보 페이지 접속: 카플랫 API 연동 관리 페이지에서 승인된 API 키의 상세정보로 이동합니다.
- 콜백 베이스 URL 등록: 콜백을 받을 서버의 베이스 주소를 입력합니다.
- 형식:
https://서버주소 - 예시:
https://api.yourservice.com
- 형식:
- 콜백 이벤트 선택: 수신하고자 하는 콜백 이벤트를 선택합니다.
- 필요한 이벤트만 선택하여 불필요한 콜백 수신을 방지할 수 있습니다.
참고:
- 콜백 URL은 HTTPS 프로토콜을 사용해야 하며, 외부에서 접근 가능한 공개 URL이어야 합니다.
- 등록한 베이스 URL에 각 이벤트별 경로가 추가되어 전송됩니다. (예:
{베이스URL}/events/{이벤트타입})- 선택하지 않은 이벤트는 콜백이 전송되지 않습니다.
- 콜백 URL과 이벤트 설정은 상세정보 페이지에서 언제든지 수정할 수 있습니다.
- 사용 가능한 모든 콜백 이벤트와 경로는 API 레퍼런스의 콜백 이벤트 섹션에서 확인할 수 있습니다.
3. 콜백 수신 및 처리 가이드
3.1 콜백 요청 형식
중요: 클라이언트는 각 콜백 이벤트의 엔드포인트를 구현하여 Carplat으로부터 실시간 정보를 수신해야 합니다.
카플랫에서 전송하는 콜백은 이벤트별로 다른 엔드포인트로 전송됩니다. 각 이벤트 타입에 따라 등록한 콜백 베이스 URL에 해당 이벤트 경로가 추가되어 요청이 전달됩니다.
요청 구조
모든 콜백 이벤트는 다음과 같은 공통 구조를 따릅니다. 예약 정보 등록 이벤트는 새 예약을 전달하므로 POST로, 이미 전달된 예약의 변경 사항은 예약 ID를 경로에 담아 PUT으로 전송됩니다.
Loading...
Loading...
주요 특징
- HTTP 메서드: 새 데이터를 전달하는 이벤트(예약 정보 등록, 하이패스 결제 정보 전달)는
POST, 기존 예약의 변경을 전달하는 이벤트(예약 정보 업데이트, 차량 변경, 반납 연장)는PUT메서드를 사용합니다. - Content-Type:
application/json형식으로 전송됩니다. - 엔드포인트: 각 이벤트는
/events/로 시작하는 고유한 경로를 가지며, 예약 변경 이벤트는 경로에 예약 ID({id})를 포함합니다. - 요청 본문: 이벤트 타입에 따라 다른 JSON 스키마를 가집니다.
참고:
- 사용 가능한 모든 콜백 이벤트 목록과 각 이벤트의 상세한 요청 스키마는 API 레퍼런스의 콜백 이벤트 섹션에서 확인할 수 있습니다.
3.2 콜백 응답 처리
콜백을 정상적으로 수신했다면 HTTP 200 OK 응답과 아래 객체를 Response Body로 반환해야 합니다:
Loading...
3.3 방화벽 설정 (필수)
콜백을 정상적으로 수신하려면 카플랫 서버 IP에 대한 방화벽 설정이 필수입니다.
방화벽 설정 방법은 방화벽 및 보안 프로토콜 페이지를 참고해주세요
콜백 URL로 등록한 서버에서 다음 방화벽 규칙을 설정해야 합니다:
- 인바운드 규칙: 카플랫 서버에서 콜백 서버로의 HTTP/HTTPS 요청 허용
- 아웃바운드 규칙: 콜백 서버에서 카플랫 서버로의 응답 허용
방화벽 설정 예시
Loading...
참고: 정확한 카플랫 서버 IP 주소는 API 키 발급 시 함께 안내됩니다.
3.4 보안 고려사항
- HTTPS 필수: 콜백 URL은 반드시 HTTPS를 사용해야 합니다.
- IP 화이트리스트: 카플랫 서버 IP만 허용하도록 방화벽을 설정하세요.