항공권 예약 API 연동: 문서에는 나오지 않는 것들

보드에 올라온 티켓에는 "항공 추가"라고 적혀 있습니다. 결제 연동도 해 봤고, 배송비 계산도, 어쩌면 지도 연동도 해 봤을 겁니다. 그래서 머릿속 모델은 가장 단순한 형태입니다. 검색하고, 결과를 보여 주고, 카드를 결제하면 끝. 그런데 첫 실제 예약은 결과 화면과 다른 가격으로 돌아오고, 두 번째는 타임아웃이 나서 고객에게 좌석이 있는지 아무도 모르며, 운영팀에서는 예약은 있는데 왜 항공권이 없느냐고 묻습니다. 항공권 예약 API 연동은 밖에서 보면 이커머스 결제처럼 생겼습니다. 하지만 그 아래는 REST보다 훨씬 오래전에 설계된 시스템을 상대로 한 분산 트랜잭션이고, 놀랄 일의 대부분은 그 간극에서 나옵니다.
이 글은 PNR을 한 번도 본 적 없는 개발자를 위한 것입니다. 특정 공급사의 엔드포인트 이야기가 아닙니다. 이름은 공급사마다 바뀌어도 구조는 바뀌지 않습니다.
항공권 예약 API 연동의 호출 순서
거의 모든 항공 API는 메서드 이름이 무엇이든 같은 네 단계를 거칩니다. 단계 사이의 경계를 제대로 긋는 것이 일의 대부분입니다.
| 단계 | 받는 것 | 저장해야 하는 것 | 잘못되는 지점 |
|---|---|---|---|
| 검색 | 가격과 불투명한 오퍼 키 또는 운임 키가 붙은 여정 | 영구 저장할 것은 없음 — 결과는 금방 낡음 | 가격을 확정가로 취급; 결제 전에 키가 만료됨 |
| 가격 확인 / 검증 | 확정된 가격, 운임 규정, 수하물, 때로는 필수 승객 항목 | 검증된 오퍼와 만료 시각 | 가격 변동; 해당 클래스 매진; 규정이 화면에 보여 준 것과 다름 |
| 예약 | 예약 레코드 — PNR — 와 예약번호, 발권 기한 | 자체 참조번호, 예약번호, 기한, 실제로 보낸 승객 데이터 그대로 | 응답 없는 타임아웃; 중복 PNR; 이름 거절 |
| 발권 | 발행된 전자항공권 번호; 실제로 돈이 확정되는 곳 | 모든 항공권 번호를 해당 승객과 구간에 연결해서 | 일부만 발권; 기한이 지나 항공사가 예약을 취소 |
사람들이 가장 많이 반박하는 건 세 번째 줄입니다. 많은 API가 예약과 발권을 한 번의 호출로 처리하게 해 주기 때문입니다. 써도 됩니다. 하지만 항공사의 세계에서 둘은 여전히 별개입니다. 항공권 없이 PNR이 존재할 수 있고, PNR이 만들어진 뒤에 발권이 실패할 수도 있습니다. 통합 엔드포인트는 한쪽은 성공하고 다른 쪽은 실패한 순간을 가릴 뿐이니, 데이터 모델에는 여전히 그 상태를 담을 자리가 있어야 합니다.
검색이 돌려주지 않는 것도 눈여겨보세요. 바로 약속입니다. 검색 결과는 광고입니다. 가격 확인 단계가 견적이고, 판매는 오직 항공권입니다.
검색한 가격으로 예약되지 않는 이유
웹 개발자는 상품 카탈로그를 기대합니다. 항공 좌석 재고는 카탈로그가 아닙니다. 한 항공편은 예약 클래스 단위로 팔리고, 각 클래스는 특정 운임의 좌석 묶음이며, 항공사는 좌석이 차는 대로 이 묶음을 계속 열고 닫습니다. 검색 결과는 이미 조금 뒤처졌을 수 있는 잔여석 정보로 빠르게 조립됩니다. 사용자가 여권 두 개를 입력하는 사이에 그 항공편의 가장 싼 클래스가 닫혔을 수 있습니다. 가격 확인 단계는 다시 묻고, 정직한 대답은 때로 더 비쌉니다.
세금도 따로 움직입니다. 세금은 가격 확인 시점에 실제 승객과 여정 기준으로 다시 계산되고, 소아나 유아는 검색이 가정한 성인과 가격이 다릅니다. 판매 화면이 원화로 표시되는데 공급사가 다른 통화로 견적을 낸다면 환율 변환도 숫자가 움직이는 또 하나의 지점입니다.
설계상의 결론은 단순하고 자주 빠집니다. 검색 가격으로 절대 결제하지 마세요. 결제 전에 가격 확인을 실행하고, 비교하고, 금액이 바뀌었으면 새 금액을 보여 주고 동의를 받으세요. 붙이는 마크업은 결과 화면에서 그대로 가져오지 말고 재확인된 운임 위에서 다시 계산해야 합니다. 여행사가 온라인 마크업 전략을 세울 때 거치는 논리와 같고, 기준가가 밑에서 움직이면 똑같이 깨집니다.
멱등성, 그리고 예약 중 타임아웃의 의미
이 부분은 두 번 읽으세요.
예약 호출이 타임아웃되면 무슨 일이 일어났는지 알 수 없습니다. 요청이 아예 도착하지 않았을 수도 있습니다. 도착했지만 실패했을 수도 있습니다. 아니면 — 가장 아픈 경우 — 도착했고, 공급사가 항공사에 PNR을 만들었고, 응답만 돌아오는 길에 사라졌을 수도 있습니다. 코드 입장에서는 셋 다 똑같아 보입니다. 항공사 입장에서 세 번째는 고객 이름으로 좌석을 잡고 있는 살아 있는 예약입니다.
다른 연동에서 익힌 반사 행동은 재시도입니다. 여기서 무작정 재시도하면 같은 승객, 같은 항공편에 두 번째 PNR이 생길 수 있습니다. 항공사는 중복 예약을 정책 위반으로 봅니다. 항공사와 여행사 계약에 따라 결과는 한쪽 또는 양쪽 예약의 자동 취소부터, 발권한 쪽에 보내는 정산 청구서인 ADM(Agency Debit Memo)까지 다양합니다. 그걸 받은 여행사는 당신의 시스템이 왜 두 번 예약했는지 알고 싶어 할 겁니다.
효과가 있는 방법을 대략 순서대로 보면 다음과 같습니다.
- 외부 호출 전에 자체 예약 참조번호를 만드세요. 저장하고, API가 클라이언트 참조를 받는 곳이라면 어디든 요청에 함께 보내세요. API가 멱등성 키를 지원하면 쓰고, 지원하지 않아도 그 참조번호로 나중에 예약을 찾을 수 있습니다.
- '알 수 없음' 상태를 명시적으로 모델링하세요. 대기, 확정, 실패, 그리고 알 수 없음. 타임아웃은 예약을 실패가 아니라 알 수 없음으로 옮깁니다.
- 알 수 없음은 반복이 아니라 조회로 해결하세요. 다시 시도할지 정하기 전에 참조번호로 예약을 조회하거나 해당 승객의 최근 예약 목록을 확인하세요.
- 대사 작업을 돌리세요. 여전히 알 수 없는 건을 훑어 공급사가 보고하는 내용과 비교하고, 정리되지 않는 건은 추측하지 말고 사람이 보는 큐로 보내세요.
발권 타임아웃은 돈이 걸린 같은 문제입니다. 발권 전에 카드를 매입했는데 발권이 멈추면, 돈을 낸 고객은 있고 항공권은 없을 수 있습니다. 매입 전에 발권했는데 매입이 실패하면, 누군가 항공사에 대금을 치러야 하는 서류를 발행한 셈입니다. 흔한 방식은 카드 승인 먼저, 그다음 발권, 성공하면 매입입니다. 핵심은 이것을 의도적으로 정하는 것이지, 운영 환경에서 발견하는 것이 아닙니다.
웹 개발자가 놀라는 항공 개념들
어느 것도 어렵지 않습니다. 다만 하나하나가 그런 게 있는 줄 몰랐던 누군가의 일주일을 잡아먹었습니다.
PNR은 항공권이 아니다
PNR은 예약 기록입니다. 승객, 구간, 연락처, 기한이 들어 있습니다. 항공권은 승객에게 탑승 자격을 주는, 대금이 지불된 문서입니다. 발권되지 않은 PNR은 발권 기한에 만료되고 좌석은 다시 판매로 돌아가는데, 당신 쪽에서는 아무 신호 없이 그렇게 되기도 합니다.
이름은 거의 바꿀 수 없다
발권 후에는 대부분의 운임이 사소한 정정 외의 이름 변경을 허용하지 않고, 무엇이 사소한지는 항공사마다 다릅니다. 이름은 여권과 일치해야 합니다. 성과 이름을 따로 받고 — 한국어 이름은 여권의 영문 표기를 그대로 받으세요 — 자유 입력란의 호칭이 이름 필드로 새어 들어가지 않게 하며, 검증은 예약 호출 전에 하세요. 후가 아닙니다.
승객 유형은 장식이 아니라 가격이다
성인, 소아, 유아는 운임 유형이며, 어느 쪽인지 정하는 나이는 보통 예약일이 아니라 탑승일 기준입니다. 무릎에 앉는 유아는 대개 좌석을 차지하지 않고 성인과 함께만 탑승할 수 있습니다. 유형을 틀리면 가격 확인이 실패하거나 잘못된 운임을 냅니다.
시간은 현지 시각이고, 구간은 레그가 아니다
출발·도착 시각은 각 공항의 현지 시각으로 주어집니다. 표시할 때 사용자 시간대로 바꾸지 말고, 시차 없이 빼서 소요 시간을 계산하지도 마세요. 여정은 구간으로 이루어지고, 기술적 경유가 있는 구간은 레그가 둘 이상입니다. UI와 데이터가 무엇을 '경유'라고 부를지 합의해야 합니다.
판매 후에도 일은 일어난다
항공사는 발권 이후에도 스케줄을 바꿉니다. 발권 당시 맞았던 예약이 몇 주 뒤에 새 시각, 새 편명, 끊긴 연결편을 보여 줄 수 있고, 공급사에 따라 알림, 큐, 혹은 예약 재조회로 알게 됩니다. 더 이상 들여다보지 않게 된 뒤에도 예약은 바뀐다고 가정하고 설계하세요.
Void는 환불이 아니다
발권 직후에는 보통 항공권을 없었던 일처럼 void할 수 있는 시간이 있습니다. 그 시간이 지나면 운임 규정에 따른 환불만 가능하며, 위약금이 붙거나 아무것도 돌려받지 못할 수도 있습니다. 그 시간과 규칙은 공급사와 발권 계약에 달려 있으니 '취소' 버튼을 만들기 전에 읽어 두세요.
실수의 비용
항공 연동의 실패는 독특한 방식으로 비쌉니다. 로그가 아니라 사람에게 떨어집니다. 중복 예약은 항공사와의 통화가 되고, 어쩌면 여행사 계정에 대한 통지가 됩니다. 결제는 됐는데 항공권이 없는 고객은 환불, 민원, 차지백 위험이 됩니다. 결제 성공 없이 발행된 항공권은 누군가 갚아야 할 항공사 채무가 됩니다. 아무도 처리하지 않은 스케줄 변경은 이미 일찍 떠난 비행기를 기다리며 공항에 서 있는 승객이 됩니다.
이 중 어느 것도 정상 흐름 테스트에는 나타나지 않습니다. 비정상 흐름부터 작성하세요. 예약 중 타임아웃, 오른 가격, PNR 생성 후 실패한 발권, 결제 성공 뒤의 void. 이것들이 처리되어 있다면 정상 흐름은 쉬운 부분입니다.
항공 API 테스트하기
공급사의 테스트 환경은 유용하지만 불완전합니다. 대개 운영 환경보다 조용해서 매진 클래스나 가격 변동이 드물고, 일부는 타임아웃을 아예 재현하지 않습니다. 호출 구조와 검증 오류를 익히는 데 쓰고, 그다음 운영 환경에서 실제 예약을 만들어 void 가능 시간 안에 취소하는 통제된 테스트를 계획하세요. 물론 운영팀이 알고 있는 상태에서요.
애초에 연동을 할지는 별개의 질문입니다. 실제로 필요한 것이 자체 시스템 안의 원시 재고가 아니라 판매 사이트라면, 그 득실은 화이트라벨과 자체 예약엔진 구축 비교에 정리되어 있고, 같은 논리가 하위 대리점용 B2B 포털에도 적용됩니다. 재고를 자체 코드 안에 두고 싶다면 이 플랫폼은 항공·호텔 API를 제공하며, 접근은 셀프서비스 키가 아니라 사용 목적에 대한 대화로 시작합니다. 위의 질문들을 하나씩 던지기에도 바로 그때가 적절합니다.