FareRuleController DFS (Detailed Functional Specification)
문서 정보
- 서비스명: air-intl-search (국제 항공 검색 서비스)
- 컨트롤러: FareRuleController
- OpenAPI 출처:
openapi.yamlpaths/fare-rules/** - 작성일: 2026-03-04
목차
개요
FareRuleController는 항공편 운임 규정을 비동기 폴링 방식으로 조회하는 REST API 컨트롤러입니다.
플로우: 키 발급 (202) → 폴링 조회 (202 진행중 / 200 완료)
기존 동기 API 대체
FlightDetailController의
GET /flights/detail/{detailKey}/fare-rules(deprecated)를 대체합니다.
API 엔드포인트 목록
| # | HTTP Method | URL Pattern | operationId | 설명 |
|---|---|---|---|---|
| 1 | GET | /fare-rules | getFareRuleKey | 운임 규정 조회 키 발급 |
| 2 | GET | /fare-rules/{fareRuleKey} | getFareRule | 운임 규정 폴링 조회 |
상세 스펙
1. 운임 규정 조회 키 발급
GET /fare-rules?flightDetailKey={key}&adult={n}
Parameters
| 위치 | 이름 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| query | flightDetailKey | string | O | 항공편 상세 키 |
| query | adult | int32 | O | 성인 인원 수 (≥1) |
| query | child | int32 | X | 소아 인원 수 (기본: 0) |
| query | infant | int32 | X | 유아 인원 수 (기본: 0) |
Responses
Response Examples
시나리오: ICN→NRT 왕복, 성인 2 / 소아 1, 이코노미
GET /fare-rules?flightDetailKey=KE-ICN-NRT-20260415-Y-1&adult=2&child=1
성공 응답 (202)
{
"key": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}에러 응답 (400)
{
"status": 400,
"code": "INVALID_PARAMETER",
"title": "잘못된 요청",
"message": "성인 인원은 1명 이상이어야 합니다.",
"messageArguments": []
}2. 운임 규정 폴링 조회
GET /fare-rules/{fareRuleKey}
Parameters
| 위치 | 이름 | 타입 | 필수 | 설명 |
|---|---|---|---|---|
| path | fareRuleKey | uuid | O | 운임 규정 키 |
Responses
| 상태 코드 | 설명 | 응답 스키마 |
|---|---|---|
| 200 | 조회 완료 | |
| 202 | 조회 진행 중 (폴링 필요) | |
| 400 | 잘못된 요청 | ErrorView |
| 404 | 리소스 없음 | ErrorView |
| 410 | 만료된 리소스 | ErrorView |
| 500 | 서버 내부 오류 | ErrorView |
| 550 | 검색 실패 (커스텀) | ErrorView |
Response Examples
시나리오: 위 키 발급 후 폴링 조회
GET /fare-rules/a1b2c3d4-e5f6-7890-abcd-ef1234567890
진행 중 응답 (202 PENDING)
{
"status": "PENDING",
"fareRules": null
}완료 응답 (200 COMPLETE)
{
"status": "COMPLETE",
"fareRules": [
{
"groupTitle": "환불/변경 규정",
"rules": [
{
"type": "REFUND_AND_CHANGE",
"title": "취소 수수료",
"content": "출발일 기준 91일 전: 무료\n출발일 기준 90~61일 전: 50,000원\n출발일 기준 60~31일 전: 80,000원\n출발일 기준 30일 이내: 100,000원\n출발 후 환불 불가",
"order": 1
},
{
"type": "REFUND_AND_CHANGE",
"title": "변경 수수료",
"content": "출발일 기준 91일 전: 무료\n출발일 기준 90~61일 전: 30,000원\n출발일 기준 60일 이내: 50,000원\n변경은 1회에 한하며 동일 항공사 내에서만 가능",
"order": 2
}
]
},
{
"groupTitle": "수하물 규정",
"rules": [
{
"type": "BAGGAGE",
"title": "위탁 수하물",
"content": "성인/소아: 23kg × 1개 무료\n유아: 10kg × 1개 무료\n추가 수하물: 1개당 60,000원",
"order": 1
},
{
"type": "BAGGAGE",
"title": "기내 수하물",
"content": "1개 (12kg 이내, 55×40×20cm)\n소형 개인 물품 1개 추가 가능",
"order": 2
}
]
},
{
"groupTitle": "마일리지 적립",
"rules": [
{
"type": "MILEAGE",
"title": "적립률",
"content": "대한항공 스카이패스 적립률: Y클래스 100%\n스카이팀 제휴사 적립 가능",
"order": 1
}
]
},
{
"groupTitle": "기타 안내",
"rules": [
{
"type": "COMMON",
"title": "유효 기간",
"content": "발권일로부터 1년간 유효\n여정 변경 시 유효기간 내에서만 가능",
"order": 1
}
]
}
]
}데이터 없음 응답 (200 NO_DATA)
{
"status": "NO_DATA",
"fareRules": null
}에러 응답 (550)
{
"status": 550,
"code": "SEARCH_FAILED",
"title": "검색 실패",
"message": "운임 규정 조회에 실패했습니다. 잠시 후 다시 시도해주세요.",
"messageArguments": []
}데이터 모델
FareRuleInfoView
| 필드 | 타입 | 필수 | 설명 |
|---|---|---|---|
status | O | 폴링 상태 | |
fareRules | Array<FareRuleView> | X | 운임 규정 목록 (조회 완료 시) |
PollingStatus
| 값 | 설명 |
|---|---|
PENDING | 진행 중 |
ERROR | 오류 |
COMPLETE | 완료 |
NO_DATA | 데이터 없음 |
비동기 폴링 플로우
Client Server
│ │
├─ GET /fare-rules?... ───────►│ 키 발급 요청
│◄── 202 { key: uuid } ───────┤
│ │
├─ GET /fare-rules/{key} ──────►│ 폴링 (1차)
│◄── 202 { status: PENDING } ──┤
│ │
├─ GET /fare-rules/{key} ──────►│ 폴링 (2차)
│◄── 200 { status: COMPLETE, ──┤ 완료
│ fareRules: [...] } │
│ │
폴링 전략
클라이언트는
202응답을 받으면 일정 간격(예: 1초)으로 재요청합니다.200또는 에러 응답을 받으면 폴링을 중단합니다.