Channel API v2 가이드

HATEOAS 토큰 기반의 v2 API를 사용하여 숙소 검색부터 예약까지 완전한 흐름을 구현합니다.

Channel API v2 가이드

v2 API는 HATEOAS(Hypermedia as the Engine of Application State) 패턴을 채택한 새로운 Channel API입니다. 각 단계에서 발급된 토큰이 다음 단계로 연결되므로, 파라미터를 직접 조합하지 않고 응답에 포함된 링크를 따라가는 방식으로 예약 흐름을 구성합니다.

v1과의 주요 차이점

전체 엔드포인트 목록

예약 4단계 흐름

v2의 예약 흐름은 토큰으로 연결된 4단계로 구성됩니다.

Step 1: 가용성 검색

GET /api/channel/v2/properties/availability

날짜, 인원, 숙소 ID를 지정하여 가용 객실과 요금을 조회합니다.

쿼리 파라미터

occupancy 형식: EPS 호환 포맷을 사용합니다.

• "2" — 성인 2명
• "2-3,5" — 성인 2명, 어린이 3세·5세

응답 구조

[
  {
    "property_id": "12345",
    "status": "available",
    "rooms": [
      {
        "id": "a1b2c3d4",
        "room_name": "디럭스 더블룸",
        "rates": [
          {
            "id": "e5f6g7h8",
            "status": "available",
            "available_rooms": 5,
            "refundable": true,
            "occupancy_pricing": {
              "2": {
                "nightly": [
                  [
                    { "type": "base_rate", "currency": "KRW", "value": 150000 },
                    { "type": "tax_and_service_fee", "currency": "KRW", "value": 15000 }
                  ],
                  [
                    { "type": "base_rate", "currency": "KRW", "value": 150000 },
                    { "type": "tax_and_service_fee", "currency": "KRW", "value": 15000 }
                  ]
                ],
                "totals": {
                  "inclusive": {
                    "request_currency": { "currency": "KRW", "value": 330000 }
                  }
                }
              }
            },
            "bed_groups": {
              "37321": {
                "id": "37321",
                "description": "1 King Bed",
                "links": {
                  "price_check": {
                    "method": "GET",
                    "href": "/api/channel/v2/properties/12345/rooms/a1b2c3d4/rates/e5f6g7h8?token=eyJ...",
                    "expires": "2026-04-01T10:30:00.000Z"
                  }
                }
              }
            },
            "cancel_penalties": [],
            "amenities": {},
            "promotions": null,
            "deposits": []
          }
        ]
      }
    ]
  }
]

Step 2: 가격 확인 (Price Check)

GET /api/channel/v2/properties/{propertyId}/rooms/{roomId}/rates/{rateId}?token=

Step 1 응답의 price_check 링크를 그대로 호출합니다. URL을 직접 조합하지 말고 응답에 포함된 href를 사용하세요.

경로 파라미터

쿼리 파라미터

응답 구조

{
  "status": "matched",
  "occupancy_pricing": {
    "2": {
      "nightly": [...],
      "totals": {
        "inclusive": {
          "request_currency": { "currency": "KRW", "value": 330000 }
        }
      }
    }
  },
  "links": {
    "book": {
      "method": "POST",
      "href": "/api/channel/v2/bookings?token=eyJ...",
      "expires": "2026-04-01T11:00:00.000Z"
    }
  }
}

status 필드:

• "matched" — 가격이 Step 1과 동일합니다.
• "price_changed" — 가격이 변경되었습니다. occupancy_pricing에 최신 가격이 반영됩니다. 변경된 가격을 고객에게 안내한 후 계속 진행하세요.

Step 3: 예약 생성

POST /api/channel/v2/bookings?token=

Step 2에서 발급된 book 토큰과 투숙객 정보로 예약을 생성합니다.

쿼리 파라미터

요청 바디

응답 (201 Created)

{
  "itinerary_id": "ONDA1743500000000",
  "links": {
    "retrieve": {
      "method": "GET",
      "href": "/api/channel/v2/bookings/retrieve?token=eyJ...",
      "expires": "2027-04-01T10:00:00.000Z"
    },
    "cancel": {
      "method": "PUT",
      "href": "/api/channel/v2/bookings/cancel?token=eyJ...",
      "expires": "2027-04-01T10:00:00.000Z"
    }
  }
}

itinerary_id와 retrieve/cancel 링크를 안전하게 저장하세요. 예약 조회와 취소에 사용됩니다.

Step 4a: 예약 조회

GET /api/channel/v2/bookings/retrieve?token=

예약 생성 응답의 retrieve 링크를 호출하여 예약 상세를 조회합니다.

응답 구조

{
  "itinerary_id": "ONDA1743500000000",
  "status": "confirmed",
  "property_id": "12345",
  "checkin": "2026-04-01",
  "checkout": "2026-04-03",
  "request_currency": "KRW",
  "billable_currency": "KRW",
  "rooms": [
    {
      "room_id": "a1b2c3d4",
      "rate_id": "e5f6g7h8",
      "bed_group_id": "37321",
      "bed_group_description": "1 King Bed",
      "status": "confirmed",
      "refundable": true,
      "guest": {
        "given_name": "길동",
        "family_name": "홍"
      },
      "occupancy_pricing": { ... },
      "cancel_penalties": [],
      "cancel_refund": {
        "refundable": true,
        "refund_amount": 330000,
        "penalty_amount": 0,
        "currency": "KRW"
      }
    }
  ],
  "links": {
    "cancel": {
      "method": "PUT",
      "href": "/api/channel/v2/bookings/cancel?token=eyJ...",
      "expires": "2027-04-01T10:00:00.000Z"
    }
  }
}

Step 4b: 예약 취소

PUT /api/channel/v2/bookings/cancel?token=

예약 생성(또는 조회) 응답의 cancel 링크를 호출하여 예약을 취소합니다.

응답 구조

{
  "itinerary_id": "ONDA1743500000000",
  "status": "cancelled",
  "cancel_refund": {
    "refundable": true,
    "refund_amount": 330000,
    "penalty_amount": 0,
    "currency": "KRW"
  }
}

콘텐츠 API

숙소 목록 조회

GET /api/channel/v2/properties

연동된 숙소 목록을 페이지 토큰 기반으로 조회합니다.

쿼리 파라미터

curl -X GET "https://developers.tport.dev/api/channel/v2/properties?per_page=20" \
  -H "X-Api-Key: {your_api_key}"

숙소 상세 조회

GET /api/channel/v2/properties/{id}

특정 숙소의 상세 정보를 조회합니다. property_id는 문자열로 반환됩니다.

curl -X GET "https://developers.tport.dev/api/channel/v2/properties/12345" \
  -H "X-Api-Key: {your_api_key}"

객실 타입 목록 조회

GET /api/channel/v2/properties/{id}/roomtypes

특정 숙소의 객실 타입 목록을 조회합니다.

curl -X GET "https://developers.tport.dev/api/channel/v2/properties/12345/roomtypes" \
  -H "X-Api-Key: {your_api_key}"

토큰 오류 처리

v2 API는 단계 간 연결에 토큰을 사용합니다. 토큰 관련 오류 시나리오와 대응 방법입니다.

v1에서 v2로 마이그레이션

1. 예약 흐름 재구성

v1은 직접 파라미터를 조합하여 예약 API를 호출하는 방식이었습니다. v2는 응답의 링크(href)를 따라가는 방식입니다.

v1: GET /search/availability → GET /search/price-check → POST /bookings

v2: GET /properties/availability (price_check 링크 수령)
    → GET /properties/{pId}/rooms/{rId}/rates/{rateId}?token= (book 링크 수령)
    → POST /bookings?token= (retrieve/cancel 링크 수령)

2. property_id 형식 변경

v2에서 property_id는 항상 문자열로 반환됩니다. 숫자로 비교하거나 저장하지 마세요.

// v1 (숫자)
property.property_id === 12345

// v2 (문자열)
property.property_id === "12345"

3. 인원 파라미터 변경

v1의 adults/children 파라미터 대신 EPS 호환 occupancy 파라미터를 사용합니다.

v1: ?adults=2&children=1
v2: ?occupancy=2-5   (성인 2명, 어린이 5세 1명)

4. room/rate ID 변경

v2의 room ID와 rate ID는 내부 ID를 해싱한 값입니다. 직접 생성하거나 저장하지 말고 가용성 검색 응답에서 가져오세요.

다음 단계

• 실시간 검색 — v1 검색 API 개념 이해
• 예약 관리 — 예약 상태 라이프사이클
• 에러 처리 — 전체 에러 코드 목록
• API 레퍼런스 — 전체 API 명세