FlightDetailController DFS (Detailed Functional Specification)

문서 정보

서비스명: air-intl-search (국제 항공 검색 서비스)
컨트롤러: FlightDetailController
OpenAPI 출처: openapi.yaml paths /flights/detail/**
작성일: 2026-03-04

개요

FlightDetailController는 항공편 상세 정보를 조회하는 REST API 컨트롤러입니다. 검색 결과의 detailKey 또는 listKey + id 조합으로 개별 항공편의 상세 운임, 스케줄, 좌석 정보를 제공합니다.

API 엔드포인트 목록

#	HTTP Method	URL Pattern	operationId	설명
1	GET	`/flights/detail/{detailKey}`	`getFlightDetail`	항공편 상세 조회 (detailKey)
2	GET	`/flights/detail`	`getFlightDetailById`	항공편 상세 조회 (listKey + id)
3	GET	`/flights/detail/{detailKey}/fare-rules`	`getFareRules`	운임 규정 조회 (deprecated)
4	GET	`/flights/detail/{detailKey}/benefit/free-installment`	`findFreeInstallment`	무이자 할부 카드 혜택 조회

상세 스펙

1. 항공편 상세 조회 (detailKey)

GET /flights/detail/{detailKey}

Parameters

위치	이름	타입	필수	설명
path	`detailKey`	string	O	항공편 상세 키
query	`adult`	int32	O	성인 인원 수 (≥1)
query	`child`	int32	X	소아 인원 수 (기본: 0)
query	`infant`	int32	X	유아 인원 수 (기본: 0)
query	`promotionPrincipleId`	int64	X	프로모션 정책 ID (nullable)

Responses

상태 코드	설명	응답 스키마
200	항공편 상세 정보
400	잘못된 요청
404	리소스 없음
410	만료된 리소스
500	서버 내부 오류

Response Examples

시나리오: ICN→NRT 왕복, 성인 2 / 소아 1, 이코노미

GET /flights/detail/KE-ICN-NRT-20260415-Y-1?adult=2&child=1&promotionPrincipleId=1001

산술 검증 (Critique D)

total = airPrice + fuelCharge + otherTax + ticketingFee - discount

totalPrice = Σ(fare.total × count) = 443,900×2 + 368,900×1 = 1,256,700

totalDiscount = Σ(fare.discount × count) = 10,000×2 + 7,500×1 = 27,500

originalAdultPrice = adultPrice + discount = 443,900 + 10,000 = 453,900

성공 응답 (200)

{
  "detailKey": "KE-ICN-NRT-20260415-Y-1",
  "id": "KE-ICN-NRT-20260415-Y-1",
  "passengerFares": [
    {
      "type": "ADULT",
      "count": 2,
      "airPrice": 340000,
      "fuelCharge": 85600,
      "otherTax": 28300,
      "ticketingFee": 0,
      "discount": 10000,
      "total": 443900
    },
    {
      "type": "CHILD",
      "count": 1,
      "airPrice": 262500,
      "fuelCharge": 85600,
      "otherTax": 28300,
      "ticketingFee": 0,
      "discount": 7500,
      "total": 368900
    }
  ],
  "validatingCarrier": {
    "code": "KE",
    "name": "대한항공",
    "logoUrl": null
  },
  "fares": [
    {
      "passengerFares": [
        {
          "type": "ADULT",
          "count": 2,
          "airPrice": 350000,
          "fuelCharge": 85600,
          "otherTax": 28300,
          "ticketingFee": 0,
          "discount": 0,
          "total": 463900
        },
        {
          "type": "CHILD",
          "count": 1,
          "airPrice": 262500,
          "fuelCharge": 85600,
          "otherTax": 28300,
          "ticketingFee": 0,
          "discount": 0,
          "total": 376400
        }
      ],
      "adultPrice": 463900,
      "cardPromotionName": null,
      "promotionPrincipleId": null,
      "tags": []
    },
    {
      "passengerFares": [
        {
          "type": "ADULT",
          "count": 2,
          "airPrice": 340000,
          "fuelCharge": 85600,
          "otherTax": 28300,
          "ticketingFee": 0,
          "discount": 10000,
          "total": 443900
        },
        {
          "type": "CHILD",
          "count": 1,
          "airPrice": 262500,
          "fuelCharge": 85600,
          "otherTax": 28300,
          "ticketingFee": 0,
          "discount": 7500,
          "total": 368900
        }
      ],
      "adultPrice": 443900,
      "cardPromotionName": "신한카드 할인",
      "promotionPrincipleId": 1001,
      "tags": ["CARD_PROMOTION"]
    }
  ],
  "schedules": [
    {
      "title": "가는편",
      "totalFlightTime": "PT2H30M",
      "departure": {
        "code": "ICN",
        "name": "인천국제공항",
        "dateTime": "2026-04-15T10:00:00",
        "cityName": "서울",
        "terminal": "T2"
      },
      "arrival": {
        "code": "NRT",
        "name": "나리타국제공항",
        "dateTime": "2026-04-15T12:30:00",
        "cityName": "도쿄",
        "terminal": "T1"
      },
      "segments": [
        {
          "departure": {
            "code": "ICN",
            "name": "인천국제공항",
            "dateTime": "2026-04-15T10:00:00",
            "cityName": "서울",
            "terminal": "T2"
          },
          "arrival": {
            "code": "NRT",
            "name": "나리타국제공항",
            "dateTime": "2026-04-15T12:30:00",
            "cityName": "도쿄",
            "terminal": "T1"
          },
          "marketingCarrier": { "code": "KE", "name": "대한항공", "logoUrl": null },
          "operatingCarrier": null,
          "flightNumber": "KE705",
          "cabin": "ECONOMY",
          "bookingClass": "Y",
          "freeBaggage": { "unit": "개", "allowance": 1 },
          "legs": [
            {
              "departure": {
                "code": "ICN",
                "name": "인천국제공항",
                "dateTime": "2026-04-15T10:00:00",
                "cityName": "서울",
                "terminal": "T2"
              },
              "arrival": {
                "code": "NRT",
                "name": "나리타국제공항",
                "dateTime": "2026-04-15T12:30:00",
                "cityName": "도쿄",
                "terminal": "T1"
              },
              "flightTime": "PT2H30M",
              "connectingTime": null,
              "transferAirport": null
            }
          ],
          "amenity": null
        }
      ],
      "stop": 0,
      "mainCarrier": { "code": "KE", "name": "대한항공", "logoUrl": null },
      "carrierText": "대한항공"
    },
    {
      "title": "오는편",
      "totalFlightTime": "PT2H40M",
      "departure": {
        "code": "NRT",
        "name": "나리타국제공항",
        "dateTime": "2026-04-22T14:00:00",
        "cityName": "도쿄",
        "terminal": "T1"
      },
      "arrival": {
        "code": "ICN",
        "name": "인천국제공항",
        "dateTime": "2026-04-22T16:40:00",
        "cityName": "서울",
        "terminal": "T2"
      },
      "segments": [
        {
          "departure": {
            "code": "NRT",
            "name": "나리타국제공항",
            "dateTime": "2026-04-22T14:00:00",
            "cityName": "도쿄",
            "terminal": "T1"
          },
          "arrival": {
            "code": "ICN",
            "name": "인천국제공항",
            "dateTime": "2026-04-22T16:40:00",
            "cityName": "서울",
            "terminal": "T2"
          },
          "marketingCarrier": { "code": "KE", "name": "대한항공", "logoUrl": null },
          "operatingCarrier": null,
          "flightNumber": "KE706",
          "cabin": "ECONOMY",
          "bookingClass": "Y",
          "freeBaggage": { "unit": "개", "allowance": 1 },
          "legs": [
            {
              "departure": {
                "code": "NRT",
                "name": "나리타국제공항",
                "dateTime": "2026-04-22T14:00:00",
                "cityName": "도쿄",
                "terminal": "T1"
              },
              "arrival": {
                "code": "ICN",
                "name": "인천국제공항",
                "dateTime": "2026-04-22T16:40:00",
                "cityName": "서울",
                "terminal": "T2"
              },
              "flightTime": "PT2H40M",
              "connectingTime": null,
              "transferAirport": null
            }
          ],
          "amenity": null
        }
      ],
      "stop": 0,
      "mainCarrier": { "code": "KE", "name": "대한항공", "logoUrl": null },
      "carrierText": "대한항공"
    }
  ],
  "avail": 9,
  "passengerChangeable": true,
  "cardPromotionName": "신한카드 할인",
  "promotionPrincipleId": 1001,
  "tags": ["CARD_PROMOTION"],
  "tripType": "ROUND_TRIP",
  "totalPrice": 1256700,
  "totalDiscount": 27500,
  "adultPrice": 443900,
  "originalAdultPrice": 453900
}

에러 응답 (404)

{
  "status": 404,
  "code": "NOT_FOUND",
  "title": "리소스 없음",
  "message": "항공편 상세 정보를 찾을 수 없습니다.",
  "messageArguments": []
}

에러 응답 (410)

{
  "status": 410,
  "code": "GONE",
  "title": "만료된 리소스",
  "message": "검색 결과가 만료되었습니다. 다시 검색해주세요.",
  "messageArguments": []
}

2. 항공편 상세 조회 (listKey + id)

GET /flights/detail

Parameters

위치	이름	타입	필수	설명
query	`listKey`	uuid	O	검색 리스트 키
query	`id`	string	O	항공편 ID
query	`adult`	int32	O	성인 인원 수 (≥1)
query	`child`	int32	X	소아 인원 수 (기본: 0)
query	`infant`	int32	X	유아 인원 수 (기본: 0)

Responses

상태 코드	설명	응답 스키마
200	항공편 상세 정보
400	잘못된 요청
404	리소스 없음
410	만료된 리소스
500	서버 내부 오류

3. 운임 규정 조회 (deprecated)

Deprecated

이 API는 더 이상 사용되지 않습니다. FareRuleController의 비동기 폴링 방식을 사용하세요.

GET /flights/detail/{detailKey}/fare-rules

Parameters

위치	이름	타입	필수	설명
path	`detailKey`	string	O	항공편 상세 키
query	`adult`	int32	O	성인 인원 수 (≥1)
query	`child`	int32	X	소아 인원 수 (기본: 0)
query	`infant`	int32	X	유아 인원 수 (기본: 0)

Responses

상태 코드	설명	응답 스키마
200	운임 규정 목록	`Array<>`
400	잘못된 요청
500	서버 내부 오류

Response Examples

Deprecated — FareRuleController의 비동기 폴링 방식을 사용하세요.

GET /flights/detail/KE-ICN-NRT-20260415-Y-1/fare-rules?adult=2&child=1

성공 응답 (200)

[
  {
    "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원",
        "order": 2
      }
    ]
  },
  {
    "groupTitle": "수하물 규정",
    "rules": [
      {
        "type": "BAGGAGE",
        "title": "위탁 수하물",
        "content": "성인/소아: 23kg × 1개 무료\n유아: 10kg × 1개 무료",
        "order": 1
      }
    ]
  },
  {
    "groupTitle": "마일리지 적립",
    "rules": [
      {
        "type": "MILEAGE",
        "title": "적립률",
        "content": "대한항공 스카이패스 적립률: Y클래스 100%",
        "order": 1
      }
    ]
  }
]

4. 무이자 할부 카드 혜택 조회

GET /flights/detail/{detailKey}/benefit/free-installment

Parameters

위치	이름	타입	필수	설명
path	`detailKey`	string	O	항공편 상세 키

Responses

상태 코드	설명	응답 스키마
200	카드 혜택 정보 (없으면 null)	(nullable)
500	서버 내부 오류

Response Examples

시나리오: KE 항공편 무이자 할부 혜택 조회

GET /flights/detail/KE-ICN-NRT-20260415-Y-1/benefit/free-installment

혜택 있음 응답 (200)

{
  "title": "무이자 할부 안내",
  "period": "2026.03.01 ~ 2026.05.31",
  "interestFreeCards": [
    {
      "cardCompanies": ["신한카드", "삼성카드"],
      "installments": "2-6"
    },
    {
      "cardCompanies": ["현대카드"],
      "installments": "2-3"
    }
  ],
  "cautions": [
    "법인카드, 체크카드, 선불카드는 할부 불가",
    "일부 카드는 무이자 할부 적용이 제한될 수 있습니다"
  ]
}

혜택 없음 응답 (200)

null

데이터 모델

FlightDetailView

항공편 상세 응답 최상위 객체.

필드	타입	필수	설명
`detailKey`	string	O	상세 키
`id`	string	O	항공편 ID
`passengerFares`	Array<>	O	탑승객별 운임
`validatingCarrier`		O	발권 항공사
`fares`	Array<>	O	운임 옵션 목록
`schedules`	Array<>	O	구간별 스케줄
`avail`	int32	O	잔여 좌석 수
`passengerChangeable`	boolean	O	탑승자 변경 가능 여부
`cardPromotionName`	string	X	카드 프로모션명
`promotionPrincipleId`	int64	X	프로모션 정책 ID
`tags`	Array<string>	O	태그 목록
`tripType`		O	여정 유형
`totalPrice`	int64	O	전체 합계 가격 (computed)
`totalDiscount`	int64	X	전체 할인 금액 (computed)
`adultPrice`	int64	O	성인 1인 가격 (computed)
`originalAdultPrice`	int64	O	성인 1인 할인 전 가격 (computed)

PassengerFareView

필드	타입	필수	설명
`type`		O	탑승객 유형
`count`	int32	O	인원 수
`airPrice`	int64	O	항공 운임
`fuelCharge`	int64	O	유류할증료
`otherTax`	int64	O	기타 세금
`ticketingFee`	int64	O	발권대행수수료
`discount`	int64	O	할인 금액
`total`	int64	O	합계 (`airPrice + fuelCharge + otherTax + ticketingFee - discount`)

FlightFareDetailView

필드	타입	필수	설명
`passengerFares`	Array<>	O	탑승객별 운임
`adultPrice`	int64	O	성인 1인 가격
`cardPromotionName`	string	X	카드 프로모션명
`promotionPrincipleId`	int64	X	프로모션 정책 ID
`tags`	Array<string>	O	태그 목록

ScheduleView

필드	타입	필수	설명
`title`	string	O	구간 제목 (가는편, 오는편, 여정 N)
`totalFlightTime`	string	O	총 비행시간 (ISO 8601 duration)
`departure`		O	출발지
`arrival`		O	도착지
`segments`	Array<>	O	세그먼트 목록
`stop`	int32	O	경유 횟수
`mainCarrier`		O	대표 항공사 (computed)
`carrierText`	string	O	항공사 텍스트 (computed)

SegmentView

필드	타입	필수	설명
`departure`		O	출발지
`arrival`		O	도착지
`marketingCarrier`		O	마케팅 항공사
`operatingCarrier`		X	실운항 항공사 (공동운항 시)
`flightNumber`	string	O	편명
`cabin`		O	좌석 등급
`bookingClass`	string	O	예약 클래스
`freeBaggage`		X	무료 수하물
`legs`	Array<>	O	레그 목록
`amenity`		X	기내 편의시설

LegView

필드	타입	필수	설명
`departure`		O	출발지
`arrival`		O	도착지
`flightTime`	string	O	비행시간 (ISO 8601 duration)
`connectingTime`	string	X	환승 대기시간
`transferAirport`	boolean	X	공항 이동 여부

LocationView

필드	타입	필수	설명
`code`	string	O	공항 IATA 코드
`name`	string	X	공항명
`dateTime`	date-time	O	일시
`cityName`	string	X	도시명
`terminal`	string	X	터미널

AirlineView

필드	타입	필수	설명
`code`	string	O	IATA 항공사 코드
`name`	string	X	항공사 한글명
`logoUrl`	string	X	항공사 로고 URL

FreeBaggageView

필드	타입	필수	설명
`unit`	string	O	수하물 단위 (개, kg, lb)
`allowance`	int32	O	허용량

AmenityView

기내 편의시설 정보.

필드	타입	설명
`beverages`	Array<BeverageView>	음료 (type: BeverageType, cost: CostType)
`entertainment`	EntertainmentView	엔터테인먼트 (type: EntertainmentType, cost: CostType)
`food`	FoodView	식사 (type: FoodType, cost: CostType)
`layout`	LayoutView	좌석 배치 (rowLayout, directAisleAccess)
`power`	PowerView	전원 (type: PowerType, distribution, cost: CostType)
`seat`	SeatView	좌석 (pitch, type: SeatType)
`wifi`	WifiView	와이파이 (type: WifiType, cost: CostType)

FareRuleView

필드	타입	필수	설명
`groupTitle`	string	O	운임 규정 그룹 제목
`rules`	Array<>	O	규정 항목 목록

FareRuleItemView

필드	타입	필수	설명
`type`		X	규정 유형
`title`	string	O	규정 제목
`content`	string	X	규정 내용
`order`	int32	O	정렬 순서

CardBenefitView

필드	타입	필수	설명
`title`	string	O	제목
`period`	string	O	적용 기간
`interestFreeCards`	Array<>	O	무이자 카드 목록
`cautions`	Array<string>	O	주의사항

InterestFreeView

필드	타입	필수	설명
`cardCompanies`	Array<string>	O	카드사 목록
`installments`	string	O	할부 개월 (예: “2-6”)

ErrorView

필드	타입	필수	설명
`status`	int32	O	HTTP 상태 코드
`code`	string	O	에러 코드
`title`	string	X	에러 제목
`message`	string	X	에러 메시지
`messageArguments`	Array	X	메시지 인자

Enums (참조)

Enum	값
TripType	`ONE_WAY`, `ROUND_TRIP`, `MULTI_CITY`
PassengerType	`ADULT`, `CHILD`, `INFANT`
CabinType	`ECONOMY`, `PREMIUM_ECONOMY`, `BUSINESS`, `FIRST`
FareRuleType	`REFUND_AND_CHANGE`, `BAGGAGE`, `MILEAGE`, `COMMON`

Molidae Docs

탐색기

FlightDetailController DFS (Detailed Functional Specification)

FlightDetailController DFS (Detailed Functional Specification)

문서 정보

목차

개요

API 엔드포인트 목록

상세 스펙

1. 항공편 상세 조회 (detailKey)

Parameters

Responses

Response Examples

성공 응답 (200)

에러 응답 (404)

에러 응답 (410)

2. 항공편 상세 조회 (listKey + id)

Parameters

Responses

3. 운임 규정 조회 (deprecated)

Parameters

Responses

Response Examples

성공 응답 (200)

4. 무이자 할부 카드 혜택 조회

Parameters

Responses

Response Examples

혜택 있음 응답 (200)

혜택 없음 응답 (200)

데이터 모델

FlightDetailView

PassengerFareView

FlightFareDetailView

ScheduleView

SegmentView

LegView

LocationView

AirlineView

FreeBaggageView

AmenityView

FareRuleView

FareRuleItemView

CardBenefitView

InterestFreeView

ErrorView

Enums (참조)

그래프 뷰

목차

백링크