본문으로 건너뛰기
블로그

예약 엔진 API 오류 처리: 돈이 새는 세 가지 장애

Tekravel 편집팀
AI의 도움을 받아 작성됨

목요일 저녁에 지원 티켓이 들어옵니다. 고객은 결제를 마쳤고, 화면은 계속 돌다가 일반적인 오류를 띄웠습니다. 카드에는 청구가 잡혔습니다. 로그에는 응답을 받지 못한 공급사 POST가 남아 있습니다. 항공사가 좌석을 잡아 두었을까요? 아무도 답하지 못하고, 고객은 기다리고 있습니다. 좋은 예약 엔진 API 오류 처리는 대부분 애초에 그 자리에 서지 않기 위한 작업이고, 서게 되더라도 무엇을 해야 하는지 정확히 아는 것입니다.

대부분의 연동 가이드는 오류를 상태 코드 목록으로 다룹니다. 예약에서 상태 코드는 쉬운 부분입니다. 돈이 드는 것은 요청이 실패한 것처럼 보이지만 현실은 바뀌었거나, 성공한 것처럼 보이지만 현실은 바뀌지 않은 소수의 상황입니다. 그중 세 가지가 나머지보다 중요합니다.

첫 번째 장애: 검색과 예약 사이에 가격이 움직였다

검색 결과는 견적이지 계약이 아닙니다. 운임은 캐시되고, 재고는 공급사가 판매하는 모든 채널이 공유하며, 14시 02분에 보여 준 숫자는 몇 분 뒤 낡아 있을 수 있습니다. 공급사는 예약 생성 단계에서 알려 줍니다. 깔끔하게 "fare changed"로 응답하기도 하고, 겉으로는 성공한 응답 안에서 조용히 다른 총액을 돌려주기도 합니다.

위험한 쪽은 두 번째입니다. 코드가 확인을 읽고 예약을 저장하고 고객이 본 금액 그대로 청구하면, 차액은 마진에서 나가거나 나중에 ADM으로 돌아옵니다. 그래서 규칙은 단순합니다. 공급사가 확정한 총액과 고객이 수락한 총액을 매번, 코드 안에서, 결제를 캡처하기 전에 비교하세요.

둘이 다를 때 무엇을 할지는 차이의 크기와 누가 부담하느냐에 달려 있습니다. 통화 간 몇 센트의 반올림은 한 번 정해 두는 허용 오차입니다. 그보다 크면 명시적인 수락 버튼과 함께 새 가격으로 고객에게 돌려보냅니다. 자동으로 흡수하지 말고, 자동으로 추가 청구하지도 마세요.

두 번째 장애: 예약은 됐지만 발권은 안 됐다

PNR이 있다는 것과 티켓이 있다는 것은 다릅니다. 많은 흐름이 예약을 먼저 만들고 e-티켓 발행을 별도 단계로 두며, 그 사이에 시간 제한이 있습니다. 결제는 성공했는데 발권이 실패하면, 고객의 돈과 자기 시계대로 만료되는 예약을 함께 쥐고 있게 됩니다.

이 장애는 좀처럼 시끄럽지 않습니다. 발권 호출이 오류나 타임아웃을 반환하고, 예약은 데이터베이스에서는 "paid"인데 공급사는 여전히 "held"라고 하는 상태로 남습니다. 그 사이 발권 시한은 흘러가고, 지원 대기열과 달리 항공사는 기다려 주지 않습니다.

성공이나 실패의 변형이 아니라 독립된 상태로 다루세요. 예약에는 최소한 다음 상태가 필요합니다. created, held, payment captured, issuing, ticketed, failed-and-refundable. "payment captured, issuing"은 타이머가 필요한 상태입니다. 예약이 거기에 너무 오래 머물면 사람이 알아채기를 기다리지 말고 작업이 공급사에서 예약을 다시 읽어 판단해야 합니다. 공급사의 시한을 알고 있으면 판단은 저렴합니다. 환불로 넘어가기 전까지 얼마나 안전하게 재시도할 수 있는지 알려 주기 때문입니다.

세 번째 장애: 결과를 알 수 없는 타임아웃

이것이 목요일 저녁의 티켓입니다. 요청은 나갔고, 응답은 돌아오지 않았으며, 연결이 끊겼거나 게이트웨이가 포기했습니다. 공급사는 완전히, 일부, 혹은 전혀 처리하지 않았을 수 있습니다.

유혹은 재시도입니다. 예약 생성 호출을 맹목적으로 재시도하지 마세요. 두 번째 시도가 두 번째 예약을 만들 수 있고, 중복은 실제 비용입니다. 좌석 두 개가 묶이고, 어쩌면 티켓이 두 장 발행되며, 그중 하나를 두고 환불 다툼이 벌어집니다.

안전한 순서는 멈추고, 읽고, 판단하는 것입니다. 고객 쪽 흐름은 "예약을 확인하고 있습니다"라는 정직한 상태로 멈춥니다. 공급사 쪽은 호출 전에 생성한 참조 번호로 예약을 조회해서 읽습니다(그래서 자체 클라이언트 참조를 먼저 만들고, 공급사가 받아 준다면 함께 보내는 것입니다). 그다음에야 판단합니다. 찾으면 실제 상태에서 이어 가고, 공급사 자체의 처리 시간 창이 지나도 찾지 못하면 한 번 재시도해도 안전합니다.

공급사가 자체 참조로 조회할 방법을 주지 않는다면, 좁은 시간 창 안에서 탑승자 이름, 노선, 날짜로 검색하고 일치하는 건을 찾은 것으로 취급하세요. 보기 흉하지만 중복보다는 훨씬 쌉니다.

반박해도 좋은 판단 표

보이는 것알고 있는 것할 일하지 말 것
공급사가 "fare changed"를 반환아무것도 예약되지 않음새 총액을 보여 주고 수락을 받은 뒤 create 재실행옛 가격으로 다시 실행하고 통과하기를 바람
성공했지만 총액이 고객이 수락한 금액과 다름새 가격으로 예약이 존재함결제를 보류하고 고객에게 묻고, 거절하면 예약을 void옛 금액을 캡처하고 차액을 떠안음
결제는 캡처됐고 발권 호출이 오류PNR은 있고 티켓 상태는 불명예약을 다시 읽고 시한 내에 issue 재시도, 시한 후 환불예약을 실패로 표시하고 PNR을 잊음
create에서 타임아웃결과 불명자체 참조로 조회한 뒤 계속하거나 한 번만 재시도즉각적인 맹목 재시도
cancel에서 타임아웃구간에 대한 책임이 남아 있을 수 있음고객에게 무언가 말하기 전에 상태를 다시 읽기버튼을 눌렀다는 이유로 "cancelled" 표시

이견이 나올 만한 행이 하나 있습니다. 일부 팀은 고객을 진정시키려고 첫 발권 오류에서 바로 환불합니다. 저가 티켓에서는 변호할 만하지만 고가 티켓에서는 나쁜 습관입니다. 1분 뒤에 살릴 수 있었던 운임을 잃을 수 있기 때문입니다.

잘못 처리하면 얼마가 드는가

장애마다 청구서가 다릅니다. 놓친 가격 변동은 영향받는 모든 예약에서 마진 손실이며, 대사 때까지 눈에 띄지 않는 경우가 많습니다. 예약됐지만 발권되지 않은 건은 만료된 예약과 카드 청구를 안고 공항에 도착하는 고객이며, 차지백과 평판 문제가 동시에 터집니다. 타임아웃 때의 맹목 재시도는 중복 예약이고, 항공사는 중복을 감사합니다. 그런 사례의 반복은 ADM으로 이어지기 쉽습니다.

이 중 특별한 것은 없습니다. 데모와 주말 내내 돌려 둘 수 있는 서비스를 가르는, 눈에 띄지 않는 배관 작업입니다.

필요해지기 전에 대사 작업을 만드세요

세 장애는 모두 같은 곳에서 끝납니다. 내 데이터베이스와 공급사의 데이터베이스가 서로 다르다는 것입니다. 그러니 첫 사고 이후가 아니라 이전에 둘을 비교하는 작업을 작성하세요. 야간 실행이 최소한이며, 전환 중인 상태의 건은 몇 분마다 도는 편이 더 낫습니다. held, issuing, unknown에 걸린 예약을 나열하고, 공급사에 물어본 뒤, 레코드를 고치거나 증거를 첨부한 티켓을 엽니다.

예약 호출의 모든 요청과 응답을 타임아웃까지 포함해, 보낸 참조 번호와 함께 보관하세요. 고객이 청구에 이의를 제기하면 그 로그가 곧 근거입니다. 지연 시간 논의를 정직하게 유지하는 데도 도움이 됩니다. 타임아웃이 없애야 할 버그가 아니라 피할 수 없는 현실인 이유는 API 지연 시간에서 고칠 수 있는 것과 없는 것을 참고하세요.

공급사 연결 자체를 어떻게 구성할지 아직 정하는 중이라면, 항공권 예약 API 연동 안내가 이 글이 전제하는 호출 순서를 다룹니다. 그리고 이 상태들이 저희 항공편 및 호텔 API에 어떻게 대응되는지 이야기하고 싶다면, 접근은 대화에서 시작됩니다: 여행 API 페이지를 확인하세요.

Tekravel 편집팀

여행 기술 데스크

Tekravel 여행 기술 데스크는 업계 독자를 위해 씁니다. 여행사 대표, 콘솔리데이터, 그리고 이들을 연동하는 개발자입니다. 모든 기사는 공개 전에 해당 기사가 다루는 플랫폼에서 확인합니다.