빠른 활동 API 개요
신속한 액티비티 API로 여행자가 액티비티와 체험을 예약할 수 있도록 지원하세요.
얼리 액세스 미리 보기
이 문서는 일부 파트너에게만 제공되는 얼리 액세스 미리 보기 이니셔티브의 일부입니다. 파일럿 프로그램은 2026년 2분기에 시작되며, 2027년에 정식 출시될 예정입니다.
파일럿 또는 베타 파트너가 되고 싶다면 담당 계정 관리자에게 문의하세요.
신속한 액티비티 API 는 통합하기 쉬운 쇼핑 및 예약 흐름( end-to-end )을 통해 여행자에게 액티비티를 노출할 수 있도록 설계되었습니다. 이를 통해 여행자에게 보다 총체적인 경험을 제공하는 동시에 새로운 수익원을 창출할 수 있습니다.
주요 개념
- 활동: 예약 가능한 이벤트(보여 주고 판매하는 상품).
- 활동 그룹: 유사한 활동의 묶음입니다.
- 경험: 여러 활동을 포함할 수 있는 개념/마케팅 래퍼입니다.
- 티켓: 액티비티의 티켓 유형(성인/어린이/유아 등).
- 일정: 하나의 액티비티와 하나 이상의 티켓이 포함된 예약(액티비티 예약)입니다.
- 카테고리: High-level 체험과 활동을 테마로 분류하는 그룹(예: 시티 투어, 박물관 또는 야외 활동).
- 속성: 체험 또는 활동의 특정 특성을 설명하는 플래그(예: 휠체어 이용 가능, 가족 친화적, 가이드 투어, 줄 건너뛰기 등)를 표시합니다.
엔드투엔드 통합 흐름
이 API를 사용한 예약 활동은 다음과 같은 일반적인 흐름을 따릅니다.
1단계: 인벤토리 검색
목적지에서 판매할 수 있는 상품을 파악하고 상품화할 준비가 된 목적지별 활동의 구조화된 카탈로그를 만드세요.
- 지역 매핑 엔드포인트를 사용하여 지리 API 지역 을 기본 인벤토리(경험, 활동 및 활동 그룹)에 매핑합니다. 참고: 활동 API는 이 반복에서
region_ID매개변수만 지원합니다. - 여러 언어로 된 풍부한 활동 콘텐츠(제목, 설명, 이미지, 위치, 카테고리)를 가져옵니다.
- 액티비티에 대한 게스트 평점과 후기를 가져와 여행자가 옵션을 비교하고 경험에 대한 신뢰를 쌓을 수 있도록 도와주세요.
- 검색 결과, 활동 상세 페이지, 필터(예: 가족 친화적 또는 도보 여행)를 채웁니다.
2단계: 이용 가능 여부 및 가격 검색
액티비티 이용 가능 시기와 가격을 확인하세요. 예약 가능한 날짜/시간, 티켓 옵션 및 가격대를 활용하여 쇼핑 여정을 강화하세요.
- 구체적인 액티비 티와 날짜는 티켓 유형별로 이용 가능 여부와 가격을 요청하세요.
- 구매자 환경에서 캘린더(사용 가능/사용 불가능한 날짜), 시간대 및 시작 가격을 표시합니다.
- 한 번의 통화로 여러 활동을 지원하세요.
3단계: Pre-booking 가격 확인
결제 전에 최종 예약 가능 가격을 확인하고 필수 예약 필드 목록을 확인하세요. 최신 인벤토리 및 정책에 따라 확정된 오퍼와 예약 토큰을 받습니다.
- 특정 선택 항목(활동, 날짜, 시간, 티켓)을 실시간으로 검증합니다.
- 최종 가격, 세금/수수료, 구매 가능 여부(가격 변경 또는 품절 포함)를 확인할 수 있습니다.
- 필수 예약 필드(예: 승객 세부 정보 또는 pick-up 유형)와 예약을 위한 보안 토큰에 대한 세부 정보를 확인하세요.
4단계: 예약 만들기
확정된 선택을 예약으로 전환합니다. 자체 시스 템에서 표시하고 관리할 수 있는 일정(예약) 확인을 받습니다.
- 쇼핑 플로우의 예약 토큰을 쿼리 매개변수로 보내고, 요청 본문에 결제 API의
payment_token을 여행자 세부 정보(기본 여행자 및 추가 여행자)와 함께 전송합니다. - 나중에 예약을 조정하고 검색할 수 있도록 제휴사 참조를 포함하세요.
- 예약 세부 정보를 검색할 수 있는 일정 ID와 링크를 받습니다.
5단계: 예약 관리
고객과 상담원을 위한 예약 후 워크플로우를 지원합니다. 예약 후 전체 도구 세트에 액세스하여 기존 예약을 확인하고, 취소하고, 바우처를 제공할 수 있습니다.
- 일정 ID 또는 제휴사 참조로 예약 세부 정보를 검색합니다.
- 허용되는 경우 예약을 취소하고 결과 상태를 고객에게 표시합니다.
- 고객이 활동에서 제시할 바우처 문서를 검색합니다.
오류 응답 테스트
지정된 빠른 활동 API 메서드에 대한 테스트 요청을 보내려면 쇼핑 또는 예약 요청에 test이라는 추가 HTTP 헤더를 포함하고 아래 표에서 적절한 값을 사용하세요. 테스트 헤더를 보내지 않거나 잘못된 테스트 헤더를 보내면 요청이 실시간으로 처리됩니다.
참고: 테스트 헤더를 사용하면 정적 응답 메시지가 생성되므로 반환되는 비율 및 콘텐츠가 테스트 중인 활동과 관련이 없을 수 있습니다.
쇼핑 및 콘텐츠 API
| 테스트 헤더 값 | HTTP 코드 및 응답 | 상태 |
|---|---|---|
| 표준형 | 200 확인(표준 성공 응답) | 성공 |
invalid_input | 400 잘못된 요청(잘못된 입력) | 오류 |
bad_link | 400 잘못된 요청(불량 링크) | 오류 |
internal_server_error | 500 내부 서버 오류(알 수 없는 오류) | 오류 |
service_unavailable | 503 서비스를 사용할 수 없습니다. | 오류 |
예약 API
| 테스트 헤더 값 | HTTP 코드 및 응답 | 상태 |
|---|---|---|
| 표준형 | 200 확인(표준 성공 응답) | 성공 |
invalid_input | 400 잘못된 요청(잘못된 입력) | 오류 |
bad_link | 400 잘못된 요청(불량 링크) | 오류 |
price_mismatch | 409 충돌(가격 불일치) | 오류 |
sold_out | 409 충돌 (매진) | 오류 |
internal_server_error | 500 내부 서버 오류(알 수 없는 오류) | 오류 |
service_unavailable | 503 서비스를 사용할 수 없습니다. | 오류 |
사용 사례별 엔드포인트 요약
| 사용 사례 | 방법 및 경로 | 필수 쿼리 매개변수/설명 |
|---|---|---|
| 지역별 경험 | GET /regions/{region_id}/experiences | language |
| 지역 활동 그룹 | GET /regions/{region_id}/activity-groups | language |
| 지역 활동 | GET /regions/{region_id}/activities | language |
| 콘텐츠 경험 | GET /experiences/content | experience_id[], language |
| 활동 그룹 콘텐츠 | GET /experiences/activity-groups/content | language, activity_group_id[] |
| 활동 콘텐츠 | GET /experiences/activities/content | activity_id[], language |
| 활동 운영 시간 | GET /experiences/activities/{activity_id}/operating-hours | start_date, end_date (≤ 90일),language |
| 경험 카테고리 | GET /experiences/categories | language, pagination_size |
| 경험 속성 | GET /experiences/attributes | language, pagination_size |
| 활동 카테고리 | GET /experiences/activities/categories | language, pagination_size |
| 활동 속성 | GET /experiences/activities/attributes | language, pagination_size |
| 고객 이용 후기 | GET /experiences/activities/{activity_id}/guest-reviews | limit, sort |
| 예약 가능 객실및 요금 | GET /experiences/activities/availability | activity_id[], start_date, end_date (≤14), currency,language |
| 예약 가능 객실 달력 | GET /experiences/activities/calendars/availability | activity_id[], start_date,end_date |
| 요금 확인 | GET /experiences/activities/{activity_id}/price-check | token (조회 API 호출에서), tickets |
| 예약 생성 | POST /itineraries/activity | 쿼리: token (일정 호출에서), 본문: CreateItineraryRequest, affiliate_reference_id, payment_token,primary_traveler |
| 조회 API ID로 검색하기 | GET /itineraries/{itinerary_id}/activity | — |
| 제휴사 참조로 검색 | GET /itineraries/activity | affiliate_reference_id |
| 예약 취소 | DELETE /itineraries/{itinerary_id}/activity | 204(예약이 성공적으로 취소됨), 202 (상태 불명) |
| 바우처 검색 | GET /itineraries/{itinerary_id}/activity/voucher | 예약한 액티비티의 바우처를 검색할 수 있는 반품 링크 |
참고:[] 뒤에 오는 매 개변수는 comma-separated 배열에 여러 값을 가질 수 있음을 나타냅니다.
API 세부 정보
이 페이지의 activity-related 엔드포인트 정의를 살펴본 다음 Postman과 같은 테스트 소프트웨어를 사용하여 예제와 스키마 정의가 실제 출력과 어떻게 비교되는지 파악하세요. 이 API가 파일럿 단계를 지나면 해당 엔드포인트는 API Explorer 에도 포함될 예정입니다.