아마데우스 GDS API 분석 문서

1. 개요

1.1 아마데우스 GDS 시스템

• 공급사 타입: Global Distribution System (GDS)
• 통신 방식: SOAP over HTTPS
• 인증 방식: 세션 기반 인증 (Session-based Authentication)
• 트랜잭션 관리: Stateful Session Management
• 주요 특징: PNR 기반 예약 관리, TST(Transitional Stored Ticket) 처리

1.2 아키텍처 특징

Controller Layer → Service Layer → Client Layer → Amadeus SOAP API
     ↓                  ↓               ↓
  Request DTO      Business Logic   SOAP Request/Response
     ↓                  ↓               ↓
  Response DTO     Domain Model    Session Management

1.3 세션 관리 메커니즘

• TransactionStatusCode: Start → InSeries → End
• Session: sessionId, sequenceNumber, securityToken
• StatefulBuilder: 세션 상태를 유지하며 연속적인 API 호출 관리

---

2. API 엔드포인트별 상세 분석

2.1 항공편 검색 API (Flight Search)

2.1.1 검색 API

엔드포인트: POST /internals/AMADEUS/search

기능 설명

• 아마데우스 GDS를 통한 항공편 검색
• 다중 구간, 다중 공항 검색 지원
• 캐싱 및 Circuit Breaker 패턴 적용

요청 파라미터

data class SearchRequest(
    val originDestinationLocationInfos: List<OriginDestinationLocationInfo>,
    val cabins: List<CabinType>,
    val preferences: List<SearchPreference>,
    val airlines: List<String>?,
    val sotoAirlines: List<String>?,
    val onlyDirect: Boolean,
    val onlyFreeBaggageInclude: Boolean,
    val advancedOption: AdvancedOption?,
    val useCache: Boolean = true,
    val useMultiTicket: Boolean = false,
    val logging: Boolean = false
)

비즈니스 로직 단계

1. 캐시 확인: Redis에서 기존 검색 결과 확인
2. 요청 키 생성: CacheKeyGenerator로 고유 키 생성
3. 공항 확장: 도시 코드를 공항 코드 리스트로 변환
4. 병렬 검색: Cartesian Product로 모든 조합 병렬 검색
5. SOAP 요청: FareMasterPricerTravelBoardSearch 호출
6. 결과 병합: 중복 제거 및 필터링
7. 캐싱 저장: Redis에 결과 저장 (TTL 적용)

에러 처리

• Circuit Breaker: 실패율 35% 초과 시 차단
• Fallback: 빈 리스트 반환
• Retry: 3회 재시도 (지수 백오프)

2.1.2 상세 조회 API

엔드포인트: GET /internals/AMADEUS/search

기능 설명

• 캐시된 운임 정보 상세 조회
• 편의 시설(Amenity) 정보 포함

---

2.2 예약 API (Booking)

2.2.1 예약 생성

엔드포인트: POST /internals/AMADEUS/bookings

비즈니스 로직 단계

stateful {
    // 1. 세션 시작
    start {
        amadeusClient.markSeat() // 좌석 예약
    }
 
    // 2. 연속 트랜잭션
    inSeries {
        amadeusClient.saveReservationInfo() // 예약 정보 저장
        amadeusClient.addPassengers()       // 승객 정보 추가
        amadeusClient.addContactInfo()      // 연락처 추가
        amadeusClient.addSSR()              // 특별 서비스 요청
    }
 
    // 3. 트랜잭션 종료
    end {
        amadeusClient.commitReservation()   // 예약 확정
    }
}

주요 처리 사항

• 좌석 마킹: AirSellFromRecommendation
• 승객 정보: PnrAddMultiElements (이름, 생년월일, 여권)
• SSR 추가: DOCS, CTCE, CTCM 등
• PNR 생성: 6자리 영숫자 코드
• 검증: 스케줄 상태(HK/KK) 확인

2.2.2 예약 조회

엔드포인트: GET /internals/AMADEUS/bookings/{pnr}

처리 로직

1. PnrRetrieve 호출
2. 예약 정보 파싱
3. 스케줄 상태 검증
4. 도메인 모델 변환

2.2.3 예약 취소

엔드포인트: PUT /internals/AMADEUS/bookings/{pnr}/cancel

취소 유형

• 자동 환불: 카드 결제 정보로 자동 환불 처리
• 수동 환불: 환불 정보만 생성
• 면책 취소: Waiver 적용 취소

처리 단계

1. 예약 조회 및 검증
2. 발권 상태 확인
3. 취소 가능 여부 판단
4. PnrCancel 또는 DocRefund 처리
5. 큐 제거

---

2.3 발권 API (Ticketing)

2.3.1 발권 준비

엔드포인트: POST /internals/AMADEUS/ticketing/ready

검증 사항

• Carrier Time Limit 확인
• Carrier PNR 존재 여부
• 기존 티켓 중복 확인
• 스케줄 상태 (HK/KK)

2.3.2 발권 실행

엔드포인트: POST /internals/AMADEUS/ticketing

발권 프로세스

stateful {
    start {
        // 1. PNR 조회
        val pnrInfo = amadeusClient.getPnrInfo(pnr)
    }
 
    inSeries {
        // 2. 운임 계산
        amadeusClient.pricePnr()
 
        // 3. TST 생성
        amadeusClient.createTST()
 
        // 4. 결제 정보 추가
        amadeusClient.addFormOfPayment()
 
        // 5. 티켓 발행
        amadeusClient.issueTicket()
    }
 
    end {
        // 6. 세션 종료
        amadeusClient.endTransaction()
    }
}

주요 API 호출

• FarePricePnrWithBookingClass: 운임 계산
• TicketCreateTstFromPricing: TST 생성
• FopCreateFormOfPayment: 결제 정보
• DocIssuanceIssueTicket: 실제 발권

---

2.4 운임 규정 API (Fare Rules)

엔드포인트: GET /internals/AMADEUS/fare-rules

기능 설명

• 운임 규정 및 제한 사항 조회
• 환불/변경 수수료 정보

처리 로직

1. 캐시된 운임 정보 조회
2. CommandCryptic으로 규정 조회
3. 규정 텍스트 파싱
4. 구조화된 정보 반환

---

2.5 큐 관리 API (Queue Management)

2.5.1 큐 목록 조회

엔드포인트: GET /internals/AMADEUS/queues

큐 타입

• 예약 큐 (0-99)
• 발권 큐 (100-199)
• 시간 제한 큐 (200-299)

2.5.2 큐 제거

엔드포인트: PUT /internals/AMADEUS/queues

처리 로직

• 큐 번호별 그룹핑
• 배치 제거 처리
• 결과 집계

---

3. 공통 컴포넌트

3.1 세션 관리 (StatefulBuilder)

// 세션 관리 패턴
fun <T> stateful(block: StatefulBuilder.() -> T): T {
    return StatefulBuilder().block()
}
 
// 사용 예시
stateful {
    start { /* 세션 시작 */ }
    inSeries { /* 연속 작업 */ }
    end { /* 세션 종료 */ }
}

3.2 Redis 캐싱 전략

캐시 키 구조

AMADEUS_{channel}_{requestHash}_{timestamp}

TTL 설정

• 검색 결과: 30분
• 운임 규정: 24시간
• 예약 정보: 캐싱 안함

3.3 Circuit Breaker 설정

resilience4j.circuitbreaker:
  instances:
    amadeusSearch:
      slidingWindowSize: 180
      failureRateThreshold: 35
      waitDurationInOpenState: 120s
      slowCallRateThreshold: 90
      slowCallDurationThreshold: 15s

3.4 에러 처리 패턴

에러 타입별 처리

• SessionExpiredException: 새 세션 시작 후 재시도
• StatusInvalidException: 예약 상태 불일치
• TimeoutException: Circuit Breaker 적용
• SOAPFaultException: 상세 에러 메시지 파싱

---

4. 아마데우스 특징

4.1 SOAP 세션 관리

• 상태 유지: 모든 작업이 세션 내에서 순차 실행
• 시퀀스 번호: 각 요청마다 증가
• 트랜잭션: Start → InSeries → End 패턴

4.2 PNR 시스템

• 구조: 6자리 영숫자 (예: ABC123)
• 정보 포함: 승객, 일정, 요금, SSR, OSI
• 상태 코드: HK(확정), KK(확인중), UN(대기)

4.3 TST (Transitional Stored Ticket)

• 용도: 발권 전 운임 정보 임시 저장
• 번호: 1부터 시작하는 순차 번호
• 유효기간: 생성 후 72시간

4.4 특수 요청 (SSR/OSI)

• SSR: Special Service Request (식사, 휠체어 등)
• OSI: Other Service Information (추가 정보)
• DOCS: 여권 정보
• CTCE/CTCM: 연락처 정보

---

5. 주의사항

5.1 성능 고려사항

• 세션 유지 비용이 높음
• 병렬 처리 시 세션 분리 필요
• 캐싱 적극 활용 권장

5.2 에러 처리

• 세션 만료 시 자동 재연결
• PNR 락 발생 가능 (동시 접근 방지)
• 발권 실패 시 TST 정리 필요

5.3 보안

• 세션 토큰 안전 관리
• PCI DSS 준수 (카드 정보)
• 민감 정보 로깅 금지

---

6. 트러블슈팅 가이드

6.1 일반적인 문제

문제	원인	해결 방법
SESSION EXPIRED	세션 타임아웃	새 세션 시작
PNR LOCKED	동시 접근	재시도 또는 대기
INVALID STATUS	스케줄 변경	상태 재확인
TST NOT FOUND	TST 만료	TST 재생성

6.2 디버깅 팁

• SOAP 요청/응답 로깅 활성화
• 세션 ID 추적
• PNR 히스토리 확인
• CommandCryptic 활용

---

7. 참고 자료

7.1 주요 클래스

• AmadeusClient: SOAP 통신 클라이언트
• StatefulBuilder: 세션 관리
• AmadeusFlightSearchService: 검색 서비스
• AmadeusBookingService: 예약 서비스
• AmadeusTicketingService: 발권 서비스

7.2 설정 파일

• application.yml: 기본 설정
• application-{env}.yml: 환경별 설정
• redisson-{env}.yml: Redis 설정

7.3 관련 문서

• Amadeus Web Services Documentation
• IATA NDC Standards
• PCI DSS Compliance Guide