카플랫에서는 예약 또는 차량 상태가 변경될 때 콜백 을 통해 실시간 알림을 받아볼 수 있습니다.
콜백은 데이터 변경 시 서버 간에 이벤트를 실시간으로 전달하는 메커니즘입니다.

1. 콜백 이벤트 종류

콜백으로 등록할 수 있는 이벤트 종류와 상세한 API 스펙은 API 레퍼런스의 콜백 이벤트 섹션을 참고해주세요.

2. 콜백 URL 등록하기

2.1 API 키 신청

1. API 키 신청: 카플랫 API 연동 관리 페이지에서 API 키 신청을 진행합니다.
2. 승인 대기: 승인 결과는 관리자 검토 후 신청 시 입력한 이메일로 알려드립니다.

2.2 콜백 URL 및 이벤트 설정

API 키 신청 승인 완료 후, 상세정보 페이지에서 콜백 설정을 등록 및 관리할 수 있습니다:

1. 상세정보 페이지 접속: 카플랫 API 연동 관리 페이지에서 승인된 API 키의 상세정보로 이동합니다.
2. 콜백 베이스 URL 등록: 콜백을 받을 서버의 베이스 주소를 입력합니다.
   • 형식: https://서버주소
   • 예시: https://api.yourservice.com
3. 콜백 이벤트 선택: 수신하고자 하는 콜백 이벤트를 선택합니다.
   • 필요한 이벤트만 선택하여 불필요한 콜백 수신을 방지할 수 있습니다.

참고:

• 콜백 URL은 HTTPS 프로토콜을 사용해야 하며, 외부에서 접근 가능한 공개 URL이어야 합니다.
• 등록한 베이스 URL에 각 이벤트별 경로가 추가되어 전송됩니다. (예: {베이스URL}/events/{이벤트타입})
• 선택하지 않은 이벤트는 콜백이 전송되지 않습니다.
• 콜백 URL과 이벤트 설정은 상세정보 페이지에서 언제든지 수정할 수 있습니다.
• 사용 가능한 모든 콜백 이벤트와 경로는 API 레퍼런스의 콜백 이벤트 섹션에서 확인할 수 있습니다.

3. 콜백 수신 및 처리 가이드

3.1 콜백 요청 형식

중요: 클라이언트는 각 콜백 이벤트의 엔드포인트를 구현하여 Carplat으로부터 실시간 정보를 수신해야 합니다.

카플랫에서 전송하는 콜백은 이벤트별로 다른 엔드포인트로 전송됩니다. 각 이벤트 타입에 따라 등록한 콜백 베이스 URL에 해당 이벤트 경로가 추가되어 요청이 전달됩니다.

요청 구조

모든 콜백 이벤트는 다음과 같은 공통 구조를 따릅니다:

주요 특징

• HTTP 메서드: 모든 콜백 이벤트는 POST 메서드를 사용합니다.
• Content-Type: application/json 형식으로 전송됩니다.
• 엔드포인트: 각 이벤트는 /events/{이벤트타입} 형식의 고유한 경로를 가집니다.
• 요청 본문: 이벤트 타입에 따라 다른 JSON 스키마를 가집니다.

참고:

• 사용 가능한 모든 콜백 이벤트 목록과 각 이벤트의 상세한 요청 스키마는 API 레퍼런스의 콜백 이벤트 섹션에서 확인할 수 있습니다.

3.2 콜백 응답 처리

콜백을 정상적으로 수신했다면 HTTP 200 OK 응답과 아래 객체를 Response Body로 반환해야 합니다:

3.3 방화벽 설정 (필수)

콜백을 정상적으로 수신하려면 카플랫 서버 IP에 대한 방화벽 설정이 필수입니다.
방화벽 설정 방법은 방화벽 및 보안 프로토콜 페이지를 참고해주세요

콜백 URL로 등록한 서버에서 다음 방화벽 규칙을 설정해야 합니다:

1. 인바운드 규칙: 카플랫 서버에서 콜백 서버로의 HTTP/HTTPS 요청 허용
2. 아웃바운드 규칙: 콜백 서버에서 카플랫 서버로의 응답 허용

방화벽 설정 예시

참고: 정확한 카플랫 서버 IP 주소는 API 키 발급 시 함께 안내됩니다.

3.4 보안 고려사항

1. HTTPS 필수: 콜백 URL은 반드시 HTTPS를 사용해야 합니다.
2. IP 화이트리스트: 카플랫 서버 IP만 허용하도록 방화벽을 설정하세요.