항공 API

운임 캘린더

GET /v1/flights/price-calendar?origin=DXB&destination=LHR&departureFrom=2026-11-01&departureTo=2026-11-30은 해당 노선의 날짜별 최저 캐시 운임을 요청 통화로 반환하며, 캐시가 얼마나 최신인지도 알려 줍니다. 날짜 쌍별 왕복 총액을 원하면 returnFrom / returnTo를, 클래스를 제한하려면 cabin을 추가하세요. 당사 가격 캐시에서 제공되므로 즉시 응답하며 공급사 검색으로 계산되지 않습니다 — 실제 검색 전에 캘린더나 “최저가 날짜” 띠를 그리는 데 활용하세요.

검색

POST /v1/flights/search에 편도는 구간 1개, 왕복은 2개, 다구간은 최대 6개를 지정하고, 유형별 승객 수와 선택 사항인 캐빈 및 최대 경유 횟수(maxStops)를 전달합니다. wait=true이면 모든 공급사가 응답한 후 전체 오퍼가 담긴 응답을 받고, wait=false이면 searchId를 받아 complete가 true가 될 때까지 커서와 함께 GET /v1/flights/search/{searchId}를 폴링합니다.

각 오퍼에는 불투명한 offerId, 승객별 내역이 포함된 요청 통화 기준 총액, 구간 → 세그먼트(항공사, 편명, 시각, 기종, 캐빈, 수하물), 운임 조건 요약, 만료 시각이 들어 있습니다. 오퍼는 검색 세션이 유지되는 동안(약 20분) 유효합니다.

가격 확인과 규정

POST /v1/flights/offers/{offerId}/price는 확정 직전에 공급사와 운임을 재검증하고, 확정 가격, 세금, 항공사가 요구하는 승객 입력 항목(여권 등 서류, 생년월일, 마일리지 회원 번호)을 반환합니다. GET .../fare-rules는 위약금 규정 문구를, GET .../ancillaries는 주문에 추가할 수 있는 유료 수하물과 옵션을 반환합니다.

부가 서비스(추가 수하물)

GET /v1/flights/offers/{offerId}/ancillaries는 해당 운임에서 항공사가 제공하는 유료 부가 서비스를 나열합니다 — 현재는 추가 위탁 수하물 허용량으로, 각각 key, 개수 / 무게, 승객당 가격이 포함됩니다. 유료란 오퍼 자체에 표시된 기본 포함 허용량과 달리 운임과 별도로 가격이 매겨지고 주문과 함께 청구된다는 뜻입니다.

구매하려면 POST /v1/flights/orders에 ancillaries[]를 추가하세요: 부가 서비스마다 key와 passengerIndex(passengers의 0부터 시작하는 인덱스)를 담은 항목 하나. 주문과 함께 가격이 매겨지고 예약·발권되며 주문의 항공권 총액에 표시됩니다. 이미 발권된 주문에는 부가 서비스를 추가할 수 없으며, 좌석 선택도 같은 방식으로 제공될 예정입니다.

{
  "offerId": "fo_7Gk2Qp9LcKM5aGqrMQOIzJko",
  "passengers": [{ "type": "ADT", "gender": "M", "firstName": "SAM", "lastName": "TRAVELLER", "dateOfBirth": "1990-05-04" }],
  "contact": { "email": "[email protected]", "phone": "+971501234567" },
  "ancillaries": [{ "key": "BAG20-1", "passengerIndex": 0 }]
}

주문 생성

POST /v1/flights/orders에 offerId, 승객(여권과 동일한 이름, 유형, 생년월일, 국제선 여정의 경우 여행 서류), 연락처, 선택 사항인 ancillaries[](위 참조)를 전달하고 Idempotency-Key를 추가하세요. orderId, 항공사 PNR, 발권 기한, held 상태를 받게 됩니다. 샌드박스에서는 주문이 공급사의 테스트 시스템에 기록되며 비용이 청구되지 않고, 프로덕션에서는 예치금이 예약(홀드)됩니다.

발권

POST /v1/flights/orders/{orderId}/issue(Idempotency-Key 필수)는 전자 항공권을 발행하고 승객별 항공권 번호를 반환합니다. GET /v1/flights/orders/{orderId}로 언제든지 주문을 조회할 수 있으며, 상태는 held → issued → cancelled/refunded 순으로 바뀝니다.

보이드, 취소, 환불

GET /v1/flights/orders/{orderId}/refund-quote는 운임 규정에 따라 취소 시 돌려받는 금액을 알려 줍니다(당일 보이드는 보통 무료). POST /v1/flights/orders/{orderId}/cancel로 확정하면 환불액이 예치금 원장에 반영되며 개발자 포털에서 확인할 수 있습니다.