채널 매니저 추가하기

이 가이드는 채널 매니저 및 PMS 개발자가 Wink와 통합하는 전체 과정을 안내합니다 — 계정 생성부터 인벤토리 매핑, 첫 번째 종단 간 테스트 실행까지.

환경

채널 매니저(Integrations) API는 두 가지 환경에서 제공됩니다. 모든 개발 및 인증은 스테이징 환경에서 진행하고, 실제 운영 시점에만 프로덕션 환경으로 전환하세요.

환경	기본 URL
프로덕션	https://integrations.wink.travel
스테이징	https://staging-integrations.wink.travel

API 참조

채널 매니저 API는 기존 호스피탈리티 시스템과의 호환성을 위해 OTA 프로토콜 표준(SOAP/XML)을 따릅니다. 파트너 엔드포인트 문서를 먼저 검토하세요:

채널 매니저 API — 파트너 엔드포인트

통합 단계

Wink 사용자 계정 생성

staging-app.wink.travel에서 가입하세요. 아래 모든 단계는 스테이징 환경에서 진행하며, 실제 운영 전 프로덕션 환경에서 전체 과정을 반복합니다.
제휴사 / 채널 매니저 계정 생성

새 사용자 계정 아래에서 계정을 생성하고 제휴사 / 채널 매니저 계정 유형을 선택하세요. 이 계정이 통합 인증에 사용됩니다.
애플리케이션 등록 및 첫 토큰 발급

Application를 생성하고 2단계에서 만든 채널 매니저 계정에 연결하세요. 클라이언트 유형으로 MACHINE_2_MACHINE을 선택합니다 — 이는 서버 간 통합으로, 리디렉션할 최종 사용자가 없습니다. Client ID와 Secret Key를 즉시 복사하세요; 비밀 키는 한 번만 표시되며 다시 조회할 수 없습니다.

애플리케이션은 이 가이드의 모든 호출에 Authorization: Bearer <access_token>로 전달되는 베어러 토큰을 발급합니다. client_credentials 그랜트를 사용해 https://staging-iam.wink.travel/oauth2/token에서 integrations.read integrations.write 범위를 요청하여 자격 증명을 토큰으로 교환하세요. 이 작업을 먼저 완료해야 합니다 — 토큰 없이는 계정 식별자 조회나 채널 매니저 엔드포인트 접근이 불가능합니다. 전체 흐름, 프로덕션 호스트, 범위 목록은 인증을 참조하세요.
호텔 계정 생성

동일한 사용자 아래에서 두 번째 계정을 생성하고 호텔 계정 유형을 선택하세요. 실제 호텔과 무관하게 테스트용 부동산을 사용할 수 있습니다.
두 계정 모두 승인 확인

승인되지 않은 계정은 사용할 수 없습니다: 승인되지 않은 채널 매니저 계정은 호텔의 채널 매니저 목록에 나타나지 않으며, 승인되지 않은 호텔은 API에서 반환되지 않습니다.
- 스테이징 — 승인이 자동으로 처리됩니다. 계정 생성 즉시 사용 가능합니다.
- 프로덕션 — 승인이 수동으로 이루어집니다. Wink 통합 담당자에게 두 계정 이름과 해당 사용자를 알려 승인 확인을 받은 후 진행하세요.
두 계정 연결

호텔 계정으로 로그인 후 Extranet → Distribution → Channel Manager로 이동하세요. 목록에서 채널 매니저 계정을 선택하면 부동산과 통합이 연결됩니다. 목록에 계정이 없으면 아직 승인되지 않은 상태입니다; 5단계를 참고하세요.
기본 객실 유형 및 요금제 생성

호텔 계정 내에서 최소 하나의 객실 유형과 요금제를 생성하세요. 통합이 요금 및 가용성을 푸시하거나 예약을 조회하기 전에 필요합니다.
매핑 및 테스트

자체 시스템에서 API가 반환하는 객실 유형 및 요금제 식별자를 매핑하세요. 요금 업데이트와 가용성 업데이트를 푸시한 후 테스트 예약을 진행하고 예약 조회 엔드포인트가 올바르게 반환하는지 확인하세요.

계정 식별자 찾기

모든 채널 매니저 API 경로는 귀하의 계정에 범위가 지정됩니다:

/api/managing-entity/{managingEntityIdentifier}/channel-manager/...

{managingEntityIdentifier}는 귀하의 채널 매니저 계정의 계정 ID(UUID)입니다 — 호텔의 ID가 아닙니다. 사용자가 소유한 모든 계정의 ID와 현재 상태는 플랫폼 API에서 조회할 수 있습니다:

curl -s -X GET \
  "https://staging-api.wink.travel/api/managing-entity/list" \
  -H "Authorization: Bearer <access_token>" \
  -H "Wink-Version: 2.0" \
  -H "Accept: application/json"

응답은 귀하가 소유한 계정 배열입니다:

[
  {
    "id": "3f1c8e42-7b90-4d55-a1e2-6c8d09b4f731",
    "type": "CHANNEL_MANAGER",
    "name": "Your Channel Manager",
    "status": "ACTIVE"
  },
  {
    "id": "d5b8a3c2-9e6f-4a1b-8d34-7c2e1f0a5b69",
    "type": "HOTEL",
    "name": "Your Test Property",
    "urlName": "your-test-property",
    "status": "ACTIVE"
  }
]

채널 매니저 항목의 id가 **{managingEntityIdentifier}**입니다.
HOTEL 항목의 id가 **{propertyIdentifier}**입니다.
status는 각 계정이 승인되었는지 확인하는 데 사용합니다 — 프로덕션에서 특히 중요하며 승인이 수동입니다. 호텔은 예약 가능하거나 채널 매니저 API에 표시되려면 ACTIVE여야 합니다. 채널 매니저 계정은 인증 완료 전까지 PENDING_APPROVAL 상태를 유지하는데, 이는 정상이며 개발에 지장을 주지 않습니다.

인증

인증은 귀하의 통합이 인벤토리를 올바르게 매핑하고, 요금 및 가용성을 푸시하며, 예약을 종단 간으로 수신하는지 증명하는 과정입니다. 자체 서비스 방식으로 설계되어, 모든 단계를 자체 시스템에서 진행하고 최종적으로 증빙 자료를 제출합니다. Wink가 검토 후 합격하면 제휴사 / 채널 매니저 계정을 PENDING_APPROVAL에서 ACTIVE로 전환합니다.

인증은 전적으로 스테이징 환경(https://staging-integrations.wink.travel)에서 진행되며, 이 섹션에서는 프로덕션을 다루지 않습니다.

증명할 내용

인증. OAuth2 클라이언트가 액세스 토큰을 얻고 제휴사 / 채널 매니저 계정에 대해 /ping 엔드포인트를 성공적으로 호출할 수 있어야 합니다.
인벤토리 매핑. 연결된 호텔 목록을 조회하고, 구성한 마스터 요금(객실 유형 × 요금제)을 가져와 시스템이 타겟팅할 masterRateIdentifier를 정확히 식별할 수 있어야 합니다.
요금 및 가용성 푸시. 인증 주간 7일 모두를 독립적으로 업데이트할 수 있어야 합니다 — 각 날짜마다 금액, 수량, 도착 시 마감/출발 시 마감 플래그, 최소/최대 숙박 기간이 다르게 조합되어야 하며, Wink에서 정확한 값을 다시 읽을 수 있어야 합니다.
예약 조회. 테스트 부동산에 대해 생성된 실제 스테이징 예약을 조회하고, 자체 PMS/CM UI에 객실 체류, 투숙객, 총액이 올바르게 표시되는지 확인한 후, Wink가 예약을 취소 처리하면 취소 상태가 반영되는지 확인해야 합니다.

사전 준비 사항

인증을 시작하기 전에 통합 단계의 1~7단계를 완료하여 다음을 준비하세요:

스테이징 환경의 Wink 사용자로서 제휴사 / 채널 매니저 계정과 연결된 호텔 계정(Extranet → Distribution → Channel Manager)이 있어야 합니다. 스테이징 계정은 자동 승인됩니다.
호텔 계정 내에 최소 하나의 객실 유형과 하나의 요금제가 생성되어 있어야 하며, 호텔이 https://staging-book.wink.travel/hotel/<your-slug>에서 예약 가능하도록 게시되어야 합니다.
제휴사 / 채널 매니저 계정 아래에 등록된 애플리케이션이 있어야 하며, Client ID, Secret Key, integrations.read integrations.write 범위를 포함해야 합니다 (자세한 내용은 인증 참조).
제휴사 / 채널 매니저 계정의 **managingEntityIdentifier**와 호텔 계정의 propertyIdentifier (둘 다 UUID, 계정 식별자 찾기 참조)를 확보해야 합니다.

공통 요청 규칙

이 섹션의 모든 요청은 다음 헤더를 사용합니다:

Authorization: Bearer <access_token>
Wink-Version: 2.0
Accept: application/json

<access_token>은 https://staging-iam.wink.travel/oauth2/token에서 client_credentials 그랜트를 통해 발급받은 토큰입니다 — 인증 참조.
Wink-Version 헤더는 필수이며, 누락 시 v2 JSON API로 라우팅되지 않습니다.
PUT 요청에 본문이 포함될 경우 Content-Type: application/json이 추가됩니다.

아래 예제에서 플레이스홀더는 사전 준비 사항에서 수집한 값에 매핑됩니다:

플레이스홀더	의미
`{managingEntityIdentifier}`	제휴사 / 채널 매니저 계정 ID(UUID) — 계정 식별자 찾기 참조.
`{propertyIdentifier}`	채널 매니저 계정에 연결된 호텔 계정(부동산) ID.
`{masterRateIdentifier}`	인증할 마스터 요금(객실 유형 × 요금제) 식별자.
`{bookingIdentifier}`	예약 목록 호출에서 반환된 스테이징 예약 ID.

단계 A — Ping

자격 증명이 예상한 제휴사 / 채널 매니저 계정으로 해석되는지 확인합니다.

curl -s -X GET \
  "https://staging-integrations.wink.travel/api/managing-entity/{managingEntityIdentifier}/channel-manager/ping" \
  -H "Authorization: Bearer <access_token>" \
  -H "Wink-Version: 2.0" \
  -H "Accept: application/json"

예상 응답:

{
  "apiVersion": "2.0",
  "name": "Your Channel Manager Account Name",
  "status": "PENDING_APPROVAL"
}

name이 일치하는 200 응답은 인증 및 계정 해석이 올바르다는 신호입니다. status는 Wink가 인증을 완료할 때까지 PENDING_APPROVAL로 표시됩니다.

단계 B — 부동산 목록 조회

계정에 연결된 호텔 목록을 페이지 단위로 조회하고 테스트 부동산이 포함되어 있는지 확인합니다.

curl -s -X GET \
  "https://staging-integrations.wink.travel/api/managing-entity/{managingEntityIdentifier}/channel-manager/property/list?page=0&size=25" \
  -H "Authorization: Bearer <access_token>" \
  -H "Wink-Version: 2.0" \
  -H "Accept: application/json"

응답은 ChannelManagerProperty 항목의 Spring Page입니다. {propertyIdentifier}와 일치하는 항목을 찾아 currencyCode를 기록하세요 — 단계 D에서 요금 업데이트 해석에 필요합니다.

단계 C — 마스터 요금 조회

부동산과 게시하는 모든 마스터 요금(객실 유형 × 요금제 조합)을 조회합니다. 인증할 요금을 선택하고 identifier를 {masterRateIdentifier}로 기록하세요.

curl -s -X GET \
  "https://staging-integrations.wink.travel/api/managing-entity/{managingEntityIdentifier}/channel-manager/property/{propertyIdentifier}" \
  -H "Authorization: Bearer <access_token>" \
  -H "Wink-Version: 2.0" \
  -H "Accept: application/json"

응답은 PropertyWithRoomRateList로, property 블록과 PropertyRoomRate 항목 배열인 rooms를 포함합니다. 각 항목은 객실 유형, 요금제, 점유 한도, 기본 요금, 일일 요금 푸시 시 유지할 요금 수정자를 노출합니다.

단계 D — 인증 주간 로드

인증 시작 월 다음 달의 첫 7일을 포함하는 7일 요금 달력을 로드합니다. 예를 들어 8월 21일에 인증을 시작하면 9월 1일부터 7일까지를 대상으로 합니다.

각 날짜마다 startDate == endDate인 7개의 별도 PUT 호출을 보냅니다. 각 날짜는 금액, 수량, 제한 플래그, 숙박 기간 제한이 다르게 조합되어 모든 쓰기 가능한 필드를 최소 한 번씩 테스트합니다. 값은 부동산 통화 단위(단계 B에서 기록)로 지정하며, currencyCode를 생략하면 기본값이 올바르게 적용됩니다.

날짜	금액	수량	도착 시 마감	출발 시 마감	최소 숙박 기간	최대 숙박 기간	증명 내용
1	100.00	5	false	false	1	30	기준일
2	125.00	4	false	false	1	14	금액 + 수량 + 최대 숙박 기간 변경
3	150.00	3	true	false	1	30	도착 시 마감 플래그 변경
4	175.00	2	false	true	2	7	출발 시 마감 플래그 변경 + 숙박 기간 제한 강화
5	200.00	0	false	false	1	30	매진 수량
6	225.00	5	false	false	3	5	제한된 숙박 기간
7	250.00	1	false	false	1	30	마지막 객실 가용성

1일차 요청 본문 예시는 다음과 같습니다. 2~7일차는 startDate / endDate / 값만 행에 맞게 조정해 반복하세요.

curl -s -X PUT \
  "https://staging-integrations.wink.travel/api/managing-entity/{managingEntityIdentifier}/channel-manager/property/{propertyIdentifier}/master-rate/{masterRateIdentifier}" \
  -H "Authorization: Bearer <access_token>" \
  -H "Wink-Version: 2.0" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
        "startDate": "2026-09-01",
        "endDate":   "2026-09-01",
        "amount":    100.00,
        "master":    true,
        "closedOnArrival":   false,
        "closedOnDeparture": false,
        "quantity":          5,
        "minLengthOfStay":   1,
        "maxLengthOfStay":   30
      }'

각 PUT 호출은 전송한 범위에 대한 업데이트된 PropertyRate 항목 배열(단일 날짜일 경우 한 항목)을 200 응답으로 반환합니다. 이 응답을 캡처하여 증빙 자료에 포함하세요.

단계 E — 인증 주간 읽기

한 번의 호출로 7일 전체를 조회하고, 각 날짜의 저장된 값이 단계 D에서 보낸 행과 일치하는지 확인하세요 — 불리언 플래그와 숙박 기간 제한 포함.

curl -s -X GET \
  "https://staging-integrations.wink.travel/api/managing-entity/{managingEntityIdentifier}/channel-manager/property/{propertyIdentifier}/master-rate/{masterRateIdentifier}?startDate=2026-09-01&endDate=2026-09-07" \
  -H "Authorization: Bearer <access_token>" \
  -H "Wink-Version: 2.0" \
  -H "Accept: application/json"

응답은 PropertyRoomRateWithRateList입니다. rates 배열에 7개의 항목이 있어야 하며, 각 항목은 amount, quantity, closedOnArrival, closedOnDeparture, minLengthOfStay, maxLengthOfStay가 일치해야 합니다. 불일치가 있으면 단계 D의 해당 PUT 호출이 예상대로 처리되지 않은 것이므로 수정 후 재검증하세요.

단계 F — 테스트 예약 생성

브라우저에서 다음 URL을 열고 <your-slug>를 사전 준비 단계에서 게시한 호텔 계정의 슬러그로 교체하세요:

https://staging-book.wink.travel/hotel/<your-slug>

인증 주간 내에 완전히 포함되는 도착 및 출발 날짜를 선택하고, 인증한 객실 유형 + 요금제 조합을 선택하여 예약을 완료하세요. 스테이징은 테스트 결제 경로를 사용하므로 실제 카드가 청구되지 않습니다.

확인 페이지가 표시되면, 투숙객에게 보여지는 예약 코드(WNKxxxxx 형식)를 기록하세요.

단계 G — 예약 조회

예약 생성 시점을 포함하는 기간 내에 테스트 부동산에 생성된 모든 예약을 조회합니다.

curl -s -X GET \
  "https://staging-integrations.wink.travel/api/managing-entity/{managingEntityIdentifier}/channel-manager/property/{propertyIdentifier}/booking/list?startDate=2026-09-01T00:00:00&endDate=2026-09-08T00:00:00" \
  -H "Authorization: Bearer <access_token>" \
  -H "Wink-Version: 2.0" \
  -H "Accept: application/json"

단계 F에서 기록한 bookingCode와 일치하는 항목을 찾아 bookingIdentifier를 기록하세요. 그런 다음 해당 단일 예약을 조회합니다:

curl -s -X GET \
  "https://staging-integrations.wink.travel/api/managing-entity/{managingEntityIdentifier}/channel-manager/property/{propertyIdentifier}/booking/{bookingIdentifier}" \
  -H "Authorization: Bearer <access_token>" \
  -H "Wink-Version: 2.0" \
  -H "Accept: application/json"

응답은 PropertyBooking입니다. 이를 자체 PMS / 채널 매니저 UI에 임포트하여 다음 항목이 운영자에게 올바르게 표시되는지 확인하세요:

bookingCode, bookingIdentifier, createdDate
투숙객: firstName, lastName, email
totalAmount + currencyCode (호텔이 객실 전체에서 받는 순액)
paymentMethodType, paymentMethodStatus, salesChannelName
roomStays 내 모든 항목: guestRoomName, ratePlanName, adults, children, startDate, endDate, 객실별 amount

자체 UI에 표시된 예약 화면을 스크린샷으로 저장하세요 — 이 스크린샷이 증빙 자료 중 하나입니다.

단계 H — 예약 취소 및 확인

Wink 팀에 인증 예약 취소를 요청하거나, 권한이 있다면 호텔 계정의 Extranet에서 직접 취소하세요. 그런 다음 단계 G의 호출로 동일 예약을 다시 조회합니다.

응답에 다음이 표시되는지 확인하세요:

cancelled: true
채워진 cancelDate 타임스탬프
취소 상태를 반영하는 paymentMethodStatus (CANCELLED, PARTIALLY_REFUNDED, FULLY_REFUNDED 등 환불 정책에 따라 다름)

업데이트된 예약을 자체 UI에 임포트하여 운영자가 취소 상태, 취소 시각, 환불 표시를 확인할 수 있는지 검증하세요. 취소된 예약 화면도 스크린샷으로 저장하세요. 이 스크린샷이 최종 증빙 자료입니다.

단계 I — 증빙 자료 제출

다음 항목을 하나의 압축 파일(.zip)로 묶어 이름을 wink-cert-<your-channel-manager-name>-<yyyy-mm-dd>.zip으로 지정하세요:

API 기록. 단계 A부터 H까지 모든 요청에 대해 HTTP 요청(메서드, URL, 요청 헤더 중 Authorization 값은 가리고, PUT 요청의 JSON 본문 포함)과 HTTP 응답(상태 코드, 응답 헤더, JSON 본문)을 캡처하세요. 각 요청/응답 쌍은 해당 단계 이름으로 명확히 구분하세요(step-a-ping.json, step-d-day-3-put.json, step-g-list-bookings.json 등). 일반 텍스트 .http 파일이나 단일 .har 내보내기 모두 허용됩니다.
UI 스크린샷: 활성 예약. 단계 G에서 자체 PMS / 채널 매니저 UI에 표시된 인증 예약 화면으로, 투숙객, 날짜, 객실 유형, 요금제, 총액이 명확히 보이는 스크린샷.
UI 스크린샷: 취소된 예약. 단계 H에서 취소 후 자체 UI에 표시된 동일 예약 화면으로, 취소 상태와 타임스탬프가 명확히 보이는 스크린샷.
인증 요약. 압축 파일 내 README.md에 다음을 기재:
- 채널 매니저 / PMS 이름 및 버전.
- 사용한 managingEntityIdentifier, propertyIdentifier, masterRateIdentifier, bookingIdentifier.
- 스테이징 호텔 슬러그 (https://staging-book.wink.travel/hotel/<your-slug>의 <your-slug>).
- 인증 주간 날짜 범위 (1일차 → 7일차, ISO-8601 형식).
- 인증을 수행한 엔지니어 이름과 이메일.

압축 파일을 Wink 통합 담당자에게 전송하세요. Wink가 검토 후 불일치 사항을 확인하고, 합격 시 제휴사 / 채널 매니저 계정 상태를 PENDING_APPROVAL에서 ACTIVE로 전환합니다. 이후 통합은 프로덕션 온보딩 대상이 됩니다.

웹훅 알림

채널 매니저 웹훅 이벤트를 구독하여 실시간 알림을 받을 수 있습니다:

channel-manager.update.rate — 요금 업데이트 수신.
channel-manager.update.availability — 가용성 업데이트 수신.
channel-manager.update — 일반 채널 매니저 업데이트.

자세한 내용은 웹훅 이벤트 카탈로그를 참조하세요.

추가 자료

채널 매니저 API — 전체 API 엔드포인트 문서.
요금 제공자 — Extranet에서 요금 제공자 관리.
웹훅 이벤트 카탈로그 — 구독 가능한 모든 이벤트.
Wink에서 개발하기 — 개발자를 위한 플랫폼 개요.