환경, 한도, 버전 관리

샌드박스와 프로덕션, 하나의 기본 URL

기본 URL: https://api.dubaitrip.com/v1. 샌드박스와 프로덕션이 함께 사용하며, 서명에 사용한 키가 환경을 결정합니다. dt_sbx_ 키는 공급사의 테스트 환경에서 실행됩니다 — 검색, 가격 확인, 요금 확인, 주문, 예약, 발권, 취소가 모두 테스트 재고로 처음부터 끝까지 작동하며, 실제 항공권이나 바우처는 발행되지 않고 비용도 청구되지 않습니다. 프로덕션 검토 후 발급되는 dt_live_ 키는 실제 재고에 연결되어 예치금으로 정산됩니다.

샌드박스 예약과 프로덕션 예약은 개발자 포털에서 구분되어 표시되며(예약마다 표시가 붙음), 스코프, 한도, IP 규칙은 환경별로 관리됩니다.

요청 속도 제한과 할당량

각 키는 토큰 버킷(초당 지속 요청 수와 버스트)과 일일 할당량으로 제한됩니다. 샌드박스 기본값: 초당 2건, 버스트 5, 하루 2,000건. 프로덕션 한도는 계정별로 협의합니다. 버킷을 초과하면 Retry-After 헤더와 함께 429 api_rate_limited가 반환되고, 할당량을 소진하면 UTC 자정까지 429 api_quota_exceeded가 반환됩니다.

무거운 검색은 설계상 비동기입니다. wait=false를 전달하면 즉시 searchId를 받아 검색 엔드포인트를 폴링할 수 있고, wait=true를 전달하면 한 번의 호출로 전체 결과를 받습니다. 폴링도 다른 요청과 마찬가지로 한도에 포함됩니다.

룩투북 제한

검색은 예약 실적에 따라서도 배분됩니다. 최근 집계 기간(기본 7일)의 하루마다 무료 검색 허용량이 주어지고, 그 기간에 예약이 1건 생길 때마다 cap만큼의 검색이 추가됩니다 — cap은 계정별로 합의된 예약당 검색 수로, 개발자 포털에 표시됩니다. 폴링, 가격 확인, 운임 규정, 콘텐츠 조회는 포함되지 않으며, 항공 및 호텔 검색 호출만 계산됩니다.

허용량을 모두 사용하면 검색은 429 look_to_book_exceeded를 반환하며, Retry-After 헤더는 가장 오래된 날이 집계 기간에서 빠지는 다음 UTC 자정을 가리킵니다. 예약이 생기면 허용량이 즉시 다시 열립니다. 개발자 포털의 룩투북 카드에서 실시간 카운터, 한도, 남은 양을 확인할 수 있습니다. 연동 특성상 예약보다 검색이 훨씬 많은 것이 정상이라면, 거부된 요청을 재시도하지 말고 한도 상향을 요청하세요.

멱등성

금액이나 재고를 확정하는 엔드포인트 — 주문 또는 예약 생성, 발권, 취소 — 에는 Idempotency-Key 헤더가 필요합니다(최대 128자의 고유 문자열, UUID 권장). 같은 키로 재시도하면 중복 생성 대신 원래 응답이 반환되며, 재사용한 키로 다른 본문을 보내면 409가 반환됩니다.

버전 관리

버전은 경로에 포함됩니다(/v1). 추가적인 변경 — 새로운 선택 필드, 새로운 enum 값, 새로운 엔드포인트 — 은 버전 변경 없이 배포되므로, 방어적으로 파싱하고 알 수 없는 필드는 무시하세요. 호환성을 깨는 변경에는 마이그레이션 기간과 함께 새 메이저 버전이 부여되며, 변경 로그 가이드에 모든 변경 사항이 기록됩니다.