가이드
API 연동이란, 여행 기업을 위한 설명
API 연동은 두 소프트웨어 시스템이 사람이 다시 입력하지 않아도 데이터를 주고받고 동작을 실행하도록 해주는 연결입니다. 이 가이드는 여행자, 예약 플랫폼, 공급사 API, 결제 게이트웨이 사이를 오가는 호텔 예약 한 건을 따라가며 그 원리를 설명합니다.
- 하나의 요청, 하나의 응답
- REST, XML, SOAP, 웹훅
- 네 개의 시스템을 거치는 예약 한 건
- 연동 테스트 방법
정의
API 연동이란 무엇인가, 쉬운 말로
API는 애플리케이션 프로그래밍 인터페이스의 약자로, 다른 소프트웨어가 대화할 수 있도록 시스템이 공개한 규칙의 집합입니다. API 연동은 데이터가 자동으로 흐르고 동작이 자동으로 일어나도록 플랫폼을 그 인터페이스 중 하나에 연결하는 작업입니다.
여행 업계에서 그 플랫폼은 보통 여행 예약 소프트웨어 같은 예약 시스템이고, 인터페이스는 공급사, 결제 게이트웨이 또는 업무 도구의 것입니다. 여행 API 연동 페이지는 PHPTRAVELS가 이런 연결을 어떻게 구축하는지 설명하고, 모든 연동에는 이미 연결된 공급사가 정리되어 있습니다.
데이터 교환
요금, 재고, 고객 정보, 상태 업데이트가 구조화된 형식으로 시스템 사이를 오갑니다.
동작 자동화
검색, 예약, 결제, 취소, 대사가 누군가 손으로 반복하는 단계가 아니라 요청으로 처리됩니다.
결과 추적
모든 호출에 참조값이 붙으므로 실패한 예약을 원인이 된 요청까지 거슬러 추적할 수 있습니다.
요청
POST /v1/hotels/availability HTTP/1.1Host: api.supplier.exampleAuthorization: Bearer sk_test_••••••••Content-Type: application/json{ "city": "DXB", "check_in": "2026-11-12", "check_out": "2026-11-14", "guests": 2, "currency": "USD"}응답
HTTP/1.1 200 OKContent-Type: application/jsonX-Request-Id: req_7f3a91{ "hotel": "Palm Marina Hotel", "room": "Deluxe, 2 adults", "rate": { "amount": 438.00, "currency": "USD" }, "refundable": true, "rate_key": "rk_19d2c7"}API 호출 한 번의 구조
- 1
엔드포인트와 메서드
작업의 주소와 그에 적용하는 동사입니다. availability에 POST를 보내면 객실 검색을 뜻합니다.
- 2
인증
키, 토큰 또는 서명으로 호출 주체를 증명합니다. 공급사는 샌드박스와 운영 환경에 별도의 자격 증명을 발급합니다.
- 3
페이로드
구조화된 입력값: 도시, 날짜, 투숙객 수, 통화. 각 필드는 공급사 문서가 정의합니다.
- 4
상태 코드
호출 결과를 알려주는 숫자입니다. 200은 성공, 4xx는 요청 쪽 문제, 5xx는 공급사 쪽 문제입니다.
- 5
요청 ID
양쪽이 모두 보관하는 식별자입니다. 지원팀이 어떤 예약에 무슨 일이 있었는지 물을 때 찾는 값이 바로 이것입니다.
- 6
응답 본문
공급사 형식으로 돌아온 답변으로, 플랫폼이 자체 객실, 요금, 정책에 매핑합니다.
예약 한 건, 시스템 네 개
호텔 예약 중에 API 연동이 하는 일
2박 숙박 한 건을 검색부터 바우처까지 따라가 보세요. 모든 화살표는 API 호출이고, 여행자는 처음과 마지막만 봅니다.
- 01두바이 호텔 검색, 2박, 투숙객 2명보낸 곳: 여행자, 받는 곳: 예약 플랫폼
- 02날짜, 투숙객, 통화를 담은 재고 요청보낸 곳: 예약 플랫폼, 받는 곳: 공급사 API
- 03객실, 요금, 정책, 레이트 키보낸 곳: 공급사 API, 받는 곳: 예약 플랫폼
- 04마크업과 통화를 적용한 결과 표시보낸 곳: 예약 플랫폼, 받는 곳: 여행자
- 05결제 전 선택한 레이트 키의 가격 재확인보낸 곳: 예약 플랫폼, 받는 곳: 공급사 API
- 06총액에 대한 결제 승인 요청보낸 곳: 예약 플랫폼, 받는 곳: 결제 게이트웨이
- 07승인 완료, 서명된 웹훅 수신보낸 곳: 결제 게이트웨이, 받는 곳: 예약 플랫폼
- 08투숙객 정보를 담은 예약 요청보낸 곳: 예약 플랫폼, 받는 곳: 공급사 API
- 09확인 번호와 취소 조건보낸 곳: 공급사 API, 받는 곳: 예약 플랫폼
- 10바우처, 청구서, 예약 참조번호보낸 곳: 예약 플랫폼, 받는 곳: 여행자
- 01여행자예약 플랫폼두바이 호텔 검색, 2박, 투숙객 2명
- 02예약 플랫폼공급사 API날짜, 투숙객, 통화를 담은 재고 요청
- 03공급사 API예약 플랫폼객실, 요금, 정책, 레이트 키
- 04예약 플랫폼여행자마크업과 통화를 적용한 결과 표시
- 05예약 플랫폼공급사 API결제 전 선택한 레이트 키의 가격 재확인
- 06예약 플랫폼결제 게이트웨이총액에 대한 결제 승인 요청
- 07결제 게이트웨이예약 플랫폼승인 완료, 서명된 웹훅 수신
- 08예약 플랫폼공급사 API투숙객 정보를 담은 예약 요청
- 09공급사 API예약 플랫폼확인 번호와 취소 조건
- 10예약 플랫폼여행자바우처, 청구서, 예약 참조번호
가운데의 플랫폼이 바로 API 연동이 사는 곳입니다. 여행자의 화면과 각 공급사의 형식 사이를 번역하고 모든 참조값을 저장합니다.
같은 순서가 GDS를 쓰는 항공권 예약 소프트웨어, 액티비티 공급사를 쓰는 투어 운영사 소프트웨어, 어떤 게이트웨이든 쓰는 결제 게이트웨이 연동에도 그대로 적용되며, 바뀌는 것은 필드명뿐입니다.
연동 방식
REST, XML, SOAP, 웹훅, GraphQL
공급사는 서로 다른 방식으로 인터페이스를 공개합니다. 방식은 선호가 아니라 공급사 문서가 정하므로 여행 플랫폼은 모두를 다룰 수 있어야 합니다.
REST와 JSON
JSON- 데이터 형식
- JSON 문서
- 전송 방식
- HTTP 메서드: GET, POST, PUT, DELETE
- 여행 업계에서 흔한 용도
- 최신 항공, 호텔, 액티비티, 결제 API
- 강점
- 가벼운 페이로드와 풍부한 개발 도구
- 주의할 점
- 규격이 느슨해 공급사마다 REST 해석이 다름
XML과 SOAP
XML- 데이터 형식
- XML 문서, 대개 엄격한 스키마 포함
- 전송 방식
- SOAP 봉투 또는 순수 XML을 담은 HTTP POST
- 여행 업계에서 흔한 용도
- GDS, 베드뱅크, 오래된 호텔·투어 시스템
- 강점
- 정식 계약, 서명, 서비스 정의
- 주의할 점
- 장황한 메시지와 무거운 파싱
웹훅
EVENT- 데이터 형식
- 상대방이 푸시하는 JSON 또는 XML
- 전송 방식
- 등록한 URL로 보내는 HTTP POST
- 여행 업계에서 흔한 용도
- 결제 결과, 예약 상태 변경, 발권 업데이트
- 강점
- 폴링 없이 일이 생기면 플랫폼에 알려줌
- 주의할 점
- 서명 검증과 중복 처리 필수
GraphQL
QUERY- 데이터 형식
- 보낸 쿼리 모양대로 구성된 JSON
- 전송 방식
- 단일 HTTP 엔드포인트
- 여행 업계에서 흔한 용도
- 일부 신규 유통 플랫폼과 내부 API
- 강점
- 필요한 필드만 정확히 요청
- 주의할 점
- 여행 공급사 지원은 아직 드묾
API 연동과 API 개발의 차이
이미 존재하는 인터페이스에 제품을 연결합니다. API는 공급사 소유이며, 클라이언트, 매핑, 주변 규칙은 여러분이 만듭니다.
다른 시스템이 제품에 연결할 때 쓰는 인터페이스를 만듭니다. 대리점 도구가 호출할 수 있는 B2B API가 그 예입니다. 계약과 버전은 여러분 소유입니다.
많은 여행 프로젝트는 둘 다 필요합니다. 플랫폼은 한쪽으로 공급사를 연동하고 다른 쪽으로 대리점과 파트너용 자체 API를 공개합니다.
연동 전과 후
시스템이 연동되면 무엇이 달라지는가
같은 예약 다섯 단계를 공급사 포털에서 손으로 처리할 때와 API 연동으로 처리할 때를 비교합니다.
검색
담당자가 공급사 포털을 하나씩 열어 가격을 견적서에 옮겨 적습니다.
검색 한 번이 연결된 모든 공급사로 퍼져 하나의 목록을 돌려줍니다.
가격
마크업을 스프레드시트에서 더하고, 견적을 보낼 때쯤이면 요금이 바뀌었을 수 있습니다.
마크업, 세금, 통화 규칙이 응답 시점에 적용되고 결제 전에 요금을 재확인합니다.
예약
투숙객 정보를 공급사 포털에 다시 입력하고, 오타가 예약 오류가 됩니다.
정보를 한 번만 보내 검증하고 공급사 확인과 함께 저장합니다.
결제
결제를 따로 받고 나중에 예약과 맞춥니다.
승인, 매입, 환불이 예약 참조번호에 묶입니다.
사후 처리
취소와 변경마다 또 로그인하고 또 이메일을 보냅니다.
변경과 취소가 같은 연결을 통해 처리되고 기록을 갱신합니다.
용어
API 문서에서 만나게 될 용어
거의 모든 공급사 개발자 포털에 등장하는 열두 단어를 여행 업계에서 쓰이는 의미로 정의했습니다.
API
애플리케이션 프로그래밍 인터페이스. 시스템과 대화하기 위해 공개된 규칙.
인증
API 키, bearer 토큰, 서명 또는 승인된 IP 주소로 호출 주체를 증명하는 것.
인증 심사
운영 자격 증명을 발급하기 전에 공급사가 연동을 검토하는 절차.
엔드포인트
검색, 예약, 취소처럼 작업 하나에 대응하는 주소 하나.
멱등성
같은 요청을 두 번 보내도 결과는 하나만 생겨 중복 예약과 중복 결제를 막음.
매핑
공급사의 필드, 코드, 이름을 플랫폼 자체 데이터 모델로 변환하는 것.
페이로드
요청이나 응답 안에 실려 오가는 데이터로, 보통 JSON 또는 XML.
요청 제한
공급사가 거부를 시작하기 전까지 초당 또는 일일 허용하는 호출 횟수.
요청과 응답
호출 한 번. 플랫폼이 묻고 공급사가 답하며 양쪽 모두 기록을 남김.
샌드박스
가짜 재고와 테스트 카드가 있는 테스트 환경으로, 실제로는 아무것도 예약되거나 결제되지 않음.
상태 코드
결과를 요약하는 HTTP 숫자: 200 성공, 401 미인증, 429 요청 제한 초과, 500 공급사 오류.
웹훅
반대 방향의 호출. 이벤트가 발생하면 공급사나 게이트웨이가 플랫폼에 알림.
테스트와 범위 정의
여행 API 연동을 운영 전에 테스트하는 방법
연동은 실패 경로까지 제대로 동작해야 끝납니다. 인증 심사와 운영 자격 증명 전환에 앞서 공급사 샌드박스에서 아래 케이스를 테스트합니다.
run integration tests
공급사 샌드박스, 9개 케이스
- OK: 유효한 자격 증명과 만료된 자격 증명으로 인증
- OK: 잘못된 요청을 읽기 쉬운 오류와 함께 거부
- OK: 공급사 타임아웃을 예약을 매달아 두지 않고 처리
- OK: 요청 제한을 지키고 대기 후 재시도
- OK: 재확인 시 가격 변동을 잡아 결제 전에 표시
- OK: 중복 제출 시 두 번째가 아닌 첫 번째 예약을 반환
- OK: 취소 적용 및 수수료 계산
- OK: 원 결제 건에 대한 환불 처리
- OK: 예약, 결제, 공급사 참조번호가 일치
모든 케이스 통과, 인증 심사 준비 완료
API 연동은 두 소프트웨어 시스템이 자동으로 데이터를 주고받고 동작을 실행하도록 하는 연결입니다. 한 시스템이 구조화된 요청을 보내면 다른 시스템이 구조화된 응답을 돌려주며, 양쪽 모두 합의된 보안 및 데이터 규칙을 따릅니다.
여행 업계에서는 예약 플랫폼을 항공, 호텔, 투어, 렌터카 공급사와 결제 게이트웨이, 업무 도구에 연결하는 것입니다. 재입력 없이 검색, 가격 검증, 예약, 취소, 환불, 대사를 지원합니다.
REST는 보통 HTTP로 JSON을 주고받는 아키텍처 스타일입니다. XML은 GDS와 베드뱅크 공급사에서 여전히 흔한 데이터 형식으로, 대개 SOAP으로 감싸집니다. 어느 쪽을 쓸지는 공급사의 계약과 문서가 정합니다.
공급사 접근 권한, 범위에 포함된 엔드포인트, 인증 심사, 매핑 규칙, 예약의 예외 상황에 따라 다릅니다. 신뢰할 만한 견적은 문서, 자격 증명, 필요한 워크플로를 검토한 뒤에 나옵니다.
인증, 유효한 요청과 잘못된 요청, 타임아웃, 요청 제한, 가격 변동, 중복 제출, 취소, 환불, 대사를 테스트합니다. 운영 환경에서는 모든 요청이 예약 참조번호까지 추적되어야 합니다.
아닙니다. 연동은 제품을 기존 API에 연결하는 것이고, 개발은 다른 쪽이 연결할 인터페이스를 만드는 것입니다. 여행 플랫폼은 흔히 둘 다 필요합니다. 한쪽으로는 공급사를 연동하고, 다른 쪽으로는 파트너용 B2B API를 공개합니다.