> # MyRealTrip Partner API Documentation
> https://docs.myrealtrip.com
>
> 마이리얼트립 파트너 API 공식 문서입니다. 수익 현황 조회, 예약 정보 확인, API 키 발급 등
> 마케팅 파트너 연동에 필요한 모든 정보를 제공합니다.
>
> 라이선스: AI 학습 및 재배포 시 출처(docs.myrealtrip.com)를 명시해주세요.


---

# 시작하기

마이리얼트립 파트너 API를 사용하여 수익 현황과 예약 정보를 조회하세요. 아래 단계를 따라하면 첫 API 호출까지 완료할 수 있습니다.

## 온보딩 단계

### 파트너 가입

파트너 페이지에서 마케팅 파트너로 가입합니다.

### API 키 발급

파트너 페이지 → 좌측 메뉴 "Open API" → "API Key 발급" 버튼을 클릭합니다.

### 첫 API 호출 테스트

아래 명령어를 복사해서 터미널에 붙여넣기 하세요. `YOUR_API_KEY`를 실제 키로 교체하면 됩니다. 각 API 문서의 Try it 탭에서 파라미터를 입력하면 바로 실행 가능한 코드를 생성할 수도 있습니다.

```bash
curl -X GET \\
  "https://partner-ext-api.myrealtrip.com/v1/revenues\\
?dateSearchType=SETTLEMENT\\
&startDate=2025-01-01\\
&endDate=2025-01-07" \\
  -H "Authorization: Bearer YOUR_API_KEY"
```

```python
import requests

API_KEY = "YOUR_API_KEY"
BASE_URL = "https://partner-ext-api.myrealtrip.com"

response = requests.get(
    f"{BASE_URL}/v1/revenues",
    headers={"Authorization": f"Bearer {API_KEY}"},
    params={
        "dateSearchType": "SETTLEMENT",
        "startDate": "2025-01-01",
        "endDate": "2025-01-07",
    },
)

print(response.status_code)
print(response.json())
```

```javascript
const API_KEY = process.env.PARTNER_API_KEY;

const params = new URLSearchParams({
  dateSearchType: "SETTLEMENT",
  startDate: "2025-01-01",
  endDate: "2025-01-07",
});

const response = await fetch(
  \`https://partner-ext-api.myrealtrip.com/v1/revenues?\${params}\`,
  {
    headers: { Authorization: \`Bearer \${API_KEY}\` },
  }
);

const data = await response.json();
console.log(data);
```

성공 응답 예시 (200 OK)

### 프로덕션 연동

테스트가 완료되면 프로덕션 환경에 연동합니다. 아래 체크리스트를 확인하세요.

## Base URL

모든 API 요청은 HTTPS를 통해 이 Base URL에 전송합니다. HTTP 요청은 지원하지 않습니다.

## 응답 형식

### 공통 응답 구조

모든 API 응답은 다음과 같은 공통 구조를 따릅니다:

### 응답 필드 설명

API 호출 결과 데이터. 목록 조회 시 배열, 단건 조회 시 객체로 반환됩니다.

페이지네이션 정보 등 부가 정보. `totalCount`로 전체 건수를 확인할 수 있습니다.

요청 처리 결과. `status` (HTTP 상태코드), `message`, `code`를 포함합니다.

---

# 인증 및 헤더

API 요청 시 필요한 인증 방식과 HTTP 헤더 설정에 대해 안내합니다.

## 인증 방식

### Bearer 토큰 인증

HTTP Authorization 헤더에 Bearer 스키마를 사용하여 API 키를 전달합니다.

```http
Authorization: Bearer YOUR_API_KEY
```

### 헤더 구성

Bearer 토큰 형식의 API 키를 포함하는 헤더

요청 본문의 미디어 타입 (일반적으로 `application/json`)

## 인증 요청 예제

### 올바른 인증 요청

```bash
curl -X GET \\
  "https://partner-ext-api.myrealtrip.com/v1/revenues\\
?startDate=2025-01-01&endDate=2025-01-07&dateSearchType=SETTLEMENT" \\
  -H "Authorization: Bearer YOUR_API_KEY"
```

### 잘못된 인증 요청

❌ Authorization 헤더 누락

```bash
curl -X GET \\
  "https://partner-ext-api.myrealtrip.com/v1/revenues\\
?startDate=2025-01-01&endDate=2025-01-07"
```

❌ Bearer 접두사 누락

```bash
curl -X GET \\
  "https://partner-ext-api.myrealtrip.com/v1/revenues\\
?startDate=2025-01-01&endDate=2025-01-07" \\
  -H "Authorization: YOUR_API_KEY"
```

---

# 기타 헤더

API 요청 시 사용할 수 있는 추가 HTTP 헤더 설정에 대해 알아봅니다.

## 필수 헤더

API 인증을 위한 Bearer 토큰을 포함하는 헤더입니다.

형식

```http
Authorization: Bearer YOUR_API_KEY
```

예제

```http
Authorization: Bearer test_sk_aBcDeFgHiJkLmNoPqRsTuVwXyZ1234567890
```

요청 본문의 미디어 타입을 지정합니다. POST, PUT 요청 시 필수입니다.

지원 타입

- `application/json` - JSON 형식 (권장)

예제

```http
Content-Type: application/json
```

## 선택 헤더

클라이언트가 처리할 수 있는 응답 미디어 타입을 지정합니다.

기본값

```http
Accept: application/json
```

선호하는 응답 언어를 지정합니다. 다국어 오류 메시지 지원에 사용됩니다.

지원 언어

- `ko-KR` - 한국어

- `en-US` - 영어

예제

```http
Accept-Language: ko-KR
```

요청을 추적하기 위한 고유 식별자입니다. 디버깅 및 로깅에 유용합니다.

형식

UUID 또는 고유한 문자열 (최대 128자)

```http
X-Request-ID: 550e8400-e29b-41d4-a716-446655440000
```

API를 호출하는 클라이언트 애플리케이션 정보를 제공합니다.

권장 형식

```http
User-Agent: MyApp/1.0.0 (contact@example.com)
```

## 응답 헤더

API 응답에 포함되는 주요 헤더 정보입니다.

응답 본문의 미디어 타입 (일반적으로 `application/json`)

요청 시 제공한 Request ID 또는 서버에서 생성한 고유 ID

시간 단위당 최대 허용 요청 수

현재 시간 윈도우에서 남은 요청 수

## 완전한 요청 예제

모든 권장 헤더를 포함한 완전한 API 요청 예제입니다.

```bash
curl -X GET "https://partner-ext-api.myrealtrip.com/v1/revenues?startDate=2025-01-01&endDate=2025-01-07" \\
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -H "Accept: application/json" \\
  -H "Accept-Language: ko-KR" \\
  -H "X-Request-ID: 550e8400-e29b-41d4-a716-446655440000" \\
  -H "User-Agent: MyApp/1.0.0 (contact@example.com)"
```

## JavaScript 전체 예제

```javascript
const apiKey = process.env.PARTNER_API_KEY;
const baseUrl = "https://partner-ext-api.myrealtrip.com";

// UUID 생성 함수
function generateUUID() {
  return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, function(c) {
    const r = Math.random() * 16 | 0;
    const v = c === 'x' ? r : (r & 0x3 | 0x8);
    return v.toString(16);
  });
}

async function makeApiRequest(endpoint, method = 'GET', body = null) {
  const headers = {
    'Authorization': \`Bearer \${apiKey}\`,
    'Content-Type': 'application/json',
    'Accept': 'application/json',
    'Accept-Language': 'ko-KR',
    'X-Request-ID': generateUUID(),
    'User-Agent': 'MyApp/1.0.0 (contact@example.com)'
  };

  const options = {
    method,
    headers,
  };

  if (body) {
    options.body = JSON.stringify(body);
  }

  try {
    const response = await fetch(\`\${baseUrl}\${endpoint}\`, options);
    
    // 응답 헤더 로깅
    console.log('Request ID:', response.headers.get('X-Request-ID'));
    console.log('Rate Limit:', response.headers.get('X-RateLimit-Remaining'));
    
    if (!response.ok) {
      throw new Error(\`HTTP error! status: \${response.status}\`);
    }
    
    return await response.json();
  } catch (error) {
    console.error('API Error:', error);
    throw error;
  }
}

// 사용 예제
const params = new URLSearchParams({
  startDate: '2025-01-01',
  endDate: '2025-01-07'
});
makeApiRequest(\`/v1/revenues?\${params}\`, 'GET')
  .then(data => console.log('Success:', data))
  .catch(error => console.error('Error:', error));
```

## Rate Limiting

API는 Rate Limiting을 통해 과도한 요청을 제한합니다.

기본 제한

API별 요청 제한 (각 문서 참고)

제한 초과 시

HTTP 429 (Too Many Requests) 응답

모니터링

응답 헤더의 `X-RateLimit-Remaining`을 확인하여 남은 요청 수를 모니터링하세요.

---

# API 키

API 키는 파트너 계정을 식별하고 API 접근 권한을 확인하는 인증 수단입니다.

## API 키 발급

파트너 페이지 접속

관리자 계정으로 파트너 페이지에 로그인합니다.

Open API 메뉴로 이동

좌측의 "Open API" 메뉴를 클릭하고 "API Key 발급"을 선택합니다.

API 키 생성

"API Key 발급" 버튼을 클릭하여 키를 생성합니다.

안전하게 보관

발급된 API 키는 다시 확인할 수 없으므로 안전한 곳에 보관하세요.

## API 키 관리

### 키 조회 및 재발급

발급된 API 키는 파트너 페이지에서 조회하고 관리할 수 있습니다. 보안을 위해 키의 전체 값은 생성 시점에만 확인할 수 있으며, 이후에는 마스킹 처리되어 표시됩니다.

- 키 조회: 파트너 페이지에서 현재 활성화된 API 키를 확인할 수 있습니다.

키 조회: 파트너 페이지에서 현재 활성화된 API 키를 확인할 수 있습니다.

- 키 재발급: API 키를 재발급하면 새로운 키가 생성되며, 기존에 발행했던 키는 자동으로 만료됩니다. 만료된 키로는 더 이상 API를 호출할 수 없습니다.

키 재발급: API 키를 재발급하면 새로운 키가 생성되며, 기존에 발행했던 키는 자동으로 만료됩니다. 만료된 키로는 더 이상 API를 호출할 수 없습니다.

## API 키 사용 방법

API 요청 시 Authorization 헤더에 Bearer 토큰 형식으로 API 키를 포함합니다. 더 자세한 인증 방법은 인증 및 헤더에서 확인하세요.

```http
Authorization: Bearer YOUR_API_KEY
```

### cURL 예제

```bash
curl -X GET \\
  "https://partner-ext-api.myrealtrip.com/v1/revenues\\
?startDate=2025-01-01&endDate=2025-01-07&dateSearchType=SETTLEMENT" \\
  -H "Authorization: Bearer YOUR_API_KEY"
```

### JavaScript 예제

```javascript
const apiKey = process.env.PARTNER_API_KEY;

const params = new URLSearchParams({
  startDate: "2025-01-01",
  endDate: "2025-01-07",
  dateSearchType: "SETTLEMENT"
});

const response = await fetch(\`https://partner-ext-api.myrealtrip.com/v1/revenues?\${params}\`, {
  method: "GET",
  headers: {
    "Authorization": \`Bearer \${apiKey}\`
  }
});

const data = await response.json();
```

## 보안 주의사항

- 환경 변수 사용: API 키는 환경 변수나 비밀 관리 시스템에 저장하세요.

환경 변수 사용: API 키는 환경 변수나 비밀 관리 시스템에 저장하세요.

- 서버 사이드에서만 사용: 클라이언트(브라우저) 코드에 API 키를 포함하지 마세요.

서버 사이드에서만 사용: 클라이언트(브라우저) 코드에 API 키를 포함하지 마세요.

- 주기적인 갱신: 보안을 위해 정기적으로 API 키를 교체하는 것을 권장합니다.

주기적인 갱신: 보안을 위해 정기적으로 API 키를 교체하는 것을 권장합니다.

- 노출 시 조치: API 키가 노출된 경우 즉시 대시보드에서 새로운 키를 재발급받으세요. 재발급하면 기존 키는 자동으로 만료됩니다.

노출 시 조치: API 키가 노출된 경우 즉시 대시보드에서 새로운 키를 재발급받으세요. 재발급하면 기존 키는 자동으로 만료됩니다.

## API 키 에러

API 키 사용 시 발생할 수 있는 오류와 해결 방법입니다.

인증에 실패했습니다. API 키가 누락되었거나 유효하지 않습니다.

응답 예시:

해결 방법:

- Authorization 헤더에 `Bearer YOUR_API_KEY` 형식으로 API 키를 포함했는지 확인

- 재발급이 필요한 경우 파트너 페이지에서 새 키로 교체

- 공백이나 줄바꿈이 포함되지 않았는지 확인

해당 API 키는 리소스 사용 권한이 없습니다. API 키는 유효하지만 요청한 리소스에 대한 접근 권한이 없습니다.

응답 예시:

해결 방법:

- API 키를 발급했던 계정으로 새로운 키 발급 후 교체

- 여전히 문제가 발생하는 경우 marketing_partner@myrealtrip.com으로 문의

---

# 에러 코드

API 요청 실패 시 반환되는 HTTP 상태 코드와 대응 방법을 안내합니다.

## 에러 코드 목록

## 에러 상세 가이드

### {error.title}

{error.description}

발생 원인

- • {c}

해결 방법

- → {s}

응답 예시

## 재시도 전략

### Exponential Backoff

429, 500, 503 에러 발생 시 아래와 같은 재시도 전략을 권장합니다.

최대 3회까지 재시도하고, 여전히 실패하면 에러를 기록하고 나중에 다시 시도하세요.

```javascript
async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url, options);

    if (response.ok) return response.json();

    // 재시도 가능한 에러인 경우
    if ([429, 500, 503].includes(response.status)) {
      const delay = Math.pow(2, i) * 1000; // 1s, 2s, 4s
      console.log(\`Retry \${i + 1}/\${maxRetries} after \${delay}ms\`);
      await new Promise(resolve => setTimeout(resolve, delay));
      continue;
    }

    // 재시도 불가능한 에러 (400, 401, 403, 404)
    const error = await response.json();
    throw new Error(\`API Error \${response.status}: \${error.result?.message}\`);
  }
  throw new Error("Max retries exceeded");
}
```


### 400 Bad Request
요청 파라미터가 올바르지 않습니다.

**원인:**
- 필수 파라미터 누락 (예: startDate, endDate)
- 파라미터 형식 오류 (예: 날짜 형식이 yyyy-MM-dd가 아닌 경우)
- 유효하지 않은 파라미터 값 (예: startDate가 endDate보다 이후인 경우)

**해결 방법:**
- 각 API 문서의 파라미터 설명을 확인하세요
- 날짜는 yyyy-MM-dd 형식을 사용하세요 (예: 2025-01-01)
- 필수(required) 파라미터가 모두 포함되어 있는지 확인하세요

```json
{ result: { status: 400, message: "잘못된 요청입니다. 파라미터를 확인해주세요.", code: "BAD_REQUEST" } }
```

### 401 Unauthorized
인증에 실패했습니다. API 키가 누락되었거나 유효하지 않습니다.

**원인:**
- Authorization 헤더가 누락된 경우
- Bearer 접두사 없이 API 키만 전달한 경우
- 만료되었거나 재발급된 이전 API 키를 사용한 경우
- API 키에 공백이나 줄바꿈이 포함된 경우

**해결 방법:**
- 헤더 형식 확인: Authorization: Bearer YOUR_API_KEY
- 파트너 페이지에서 현재 활성화된 API 키를 확인하세요
- 키 재발급이 필요한 경우 파트너 페이지에서 새 키를 발급받으세요

```json
{ result: { status: 401, message: "인증에 실패했습니다 : Invalid API Key" } }
```

### 403 Forbidden
API 키는 유효하지만 요청한 리소스에 대한 접근 권한이 없습니다.

**원인:**
- 해당 API에 대한 접근 권한이 없는 API 키를 사용한 경우
- 파트너 계정의 API 접근 권한이 비활성화된 경우

**해결 방법:**
- 파트너 페이지에서 API 접근 권한을 확인하세요
- 권한 문의는 marketing_partner@myrealtrip.com 으로 요청하세요

```json
{ result: { status: 403, message: "해당 API Key 는 리소스 사용 권한이 없습니다" } }
```

### 404 Not Found
요청한 엔드포인트 또는 리소스를 찾을 수 없습니다.

**원인:**
- 엔드포인트 URL 오타 (예: /v1/revenue → /v1/revenues)
- 존재하지 않는 API 버전 사용
- Base URL이 올바르지 않은 경우

**해결 방법:**
- Base URL 확인: https://partner-ext-api.myrealtrip.com
- 엔드포인트 경로를 API 문서와 정확히 비교하세요
- 사용 가능한 API 목록은 좌측 사이드바에서 확인할 수 있습니다

```json
{ result: { status: 404, message: "요청한 리소스를 찾을 수 없습니다", code: "NOT_FOUND" } }
```

### 429 Too Many Requests
요청 한도를 초과했습니다. Rate Limit이 적용됩니다.

**원인:**
- API별 분당 요청 한도를 초과한 경우
- 짧은 시간 내 대량의 API 호출을 실행한 경우

**해결 방법:**
- 요청 간 적절한 간격을 두세요 (최소 1초)
- 응답 헤더의 X-RateLimit-Remaining 값으로 남은 요청 수를 모니터링하세요
- 429 응답 시 잠시 대기 후 재시도하세요 (Exponential Backoff 권장)

```json
{ result: { status: 429, message: "요청 한도를 초과했습니다. 잠시 후 다시 시도해주세요.", code: "TOO_MANY_REQUESTS" } }
```

### 500 Internal Server Error
서버 내부 오류가 발생했습니다.

**원인:**
- 서버 측 일시적인 오류
- 예상치 못한 서버 장애

**해결 방법:**
- 잠시 대기 후 동일한 요청을 재시도하세요
- 지속적으로 발생하면 요청 시간과 에러 응답을 포함하여 문의하세요
- 문의: marketing_partner@myrealtrip.com

```json
{ result: { status: 500, message: "서버 내부 오류가 발생했습니다", code: "INTERNAL_SERVER_ERROR" } }
```

### 503 Service Unavailable
서비스가 일시적으로 이용 불가합니다.

**원인:**
- 서버 점검 중
- 일시적인 과부하 상태

**해결 방법:**
- 몇 분 후 재시도하세요
- 30분 이상 지속되면 문의해 주세요
- 문의: marketing_partner@myrealtrip.com

```json
{ result: { status: 503, message: "서비스가 일시적으로 이용 불가합니다", code: "SERVICE_UNAVAILABLE" } }
```


---

# 보안

파트너 API를 안전하게 사용하기 위한 보안 정책 및 접근 제어 방법입니다.

## 인증 방식

### API Key 인증

파트너 API는 API 키 인증을 사용합니다. 유효한 API 키가 포함된 요청만 허용됩니다.

- API Key: Authorization 헤더에 Bearer 토큰으로 전송

API Key: Authorization 헤더에 Bearer 토큰으로 전송

## 전송 보안

### HTTPS 사용

모든 API 요청은 HTTPS를 통해 전송되어야 합니다.

Base URL

```text
https://partner-ext-api.myrealtrip.com
```

### TLS 버전

TLS 1.2 이상의 버전을 사용해야 합니다.

- 지원 TLS 1.2 이상

TLS 1.2 이상

- 미지원 TLS 1.1 이하, SSL

TLS 1.1 이하, SSL

## 레이트 리밋

안정적인 서비스 제공을 위해 API별 분당 요청 제한이 적용됩니다.

- 제한 초과 시 HTTP 429 (Too Many Requests) 응답이 반환됩니다.

제한 초과 시 HTTP 429 (Too Many Requests) 응답이 반환됩니다.

- 응답 헤더의 `X-RateLimit-Remaining`으로 남은 요청 수를 확인할 수 있습니다.

응답 헤더의 `X-RateLimit-Remaining`으로 남은 요청 수를 확인할 수 있습니다.

## 오류 응답

요청 실패 시 HTTP 상태 코드와 함께 에러 정보가 반환됩니다. 주요 에러 코드:

인증 실패 — API 키 확인

접근 거부 — API 접근 권한 확인

요청 한도 초과 — Rate Limit

서버 오류 — 재시도 필요

---

# 마이 링크

마이리얼트립 광고 링크를 생성하는 두 가지 방법을 안내합니다.

## 링크 생성 방법 개요

### URL 파라미터로 광고 링크 만들기

마이리얼트립 URL에 트래킹 파라미터를 직접 붙여 광고 링크로 사용합니다.

- API 연동 불필요

- 모든 MRT 페이지에 적용 가능

- 성과 추적용 클릭 ID 지원

### 마이링크 생성 API

`POST /v1/mylink` API로 단축 URL(myrealt.rip)을 생성합니다.

- 단축 URL 자동 생성

- 대량 링크 프로그래밍 생성

- 시스템 연동에 적합

## URL 파라미터로 광고 링크 만들기

마이리얼트립의 URL에 트래킹 파라미터를 직접 붙여 광고 링크로 사용할 수 있습니다. 메인홈, 상품 상세, 검색 결과, 프로모션 등 비항공 페이지에 적용됩니다. 항공 상품은 전용 랜딩 URL이 필요하며 하단에서 별도 안내합니다.

### 파라미터

마이리얼트립에서 발급한 파트너 식별 ID

파트너사에서 발급한 성과 추적용 클릭 ID. 클릭마다 반드시 유니크할 필요는 없습니다.

모바일에서 앱 설치 시 자동 오픈. `true` 설정 시 활성화, 생략 시 웹 랜딩.

### 예시 링크

### mylink_id를 모르시나요?

`mylink_id`는 마이리얼트립에서 발급한 파트너 식별 ID로, 한 번 확인하면 동일 파트너 계정에서 계속 사용할 수 있습니다.

마이리얼트립 파트너 페이지에서 전용 광고 링크(myrealt.rip)를 만들어 주세요.

전용 광고 링크를 그대로 브라우저에서 클릭합니다.

전용 광고 링크 : `https://myrealt.rip/ABCDEFG`

리다이렉트된 최종 URL에서 `mylink_id` 값을 확인합니다.

최종 랜딩 링크 : `https://www.myrealtrip.com/?mylink_id=1234567&utm_source=mktpartner`

## 마이링크 생성 API

단축 URL(myrealt.rip)을 프로그래밍 방식으로 생성합니다. 대량 링크 생성이나 시스템 연동이 필요한 경우 사용하세요.

## 항공 마이링크 생성

항공 상품은 일반 URL이 아닌 전용 랜딩 URL이 필요합니다. 아래 2단계로 마이링크를 생성하세요.

### 항공 랜딩 URL 생성

`GET /v1/products/flight/fare-query-landing-url` API로 항공 검색 랜딩 URL을 생성합니다.

```bash
curl -X GET \\
  "https://partner-ext-api.myrealtrip.com/v1/products/flight/fare-query-landing-url\\
?depAirport=GMP&arrAirport=CJU&depdt=2026-06-01&adult=2" \\
  -H "Authorization: Bearer YOUR_API_KEY"
```

응답 예시:

```json
{
  "data": "https://flights.myrealtrip.com/air/agent/b2c/AIR/GMP/CJU/offers.k1?depdt=2026-06-01&adult=2&..."
}
```

### 마이링크로 변환

1단계에서 받은 항공 URL을 `POST /v1/mylink`의 `targetUrl`로 전달해 단축 링크를 생성합니다.

```bash
curl -X POST \\
  "https://partner-ext-api.myrealtrip.com/v1/mylink" \\
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{"targetUrl": "https://flights.myrealtrip.com/air/agent/b2c/..."}'
```

응답 예시:

```json
{
  "data": { "mylink": "https://myrealt.rip/abc123def456" }
}
```

## 실전 예시: 상품 검색 후 마이링크 생성

투어티켓 조회 API로 상품을 찾은 뒤, 해당 상품 URL로 마이링크를 생성하는 전체 플로우입니다.

### 투어티켓 상품 검색

`POST /v1/products/tna/search`로 원하는 도시의 상품을 검색합니다. 응답의 `itemId`를 사용해 상품 URL을 구성합니다.

```bash
curl -X POST \\
  "https://partner-ext-api.myrealtrip.com/v1/products/tna/search" \\
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{"city": "오사카", "category": "ticket_v2", "page": 1, "perPage": 10}'
```

응답에서 `itemId` 추출:

```json
{
  "data": {
    "items": [
      { "itemId": 3000009, "itemName": "오사카 유니버설 스튜디오 재팬 입장권", ... }
    ]
  }
}
```

### 상품 URL 구성

`itemId`로 마이리얼트립 상품 상세 URL을 만듭니다.

```text
https://www.myrealtrip.com/offers/{itemId}
# 예시
https://www.myrealtrip.com/offers/3000009
```

### 마이링크 생성

구성한 상품 URL을 `POST /v1/mylink`에 전달해 단축 링크를 생성합니다.

```bash
curl -X POST \\
  "https://partner-ext-api.myrealtrip.com/v1/mylink" \\
  -H "Authorization: Bearer YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{"targetUrl": "https://www.myrealtrip.com/offers/3000009"}'
```

응답:

```json
{
  "data": { "mylink": "https://myrealt.rip/abc123def456" }
}
```

---

# MCP 개요

MCP(Model Context Protocol)를 통해 AI 도구에서 마이리얼트립의 항공편, 숙소, 투어/액티비티 검색 기능을 사용할 수 있습니다.

## 엔드포인트

## 활용 예시

"내일 제주도 가는 항공편 찾아줘"

도구: searchDomesticFlights

최저가 편도 가격, 항공사별 운항 정보를 실시간으로 조회합니다.

"부산 해운대 근처 호텔 추천해줘"

도구: searchStays

평점, 가격, 리뷰 정보를 포함한 숙소 목록을 반환합니다.

"오사카 유니버설 스튜디오 티켓 찾아줘"

도구: searchTnas

1일권, 익스프레스 패스 등 다양한 옵션과 날짜별 가격을 조회합니다.

# 제공 도구

MCP 서버에서 제공하는 도구 목록입니다. AI 클라이언트가 자동으로 도구를 인식하여 사용합니다.

## 숙소 (Stay)

목적지, 체크인/아웃 날짜로 숙소를 검색합니다.

숙소 상세 정보, 객실, 리뷰, 편의시설을 조회합니다.

## 항공 (Flight)

국내선 항공편을 검색합니다. (김포-제주, 김포-부산 등)

국제선 항공편을 검색합니다. (일본, 동남아, 유럽 등)

현재 프로모션 중인 항공사 목록을 조회합니다.

날짜별 최저가 비교 캘린더를 조회합니다.

## 투어/액티비티 (TNA)

투어, 티켓, 액티비티, 체험 상품을 검색합니다.

상품 상세 설명, 이미지, 리뷰를 조회합니다.

날짜별 예약 가능 여부와 실제 가격을 확인합니다.

도시별 카테고리 목록을 조회합니다.

## 공통 (Common)

현재 한국 시간(KST)을 조회합니다.

# 연결 가이드

AI 클라이언트별 MCP 서버 연결 방법입니다. 엔드포인트 주소 하나로 설정할 수 있습니다.

## Claude Desktop

설정 열기

Claude Desktop에서 Settings를 엽니다.

커넥터 설정

커넥터 메뉴에서 사용자 지정 탭으로 이동합니다.

커스텀 커넥터 추가

+ 버튼을 클릭하고 커스텀 커넥터 추가를 선택합니다.

정보 입력

아래와 같이 이름과 주소를 입력합니다.

```text
이름: myrealtrip\n주소: https://mcp-servers.myrealtrip.com/mcp
```

## Claude Code

터미널에서 아래 명령어를 실행합니다.

Claude Code를 시작하면 마이리얼트립 도구가 자동으로 로드됩니다.

## Cursor

MCP 설정 열기

Settings &rarr; Tools & MCP &rarr; "+ Add new MCP server"를 클릭합니다.

JSON 설정 추가

열린 mcp.json 파일에 아래 내용을 붙여넣습니다.

```json
{
  "mcpServers": {
    "myrealtrip": {
      "url": "https://mcp-servers.myrealtrip.com/mcp"
    }
  }
}
```

## Codex CLI

터미널에서 아래 명령어를 실행합니다.

Codex CLI를 시작하면 마이리얼트립 도구가 자동으로 로드됩니다.

## Gemini CLI

터미널에서 아래 명령어를 실행합니다.

Gemini CLI를 시작하고 `/mcp` 명령어로 연결 상태를 확인합니다.

## Windsurf

MCP 설정 열기

Settings &rarr; Manage MCPs &rarr; View raw config를 클릭하거나, `~/.codeium/windsurf/mcp_config.json` 파일을 직접 엽니다.

MCP 서버 추가

아래 내용을 추가합니다.

```json
{
  "mcpServers": {
    "myrealtrip": {
      "serverUrl": "https://mcp-servers.myrealtrip.com/mcp"
    }
  }
}
```

재시작

Windsurf를 재시작하면 마이리얼트립 도구를 사용할 수 있습니다.

## Cline

MCP 설정 열기

VS Code에서 Cline 아이콘 &rarr; MCP Servers &rarr; Remote Servers 탭을 선택합니다. 또는 Configure MCP Servers 버튼을 클릭하여 설정 파일을 직접 수정할 수 있습니다.

서버 추가

아래 설정을 추가합니다.

```json
{
  "mcpServers": {
    "myrealtrip": {
      "url": "https://mcp-servers.myrealtrip.com/mcp",
      "disabled": false
    }
  }
}
```

연결 확인

Cline이 자동으로 연결됩니다. 도구 목록이 표시되면 설정이 완료된 것입니다.

---

# 문의 및 지원

API 사용 중 문제가 발생하거나 궁금한 점이 있으시면 마이리얼트립에 문의해 주세요.

## 문의 방법

### 이메일 문의

API 관련 기술 지원이 필요하거나 상세한 문의사항이 있는 경우 이메일로 연락주세요.

## 문의 시 필요 정보

신속한 지원을 위해 아래 정보를 포함하여 문의해 주시면 빠른 답변이 가능합니다.

- 파트너 계정 정보: 파트너 페이지에 등록된 이메일

파트너 계정 정보: 파트너 페이지에 등록된 이메일

- 문의 API 엔드포인트: 문제가 발생한 API 경로 (예: /v1/revenues)

문의 API 엔드포인트: 문제가 발생한 API 경로 (예: /v1/revenues)

- 에러 메시지: 받은 에러 응답 전문

에러 메시지: 받은 에러 응답 전문

- 요청 시간: 문제가 발생한 날짜와 시간

요청 시간: 문제가 발생한 날짜와 시간

- 재현 방법: 문제를 재현할 수 있는 단계별 설명

재현 방법: 문제를 재현할 수 있는 단계별 설명

## 자주 묻는 질문

### Q. API 키를 분실했어요. 어떻게 해야 하나요?

A. API 키는 보안상 재확인이 불가능합니다. 파트너 페이지에서 API 키를 재발급받으세요. 재발급 시 기존 키는 자동으로 만료됩니다.

### Q. 401 에러가 발생합니다.

A. Authorization 헤더에 올바른 형식으로 API 키를 포함했는지 확인하세요. (Bearer YOUR_API_KEY)

### Q. 데이터 조회 시 결과가 비어있어요.

A. 조회 기간 내에 데이터가 없거나, 정산 기준일의 경우 아직 정산이 완료되지 않았을 수 있습니다. 데이터는 매일 오전 6시에 정산이 완료됩니다.

### Q. API 호출 횟수 제한이 있나요?

A. API별로 분당 요청 제한이 적용됩니다. 초과 시 429(Too Many Requests) 응답이 반환됩니다.

---

## API Reference

### POST /v1/mylink — 마이 링크 생성
태그: 마이 링크
마케팅 파트너용 마이 링크를 생성합니다. 생성 대상 URL은 마이리얼트립 도메인만 허용됩니다.

**파라미터:**
- `targetUrl` (body, 필수): 대상 URL (마이리얼트립 도메인만 허용) — 예시: `https://www.myrealtrip.com/offers/123`

**응답 필드:**
- `mylink` (string): 마이 링크

**응답 예시:**
```json
{ data: { mylink: "https://myrealt.rip/abc123def456" }, meta: {}, result: { status: 200, message: "SUCCESS", code: "success" }
```

### POST /v1/products/flight/fare-query-landing-url — 항공 운임 조회 랜딩 URL
태그: 마이 링크
항공 운임 조회를 위한 랜딩 URL을 생성합니다.

**파라미터:**
- `depAirportCd` (body, 필수): 출발 공항 코드 — 예시: `ICN`
- `arrAirportCd` (body, 필수): 도착 공항 코드 — 예시: `BKK`
- `tripTypeCd` (body, 필수): 여정유형 (OW: 편도, RT: 왕복, MT: 다구간) [가능한 값: "OW", "RT", "MT"] — 예시: `RT`
- `depDate` (body, 선택): 출발일 — 예시: `2026-01-10`
- `arrDate` (body, 선택): 도착일 — 예시: `2026-01-15`
- `adult` (body, 선택): 성인 인원 수 — 예시: `1`
- `child` (body, 선택): 소아 인원수 — 예시: `0`
- `infant` (body, 선택): 유아 인원수 — 예시: `0`
- `airline` (body, 선택): 항공사 코드 — 예시: `KE`
- `cabinClass` (body, 선택): 좌석등급 [가능한 값: "FIRST", "BUSINESS", "PREMIUM_ECONOMY", "ECONOMY", "NONE"] — 예시: `ECONOMY`

**응답 필드:**
- `data` (string): 항공 운임 조회 랜딩 URL

**응답 예시:**
```json
{ data: "https://flights.myrealtrip.com/air/agent/b2c/AIR/AAA/offers.k1?gid=3531412&depdt=2026-01-10&arrdt=2026-01-15&adult=2&child=3&infant=1", meta: {}, result: { status: 200, message: "SUCCESS", code: "success" }
```

> 이 API로 생성한 URL을 마이링크 생성 API(POST /v1/mylink)의 targetUrl로 전달하면 항공 단축 링크(myrealt.rip)를 만들 수 있습니다. 자세한 내용은 마이 링크 가이드의 '항공 마이링크 생성' 섹션을 참고하세요.

### GET /v1/revenues — 수익 현황 조회
태그: 수익 현황
특정 기간의 수익 현황을 조회합니다. 수익 데이터와 예약 정보를 매핑하여 반환합니다. 데이터는 매일 오전 6시에 일정산이 완료되며, 전일까지의 데이터를 조회할 수 있습니다. 환불/부분환불 건은 closingType으로 구분되며, commission이 마이너스 값으로 반환됩니다.

**파라미터:**
- `dateSearchType` (query, 필수): 필터 (SETTLEMENT: 정산기준일, PAYMENT: 예약일) [가능한 값: "SETTLEMENT", "PAYMENT"] — 예시: `SETTLEMENT`
- `startDate` (query, 필수): 검색 시작일 — 예시: `2025-01-01`
- `endDate` (query, 필수): 검색 종료일 — 예시: `2025-01-07`

**응답 필드:**
- `linkId` (string): 마케팅 링크 ID
- `reservationNo` (string): 예약 번호
- `quantity` (integer): 수량
- `salePrice` (integer (int64)): 판매 금액
- `commissionBase` (integer (int64)): 정산 대상 금액 (실결제금액, 쿠폰·포인트 차감 후). 2026-04-01 예약건부터 제공되며, 이전 예약건은 null입니다. null인 경우 salePrice를 사용하세요.
- `settlementCriteriaDate` (string (date)): 정산 기준일
- `commission` (integer (int64)): 수익 금액(VAT 포함)
- `commissionRate` (number): 커미션율(소수)
- `utmContent` (string): UTM 컨텐츠
- `closingType` (string): 주문 구분
- `reservedAt` (string (date-time)): 예약일
- `tripStartedAt` (string (date-time)): 여행 시작일
- `tripStartedAtKst` (string): 여행 시작일(KST)
- `tripEndedAt` (string (date-time)): 여행 종료일
- `tripEndedAtKst` (string): 여행 종료일(KST)
- `gid` (integer (int64)): 상품 ID
- `partnershipCommissionType` (string): 커미션 유형
- `productTitle` (string): 상품명
- `productCategory` (string): 상품 카테고리
- `status` (string): 예약 상태
- `statusKor` (string): 예약 상태(한글)
- `city` (string): 도시명
- `country` (string): 국가명

**응답 예시:**
```json
{ data: [ { linkId: "1000001", reservationNo: "TNA-20251101-00000001", quantity: 2, salePrice: 150000, commissionBase: 147000, settlementCriteriaDate: "2025-01-15", commission: 15000, commissionRate: 0.1, utmContent: "{utm_content로 넘긴 값}", closingType: "결제완료", reservedAt: "2025-01-15T14:30:00", tripStartedAt: "2025-02-01T09:00:00", tripStartedAtKst: "2025-02-01T18:00:00+09:00[Asia/Seoul]", tripEndedAt: "2025-02-03T18:00:00", tripEndedAtKst: "2025-02-04T03:00:00+09:00[Asia/Seoul]", gid: 3000009, partnershipCommissionType: "카테고리(숙소)", productTitle: "박물관 입장권", productCategory: "TICKET", status: "CONFIRM", statusKor: "예약확정", city: "Seoul", country: "Korea, Republic of" } ], meta: { totalCount: 1 }, result: { status: 200, message: "SUCCESS", code: "success" }
```

### GET /v1/revenues/flight — 항공 수익 현황 조회
태그: 수익 현황
항공 상품의 수익 현황을 조회합니다. 항공 상품 전용 API로, 예약 상세 정보 없이 수익 데이터만 반환합니다. 데이터는 매일 오전 6시에 일정산이 완료되며, 전일까지의 데이터를 조회할 수 있습니다. 환불 건은 closingType: 환불완료, commission이 마이너스 값으로 반환됩니다.

**파라미터:**
- `dateSearchType` (query, 필수): 필터 (SETTLEMENT: 정산기준일, PAYMENT: 예약일) [가능한 값: "SETTLEMENT", "PAYMENT"] — 예시: `SETTLEMENT`
- `startDate` (query, 필수): 검색 시작일 — 예시: `2025-01-01`
- `endDate` (query, 필수): 검색 종료일 — 예시: `2025-01-07`

**응답 필드:**
- `linkId` (string): 마케팅 링크 ID
- `reservationNo` (string): 예약 번호
- `quantity` (integer): 수량
- `salePrice` (integer (int64)): 판매 금액(항공료)
- `settlementCriteriaDate` (string (date)): 정산 기준일
- `commission` (integer (int64)): 수익 금액(VAT 포함)
- `commissionRate` (number): 커미션율(소수)
- `utmContent` (string): UTM 컨텐츠
- `closingType` (string): 주문 구분
- `reservedAt` (string (date-time)): 예약일
- `tripStartedAt` (string (date-time)): 여행 시작일
- `tripEndedAt` (string (date-time)): 여행 종료일
- `gid` (integer (int64)): 상품 ID
- `partnershipCommissionType` (string): 커미션 유형
- `productTitle` (string): 상품명
- `status` (string): 예약 상태
- `statusKor` (string): 예약 상태(한글)
- `city` (string): 도시명
- `country` (string): 국가명

**응답 예시:**
```json
{ data: [ { linkId: "1000002", reservationNo: "F1ABCD", quantity: 1, salePrice: 450000, settlementCriteriaDate: "2025-01-16", commission: 22500, commissionRate: 0.05, utmContent: "{utm_content로 넘긴 값}", closingType: "결제완료", reservedAt: "2025-01-16T10:20:00", tripStartedAt: "2025-03-01T08:00:00", tripEndedAt: "2025-03-05T20:00:00", gid: 4000001, partnershipCommissionType: "카테고리(항공)", productTitle: "ICN_BKK_RT_B2C", status: "CONFIRM", statusKor: "예약확정", city: "Tokyo", country: "Japan" } ], meta: { totalCount: 1 }, result: { status: 200, message: "SUCCESS", code: "success" }
```

### GET /v1/reservations — 예약 내역 조회
태그: 예약 내역
예약일 또는 여행 종료일로 예약 내역을 조회합니다. 페이징을 지원합니다. 예약 데이터는 실시간으로 업데이트되며, 최신 예약 정보를 즉시 조회할 수 있습니다. 최대 조회 기간은 6개월입니다.

**파라미터:**
- `dateSearchType` (query, 필수): 필터 (RESERVATION_DATE: 예약일, TRIP_END_DATE: 여행 종료일) [가능한 값: "RESERVATION_DATE", "TRIP_END_DATE"] — 예시: `RESERVATION_DATE`
- `startDate` (query, 필수): 검색 시작일 (yyyy-MM-dd) — 예시: `2025-01-01`
- `endDate` (query, 필수): 검색 종료일 (yyyy-MM-dd) — 예시: `2025-01-07`
- `statuses` (query, 선택): 예약 상태 필터 (복수 선택 가능, 미입력 시 전체 조회) [가능한 값: "TEMP", "WAIT_DEPOSIT", "PENDING_PAYMENT", "WAIT_CONFIRM", "CONFIRM", "REQUEST_CANCEL", "FINISH", "CANCEL", "FAIL"] — 예시: `CONFIRM`
- `page` (query, 선택): 페이지 번호 — 예시: `1`
- `pageSize` (query, 선택): 페이지 크기 (기본값 10, 최대값 300) — 예시: `20`

**응답 필드:**
- `reservedAt` (string (date-time)): 예약일
- `reservationNo` (string): 예약 ID
- `status` (string): 예약 상태
- `statusKor` (string): 예약 상태(한글)
- `salePrice` (integer (int64)): 판매 금액
- `commissionBase` (integer (int64)): 정산 대상 금액 (실결제금액, 쿠폰·포인트 차감 후). 2026-04-01 예약건부터 제공되며, 이전 예약건은 null입니다. null인 경우 salePrice를 사용하세요.
- `city` (string): 도시명
- `country` (string): 국가명
- `utmContent` (string): UTM 컨텐츠
- `linkId` (string): 마케팅 링크 ID
- `productTitle` (string): 상품명
- `productCategory` (string): 상품 카테고리
- `gid` (integer (int64)): 상품 ID
- `quantity` (integer): 수량
- `tripStartedAt` (string (date-time)): 여행 시작일
- `tripStartedAtKst` (string): 여행 시작일(KST)
- `tripEndedAt` (string (date-time)): 여행 종료일
- `tripEndedAtKst` (string): 여행 종료일(KST)
- `canceledAt` (string (date-time)): 취소 일시
- `finishedAt` (string (date-time)): 여행완료 일시

**응답 예시:**
```json
{ data: [ { reservedAt: "2025-01-15T14:30:00", reservationNo: "TNA-20251101-00000001", status: "CONFIRM", statusKor: "예약확정", salePrice: 150000, city: "Seoul", country: "Korea, Republic of", utmContent: "{utm_content로 넘긴 값}", linkId: "1000001", productTitle: "박물관 입장권", productCategory: "TICKET", gid: 3000009, quantity: 2, tripStartedAt: "2025-02-01T09:00:00", tripStartedAtKst: "2025-02-01T18:00:00+09:00[Asia/Seoul]", tripEndedAt: "2025-02-03T18:00:00", tripEndedAtKst: "2025-02-04T03:00:00+09:00[Asia/Seoul]", canceledAt: null, finishedAt: null }, { reservedAt: "2025-01-16T10:20:00", reservationNo: "ACM-20251102-00000002", status: "CONFIRM", statusKor: "예약확정", salePrice: 89000, city: "Busan", country: "Korea, Republic of", utmContent: "{utm_content로 넘긴 값}", linkId: "1000003", productTitle: "코모도 호텔 부산", productCategory: "HOTEL_V2", gid: 3000012, quantity: 1, tripStartedAt: "2025-02-10T14:00:00", tripStartedAtKst: "2025-02-10T23:00:00+09:00[Asia/Seoul]", tripEndedAt: "2025-02-10T17:00:00", tripEndedAtKst: "2025-02-11T02:00:00+09:00[Asia/Seoul]", canceledAt: null, finishedAt: null }, { reservedAt: "2025-01-16T10:20:00", reservationNo: "ACM-20251102-00000003", status: "CANCEL", statusKor: "예약취소", salePrice: 339000, city: "gapyeong", country: "Korea, Republic of", utmContent: "{utm_content로 넘긴 값}", linkId: "1000003", productTitle: "마이다스 호텔&리조트", productCategory: "HOTEL_V2", gid: 2805730, quantity: 1, tripStartedAt: "2025-02-10T14:00:00", tripStartedAtKst: "2025-02-10T23:00:00+09:00[Asia/Seoul]", tripEndedAt: "2025-02-10T17:00:00", tripEndedAtKst: "2025-02-11T02:00:00+09:00[Asia/Seoul]", canceledAt: "2026-02-08T00:22:11", finishedAt: null }, { reservedAt: "2026-03-11T03:32:14", reservationNo: "ACM-20260311-00001036", status: "FINISH", statusKor: "여행완료", salePrice: 340000, city: "Seoul", country: "Korea, Republic of", utmContent: null, linkId: "1511136", productTitle: "롯데호텔 월드", productCategory: "HOTEL_V2", gid: 2680937, quantity: 1, tripStartedAt: "2026-04-01T06:00:00", tripStartedAtKst: "2026-04-01T15:00:00+09:00[Asia/Seoul]", tripEndedAt: "2026-04-02T02:00:00", tripEndedAtKst: "2026-04-02T11:00:00+09:00[Asia/Seoul]", canceledAt: null, finishedAt: "2026-04-02T02:08:21" } ], meta: { pagination: { page: 1, pageSize: 10, totalCount: 4 }
```

### GET /v1/reservations/flight — 항공 예약 내역 조회
태그: 예약 내역
예약일로 항공 예약 내역을 조회합니다. 최대 조회 기간은 1개월입니다.

**파라미터:**
- `startDate` (query, 필수): 검색 시작일 (yyyy-MM-dd) — 예시: `2025-01-01`
- `endDate` (query, 필수): 검색 종료일 (yyyy-MM-dd) — 예시: `2025-01-07`
- `statuses` (query, 선택): 예약 상태 필터 (복수 선택 가능, 미입력 시 전체 조회) [가능한 값: "WAITING", "RESERVED", "IN_PAY", "CONFIRMED", "NOT_PAID_CONFIRMED", "CANCELLED"] — 예시: `CONFIRMED`

**응답 필드:**
- `reservationNo` (string): 예약 번호
- `flightReservationNo` (string): 항공사 예약번호 (PNR)
- `operationScope` (string): 국내/국제 구분
- `tripType` (string): 여행 타입
- `status` (string): 예약 상태
- `statusKor` (string): 예약 상태(한글)
- `airline` (string): 항공사 코드
- `airlineName` (string): 항공사 이름
- `reservedAt` (string (date-time)): 예약 일시
- `cancelledAt` (string (date-time)): 취소 일시
- `gid` (integer (int64)): GID
- `categoryCode` (string): 카테고리 코드
- `linkId` (string): 마케팅 링크 ID
- `issueNet` (integer (int64)): 항공료 금액

**응답 예시:**
```json
{ data: [ { reservationNo: "F1ABCD", flightReservationNo: "F1ABCD", operationScope: "INTERNATIONAL", tripType: "ROUND_TRIP", status: "CONFIRMED", statusKor: "발권완료(결제완료)", airline: "KE", airlineName: "대한항공", reservedAt: "2025-01-16T10:20:00", cancelledAt: null, gid: 3531412, categoryCode: "AIR_IND_INT", linkId: "1000002", issueNet: 450000 }, { reservationNo: "YEETUD", flightReservationNo: "YEETUD", operationScope: "INTERNATIONAL", tripType: "ROUND_TRIP", status: "CANCELLED", statusKor: "예약취소", airline: "7C", airlineName: "제주항공", reservedAt: "2026-02-06T14:40:39", cancelledAt: "2026-02-06T15:14:07", gid: 4761262, categoryCode: "AIR_JEJU_INT", linkId: "1426528", issueNet: 305490 } ], meta: { totalCount: 2 }, result: { status: 200, message: "SUCCESS", code: "success" }
```

### GET /health — 헬스 체크
태그: 헬스 체크
서버 상태를 확인합니다.

**응답 예시:**
```json
{ status: "UP" }
```

> 헬스 체크 API를 호출하기 전에 API 키 발급이 완료되었는지 확인하세요.

### POST /v1/products/flight/calendar — 캘린더 최저가 조회
태그: 항공권 조회
특정 출발지-도착지의 캘린더 최저가를 조회합니다. 지정한 기간(startDate~endDate) 내 날짜별 최저가 항공권 정보를 반환합니다.

**파라미터:**
- `depCityCd` (body, 필수): 출발 도시 코드 — 예시: `ICN`
- `arrCityCd` (body, 필수): 도착 도시 코드 — 예시: `BKK`
- `period` (body, 필수): 여행 기간(일) (3~7) — 예시: `5`
- `startDate` (body, 필수): 조회 시작일 (yyyy-MM-dd) — 예시: `2026-04-01`
- `endDate` (body, 필수): 조회 종료일 (yyyy-MM-dd, startDate보다 이후여야 함) — 예시: `2026-04-30`

**응답 필드:**
- `fromCity` (string): 출발 도시 코드
- `toCity` (string): 도착 도시 코드
- `period` (integer): 여행 기간(일)
- `departureDate` (string (date)): 출발일
- `returnDate` (string (date)): 귀국일
- `totalPrice` (integer (int64)): 최저가(원)
- `airline` (string): 항공사 코드
- `transfer` (integer): 경유 횟수 (0: 직항)
- `averagePrice` (integer (int64)): 평균가(원)

**응답 예시:**
```json
{ data: [ { fromCity: "ICN", toCity: "BKK", period: null, departureDate: "2026-03-25", returnDate: null, totalPrice: 809900, airline: "OZ", transfer: null, averagePrice: null }, { fromCity: "ICN", toCity: "BKK", period: null, departureDate: "2026-03-26", returnDate: null, totalPrice: 478300, airline: "7C", transfer: null, averagePrice: null }, { fromCity: "ICN", toCity: "BKK", period: null, departureDate: "2026-03-27", returnDate: null, totalPrice: 468300, airline: "7C", transfer: null, averagePrice: null } ], meta: { totalCount: 6 }, result: { status: 200, message: "SUCCESS", code: "success" }
```

### POST /v1/products/flight/calendar/window — 캘린더 윈도우 최저가 조회
태그: 항공권 조회
180일간 슬라이딩 윈도우 최저가를 조회합니다. 국제선만 지원합니다.

**파라미터:**
- `depCityCd` (body, 필수): 출발 도시 코드 — 예시: `ICN`
- `arrCityCd` (body, 필수): 도착 도시 코드 — 예시: `BKK`
- `period` (body, 필수): 여행 기간(일) (3~7) — 예시: `5`

**응답 필드:**
- `fromCity` (string): 출발 도시 코드
- `toCity` (string): 도착 도시 코드
- `period` (integer): 여행 기간(일)
- `departureDate` (string (date)): 출발일
- `returnDate` (string (date)): 귀국일
- `totalPrice` (integer (int64)): 최저가(원)
- `airline` (string): 항공사 코드
- `transfer` (integer): 경유 횟수 (0: 직항)
- `averagePrice` (integer (int64)): 평균가(원)

**응답 예시:**
```json
{ data: [ { fromCity: "ICN", toCity: "BKK", period: 5, departureDate: "2026-03-25", returnDate: "2026-03-29", totalPrice: 524630, airline: "TW", transfer: null, averagePrice: null }, { fromCity: "ICN", toCity: "BKK", period: 5, departureDate: "2026-03-26", returnDate: "2026-03-30", totalPrice: 588100, airline: "SL", transfer: null, averagePrice: null }, { fromCity: "ICN", toCity: "BKK", period: 5, departureDate: "2026-03-27", returnDate: "2026-03-31", totalPrice: 2275700, airline: "TG", transfer: null, averagePrice: null } ], meta: { totalCount: 180 }, result: { status: 200, message: "SUCCESS", code: "success" }
```

### POST /v1/products/flight/calendar/lowest — 다중 목적지 최저가 조회
태그: 항공권 조회
다중 목적지(최대 50개)의 최저가를 조회합니다. 국제선만 지원합니다.

**파라미터:**
- `depCityCd` (body, 필수): 출발 도시 코드 — 예시: `ICN`
- `arrCityCds` (body, 필수): 도착 도시 코드 목록 (최대 50개) — 예시: `[\`
- `period` (body, 필수): 여행 기간(일) (3~7) — 예시: `5`

**응답 필드:**
- `fromCity` (string): 출발 도시 코드
- `toCity` (string): 도착 도시 코드
- `period` (integer): 여행 기간(일)
- `departureDate` (string (date)): 출발일
- `returnDate` (string (date)): 귀국일
- `totalPrice` (integer (int64)): 최저가(원)
- `airline` (string): 항공사 코드
- `transfer` (integer): 경유 횟수 (0: 직항)
- `averagePrice` (integer (int64)): 평균가(원)

**응답 예시:**
```json
{ data: [ { fromCity: "ICN", toCity: "NRT", period: 5, departureDate: "2026-08-28", returnDate: "2026-09-01", totalPrice: 266500, airline: "LJ", transfer: null, averagePrice: null }, { fromCity: "ICN", toCity: "BKK", period: 5, departureDate: "2026-09-06", returnDate: "2026-09-10", totalPrice: 326300, airline: "7C", transfer: null, averagePrice: null }, { fromCity: "ICN", toCity: "TYO", period: 5, departureDate: "2026-08-20", returnDate: "2026-08-24", totalPrice: 266500, airline: "LJ", transfer: null, averagePrice: null } ], meta: { totalCount: 3 }, result: { status: 200, message: "SUCCESS", code: "success" }
```

### POST /v1/products/flight/calendar/bulk-lowest — 전체 목적지 최저가 조회
태그: 항공권 조회
전체 목적지의 최저가를 대량 조회합니다. 국제선만 지원합니다.

**파라미터:**
- `depCityCd` (body, 필수): 출발 도시 코드 — 예시: `ICN`
- `period` (body, 필수): 여행 기간(일) (3~7) — 예시: `5`

**응답 필드:**
- `fromCity` (string): 출발 도시 코드
- `toCity` (string): 도착 도시 코드
- `period` (integer): 여행 기간(일)
- `departureDate` (string (date)): 출발일
- `returnDate` (string (date)): 귀국일
- `totalPrice` (integer (int64)): 최저가(원)
- `airline` (string): 항공사 코드
- `transfer` (integer): 경유 횟수 (0: 직항)
- `averagePrice` (integer (int64)): 평균가(원)

**응답 예시:**
```json
{ data: [ { fromCity: "ICN", toCity: "ADD", period: 5, departureDate: "2026-05-02", returnDate: "2026-05-06", totalPrice: 1573500, airline: null, transfer: null, averagePrice: 1846253 }, { fromCity: "ICN", toCity: "AKL", period: 5, departureDate: "2026-05-24", returnDate: "2026-05-28", totalPrice: 1137000, airline: null, transfer: null, averagePrice: 1501637 }, { fromCity: "ICN", toCity: "BKK", period: 5, departureDate: "2026-09-06", returnDate: "2026-09-10", totalPrice: 326300, airline: null, transfer: null, averagePrice: 549671 } ], meta: { totalCount: 694 }, result: { status: 200, message: "SUCCESS", code: "success" }
```

### POST /v1/products/accommodation/search — 숙소 검색
태그: 숙소 조회
키워드, 체크인/체크아웃 날짜, 인원 등의 조건으로 숙소를 검색합니다. 성급, 가격 범위, 정렬 등 다양한 필터를 지원하며, 페이지네이션으로 결과를 조회할 수 있습니다.

**파라미터:**
- `keyword` (body, 필수): 검색 키워드 (도시명) — 예시: `서울`
- `regionId` (body, 선택): 마이리얼트립 지역 ID — 예시: `6139291`
- `checkIn` (body, 필수): 체크인 날짜 (yyyy-MM-dd) — 예시: `2026-04-15`
- `checkOut` (body, 필수): 체크아웃 날짜 (yyyy-MM-dd, 체크인 이후여야 함) — 예시: `2026-04-17`
- `adultCount` (body, 필수): 성인 수 (최소 1) — 예시: `2`
- `childCount` (body, 선택): 아동 수 — 예시: `0`
- `isDomestic` (body, 선택): 국내 숙소 여부 (true: 국내, false: 해외) — 예시: `true`
- `starRating` (body, 선택): 성급 필터 (threestar: 3성 이상, fourstar: 4성 이상, fivestar: 5성) [가능한 값: "threestar", "fourstar", "fivestar"] — 예시: `fourstar`
- `stayPoi` (body, 선택): 지역 POI ID — 예시: `14048`
- `order` (body, 선택): 정렬 기준 (price_asc: 가격 낮은순, price_desc: 가격 높은순, review_desc: 리뷰 높은순) [가능한 값: "price_asc", "price_desc", "review_desc"] — 예시: `price_asc`
- `minPrice` (body, 선택): 최소 가격 (원) — 예시: `50000`
- `maxPrice` (body, 선택): 최대 가격 (원) — 예시: `300000`
- `page` (body, 선택): 페이지 번호 (0부터 시작) — 예시: `0`
- `size` (body, 선택): 페이지 크기 (1~50, 기본값 20) — 예시: `20`

**응답 필드:**
- `items` (array): 숙소 목록
- `items[].itemId` (integer (int64)): 숙소 ID
- `items[].itemName` (string): 숙소명
- `items[].salePrice` (integer (int64)): 판매가 (원)
- `items[].originalPrice` (integer (int64)): 정가 (원)
- `items[].starRating` (integer): 성급 (1~5)
- `items[].reviewScore` (string): 리뷰 평점
- `items[].reviewCount` (integer): 리뷰 수
- `items[].imageUrl` (string): 썸네일 이미지 URL (CDN 경로). upstream 미제공 또는 빈 값일 경우 null
- `totalCount` (integer): 전체 결과 수
- `page` (integer): 현재 페이지
- `size` (integer): 페이지 크기

**응답 예시:**
```json
{ data: { items: [ { itemId: 1484076, itemName: "롯데호텔 월드", salePrice: 346690, originalPrice: 398000, starRating: 5, reviewScore: "4.7", reviewCount: 1783, imageUrl: "https://dry7pvlp22cox.cloudfront.net/mrt-images-prod/2025/11/13/sZgZ/95VgflZiXb.png?width=720" }, { itemId: 2447253, itemName: "앰배서더 서울 풀만 호텔", salePrice: 405900, originalPrice: 458000, starRating: 5, reviewScore: "4.5", reviewCount: 657, imageUrl: "https://dry7pvlp22cox.cloudfront.net/mrt-images-prod/2023/12/20/uFkY/753g00BOEY.jpg?width=720" }, { itemId: 1259122, itemName: "신라스테이 삼성", salePrice: 289080, originalPrice: 320000, starRating: 3, reviewScore: "4.1", reviewCount: 1033, imageUrl: "https://dry7pvlp22cox.cloudfront.net/mrt-images-prod/2025/10/10/j6Yk/mbkXfCFK1p.jpg?width=720" } ], totalCount: 20, page: 0, size: 20 }, meta: { totalCount: 20 }, result: { status: 200, message: "SUCCESS", code: "success" }
```

### POST /v1/products/tna/categories — 투어티켓 카테고리 목록
태그: 투어티켓 조회
도시별 투어/티켓 카테고리 목록을 조회합니다. 반환된 value 값을 상품 검색 API의 category 파라미터로 사용할 수 있습니다. 카테고리는 도시마다 다릅니다.

**파라미터:**
- `city` (body, 필수): 도시명 (한글 입력, 예: 오사카, 도쿄, 방콕, 파리, 제주) — 예시: `오사카`

**응답 필드:**
- `categories` (array): 카테고리 목록
- `categories[].name` (string): 카테고리 표시명
- `categories[].value` (string): 카테고리 값 (검색 시 사용)
- `totalCount` (integer): 해당 도시의 전체 상품 수

**응답 예시:**
```json
{ data: { categories: [ { name: "전체", value: "all" }, { name: "근교투어", value: "suburb_tour" }, { name: "티켓·입장권", value: "ticket_v2" }, { name: "이동·교통", value: "transportation_v2" }, { name: "미식", value: "delicacies" }, { name: "투어", value: "tour" }, { name: "액티비티", value: "activity" }, { name: "스냅촬영", value: "snap_v2" }, { name: "체험·클래스", value: "activity_class" }, { name: "스파·마사지", value: "spamassage" } ], totalCount: 1016 }, meta: {}, result: { status: 200, message: "SUCCESS", code: "success" }
```

### POST /v1/products/tna/search — 투어티켓 상품 검색
태그: 투어티켓 조회
투어, 티켓, 액티비티 상품을 검색합니다. 키워드, 도시, 카테고리, 가격 범위 등으로 필터링할 수 있으며, 다양한 정렬 옵션을 지원합니다.

**파라미터:**
- `keyword` (body, 필수): 검색 키워드 (상품명, 도시명 등) — 예시: `오사카 투어`
- `city` (body, 선택): 도시명 (한글 입력, 예: 오사카, 도쿄, 방콕, 파리, 제주) — 예시: `오사카`
- `category` (body, 선택): 상품 카테고리 (미전송 또는 \ — 예시: `ticket_v2`
- `minPrice` (body, 선택): 최소 가격 (원) — 예시: `10000`
- `maxPrice` (body, 선택): 최대 가격 (원) — 예시: `200000`
- `sort` (body, 선택): 정렬 기준 (price_asc: 가격 낮은순, price_desc: 가격 높은순, review_score_desc: 리뷰 높은순, selling_count_desc: 판매량순) [가능한 값: "price_asc", "price_desc", "review_score_desc", "selling_count_desc"] — 예시: `price_asc`
- `page` (body, 선택): 페이지 번호 (1부터, 기본값 1) — 예시: `1`
- `perPage` (body, 선택): 페이지 크기 (기본값 20, 최대 100) — 예시: `20`

**응답 필드:**
- `items` (array): 검색 결과 상품 목록
- `items[].gid` (string): 상품 ID (수익/예약 API의 gid와 동일)
- `items[].itemName` (string): 상품명 (상세 API에서는 title 필드로 반환)
- `items[].description` (string): 상품 설명
- `items[].salePrice` (integer (int64)): 시작가 (원)
- `items[].priceDisplay` (string): 시작가 표시용 (예: 92,600원)
- `items[].category` (string): 상품 카테고리
- `items[].reviewScore` (number): 리뷰 평점 (1.0~5.0)
- `items[].reviewCount` (integer): 리뷰 수
- `items[].imageUrl` (string): 상품 이미지 URL
- `items[].productUrl` (string): 상품 페이지 URL (마이링크 생성 시 targetUrl로 사용)
- `items[].deepLink` (string): 딥링크 (mrt://experiences/detail/{gid})
- `items[].tags` (array): 태그 (즉시 확정 등)
- `totalCount` (integer): 전체 검색 결과 수
- `page` (integer): 현재 페이지
- `perPage` (integer): 페이지 크기
- `hasNextPage` (boolean): 다음 페이지 존재 여부

**응답 예시:**
```json
{ data: { items: [ { gid: "5869248", itemName: "오사카 난카이 라피트 편도 E-티켓 (간사이 공항 ↔ 난카이 난바역)", description: "오사카 ∙ 이동·교통", salePrice: 12657, priceDisplay: "12,657원", category: "이동·교통", reviewScore: 4.83, reviewCount: 1250, imageUrl: "https://d6bztw1vgnv55.cloudfront.net/experiences/products/5869248/thumbnail.jpg", productUrl: "https://experiences.myrealtrip.com/products/5869248", deepLink: "mrt://experiences/detail/5869248", tags: ["즉시 확정"] }, { gid: "3425896", itemName: "[여행 한 그릇] 사진 촬영 포함, 아라시야마, 금각사, 여우신사, 청수사 교토 투어", description: "오사카 ∙ 투어", salePrice: 89000, priceDisplay: "89,000원", category: "투어", reviewScore: 4.95, reviewCount: 320, imageUrl: "https://d6bztw1vgnv55.cloudfront.net/experiences/products/3425896/thumbnail.jpg", productUrl: "https://experiences.myrealtrip.com/products/3425896", deepLink: "mrt://experiences/detail/3425896", tags: [] } ], totalCount: 1019, page: 1, perPage: 20, hasNextPage: true }, meta: { totalCount: 75 }, result: { status: 200, message: "SUCCESS", code: "success" }
```

### POST /v1/products/tna/detail — 투어티켓 상품 상세
태그: 투어티켓 조회
상품 상세 정보를 조회합니다. 포함/불포함 사항, 일정, 리뷰 정보를 반환합니다. 검색 결과의 gid를 사용하세요. 일부 연동 상품은 상세 정보가 제공되지 않을 수 있습니다.

**파라미터:**
- `gid` (body, 필수): 상품 ID (검색 결과의 gid) — 예시: `5869248`

**응답 필드:**
- `gid` (string): 상품 ID
- `title` (string): 상품명
- `description` (string): 상품 소개 (HTML 포함 가능)
- `reviewScore` (number): 리뷰 평점 (1.0~5.0)
- `reviewCount` (integer): 리뷰 수
- `included` (array): 포함 사항 목록
- `excluded` (array): 불포함 사항 목록
- `itineraries` (array): 일정 정보
- `itineraries[].title` (string): 일정 제목
- `itineraries[].description` (string): 일정 설명

**응답 예시:**
```json
{ data: { gid: "5869248", title: "오사카 난카이 라피트 편도 E-티켓 (간사이 공항 ↔ 난카이 난바역)", description: "오사카 난카이 라피트 편도 E-티켓으로 간사이 공항에서 난바역까지 빠르고 편리하게 이동하세요.", reviewScore: 4.83, reviewCount: 1250, included: ["난카이 라피트 편도 E-티켓"], excluded: ["개인 경비"], itineraries: [] }, meta: {}, result: { status: 200, message: "SUCCESS", code: "success" }
```

### POST /v1/products/tna/options — 투어티켓 옵션 조회
태그: 투어티켓 조회
특정 날짜의 예약 가능 옵션과 가격을 조회합니다. 검색 결과의 gid와 원하는 날짜를 입력하세요.

**파라미터:**
- `gid` (body, 필수): 상품 ID (검색 결과의 gid) — 예시: `5869248`
- `selectedDate` (body, 필수): 선택 날짜 (YYYY-MM-DD) — 예시: `2026-05-01`

**응답 필드:**
- `selectedDate` (string): 선택된 날짜
- `options` (array): 옵션 목록 (빈 배열이면 해당 날짜에 예약 가능한 옵션 없음)
- `options[].id` (integer (int64)): 옵션 ID
- `options[].name` (string): 옵션명
- `options[].salePrice` (integer (int64)): 판매가 (원)
- `options[].currency` (string): 통화 (KRW)
- `options[].minPurchaseQuantity` (integer): 최소 구매 수량
- `options[].availablePurchaseQuantity` (integer): 구매 가능 수량
- `defaultOption` (object): 기본 옵션
- `units` (array): 옵션 유닛 목록
- `units[].id` (integer (int64)): 유닛 ID
- `units[].name` (string): 유닛명

**응답 예시:**
```json
{ data: { selectedDate: "2026-05-01", options: [ { id: 8901234, name: "난카이 라피트 편도 E-티켓 (간사이공항→난바)", salePrice: 12657, currency: "KRW", minPurchaseQuantity: 1, availablePurchaseQuantity: null }, { id: 8901235, name: "난카이 라피트 편도 E-티켓 (난바→간사이공항)", salePrice: 12657, currency: "KRW", minPurchaseQuantity: 1, availablePurchaseQuantity: null } ], defaultOption: null, units: [ { id: 13762, name: "옵션" } ] }, meta: {}, result: { status: 200, message: "SUCCESS", code: "success" }
```

### POST /v1/products/tna/calendars — 투어티켓 캘린더 조회
태그: 투어티켓 조회
월별 예약 가능 여부와 시작가를 조회합니다. 선택 날짜가 포함된 월의 캘린더 정보를 반환합니다.

**파라미터:**
- `gid` (body, 필수): 상품 ID (검색 결과의 gid) — 예시: `5869248`
- `selectedDate` (body, 필수): 선택 날짜 (YYYY-MM-DD). 해당 날짜가 포함된 월의 캘린더를 반환합니다 (예: 2026-05-01 → 5월 캘린더) — 예시: `2026-05-01`

**응답 필드:**
- `date` (string): 조회 월 (YYYY-MM)
- `basePrice` (string): 시작가 표시용 문자열 (예: 9.3만, 4.9만). 정확한 가격은 옵션 API의 salePrice(숫자)를 사용하세요
- `blockDates` (array): 예약 불가 날짜 목록 (YYYY-MM-DD). 빈 배열이면 해당 월 전체 예약 가능
- `excludedOptionDates` (array): 특정 옵션 제외 날짜
- `instantConfirm` (boolean): 즉시 확정 여부. false이면 판매자 확인 후 예약 확정

**응답 예시:**
```json
{ data: { date: "2026-05", basePrice: "9.3만", blockDates: [], excludedOptionDates: [], instantConfirm: false }, meta: {}, result: { status: 200, message: "SUCCESS", code: "success" }
```