빠른 시작

HTA LMS API 문서 포털에 오신 것을 환영합니다. 이 문서는 공통 규약을 먼저 이해한 뒤 API를 호출하는 흐름으로 구성되어 있습니다.

문서 구성

섹션	설명
기본 가이드	인증, 요청/응답 규약, 에러 코드를 다룹니다. API 호출 전에 반드시 읽어 주십시오.
정책	버전 관리, 레이트리밋, 타임아웃 등 운영 정책을 설명합니다.
외부 API	제휴사 연동용 API입니다. 경로 접두사는 `/v1/api`입니다.
운영 가이드	폴링, 멱등성 키, 장애 대응 등 실제 운영에 필요한 내용을 다룹니다.

API 키

키 발급과 권한 범위를 먼저 확인합니다.

인증 헤더

서명/타임스탬프/nonce/요청 ID를 표준으로 맞춥니다.

요청·응답

포맷과 에러 해석 규칙을 먼저 고정합니다.

운영 보안

멱등성, 재시도, 제한 정책을 포함해 설계합니다.

안내API 연동 전 인증/에러 코드 문서를 먼저 확인하면 구현·운영 리스크를 줄일 수 있습니다.

접속 호스트

환경	호스트
운영(production)	`https://api.lms.ktxtourticket.co.kr`
개발(development)	`https://dev-api.lms.ktxtourticket.co.kr`

두 환경 모두 파트너별 IP 허용 목록이 적용됩니다. 온보딩 시 호출 서버의 고정 공인 IP를 등록해야 합니다. 개발 호스트에서는 허용 IP에 한해 /docs(Swagger UI)를 열람할 수 있습니다.

시작 전 준비

API를 호출하려면 다음 세 가지를 먼저 준비해야 합니다.

API 키/시크릿 발급 및 IP 등록 — 파트너 온보딩 담당자에게 요청합니다. 개발/운영 환경 각각 호출 IP 등록이 필요합니다.
인증 헤더 생성 로직 구현 — 모든 요청에 X-API-Key, X-Timestamp, X-Nonce, X-Signature 네 개의 헤더가 필요합니다. 타임스탬프는 초 단위(10자리) Unix 타임스탬프입니다. 자세한 생성 규칙은 인증 문서를 참고하십시오.
요청 추적 ID 설정 — X-Request-Id 헤더를 함께 보내면 디버깅과 로그 추적이 훨씬 수월해집니다. 미첨부 시 서버가 자동 생성하지만, 클라이언트에서 직접 관리하는 것을 권장합니다.

개발 환경에서 먼저 검증하십시오
개발 호스트(dev-api)에서 조회성 API(B2B 목록 조회, 시간표 조회, 티켓 조회) 중심으로 인증과 응답 처리를 먼저 검증한 뒤, 예약 생성·상태 변경 API를 붙이고 운영 전환하는 순서를 권장합니다.

3분 호출 예제 — 첫 실전 호출

인증 구현이 맞는지 확인하는 가장 좋은 첫 호출은 B2B 예약 목록 1건 조회입니다. 읽기 전용이라 안전하고, 서명 대상에 query parameter가 포함되므로 canonical query 구현까지 함께 검증됩니다.

GET /v1/api/b2b/reservations?db_type=seasiderailbike&page=1&size=1

# X-Signature는 아래 canonical string을 HMAC-SHA256(api_secret)으로 서명한 값입니다.
#   GET\n/v1/api/b2b/reservations\ndb_type=seasiderailbike&page=1&size=1\n{빈 body의 sha256 hex}\n{api_key}\n{timestamp}\n{nonce}
# 서명 코드 예시는 인증 문서의 Python/Node.js 샘플을 사용하십시오.

curl "https://dev-api.lms.ktxtourticket.co.kr/v1/api/b2b/reservations?db_type=seasiderailbike&page=1&size=1" \
  -H "X-API-Key: lms_xxxxxxxxxxxx" \
  -H "X-Timestamp: 1777992400" \
  -H "X-Nonce: 7cc44f76cf1d40d79952a4e7a49b1c03" \
  -H "X-Signature: <generated-signature>" \
  -H "X-Request-Id: req-20260704-0001"

X-Timestamp는 초 단위 10자리입니다(예: 1777992400). 밀리초(13자리)를 보내면 인증에 실패합니다.
X-Nonce는 요청마다 새로 생성해야 합니다. 재사용하면 replay로 차단됩니다.
GET 요청은 body가 없으므로 빈 bytes의 SHA256 hex를 body hash로 사용합니다.

성공 시 응답 (HTTP 200):

{
  "items": [
    {
      "order_no": "20260810-3",
      "date": "20260810",
      "time": "0930",
      "status": "A",
      "partner_code": "1234",
      "reserve_name": "홍**",
      "phone": "010****1234",
      "total_price": 44000,
      "misuYN": "N"
    }
  ],
  "totalCount": 1,
  "currentPage": 1,
  "pageSize": 1,
  "totalPages": 1
}

예약이 아직 없으면 items가 빈 배열로 반환됩니다. HTTP 200이면 인증 구현이 완료된 것입니다.

POST 호출 시 raw body bytes 주의
POST 요청은 서명에 사용한 body bytes와 전송하는 body bytes가 완전히 동일해야 합니다. Python이라면 json.dumps(..., ensure_ascii=False, separators=(",", ":"))로 직렬화한 bytes를 서명하고 requests.post(url, data=body_bytes, ...)로 그대로 전송하십시오. requests.post(json=...)는 사용하면 안 됩니다. 자세한 내용은 인증 문서를 참고하십시오.

연동 흐름

예약 연동은 다음 순서로 진행합니다.

1. 시간표 조회 (Timetable API)
   → 운행 시간과 잔여 수량을 확인합니다.

2. 티켓 조회 (Tickets API)
   → 상품 코드와 가격을 확인합니다.

3. 가용성 확인 (Availability API)
   → 원하는 날짜/시간/수량으로 예약 가능한지 확인합니다.

4. 예약 생성 (B2B API — POST /v1/api/b2b/reservations)
   → 확인된 정보로 예약을 생성합니다.

5. 상태 확인/변경 (B2B API)
   → 목록·상세 조회로 상태를 확인하고, 필요 시 상태를 변경합니다.

다음 단계

인증 — 서명 생성 방법과 인증 헤더 구성을 알아봅니다.
요청/응답 규약 — 공통 요청 형식과 응답 규칙을 이해합니다.
에러 코드 — 에러 코드별 원인과 대응 방법을 확인합니다.
B2B 운영 API — 예약 생성/조회/상태 변경 등 실전 연동 API를 확인합니다.

문서 구성​

접속 호스트​

시작 전 준비​

3분 호출 예제 — 첫 실전 호출​

연동 흐름​

다음 단계​