コンテンツにスキップ

チャネルマネージャーの追加

このガイドでは、チャネルマネージャーおよびPMS開発者がWinkとの統合プロセス全体を、アカウント作成から在庫マッピング、最初のエンドツーエンドテストの実行まで順を追って説明します。

チャネルマネージャー(Integrations)APIは2つの環境で利用可能です。すべての開発および認証はステージング環境で行い、本番環境は本番稼働時にのみ切り替えてください。

環境ベースURL
本番https://integrations.wink.travel
ステージングhttps://staging-integrations.wink.travel

チャネルマネージャーAPIはOTAプロトコル標準(SOAP/XML)に準拠しており、既存のホスピタリティシステムとの互換性があります。まずはパートナーエンドポイントのドキュメントを確認してください:

チャネルマネージャーAPI — パートナーエンドポイント

  1. Winkユーザーアカウントの作成

    staging-app.wink.travelでサインアップしてください。以下のすべての手順はステージング環境で行います。本番稼働前に本番環境でも同じプロセスを繰り返します。

  2. アフィリエイト / チャネルマネージャーアカウントの作成

    新規ユーザーの下でアカウントを作成し、Affiliate / Channel Managerアカウントタイプを選択してください。このアカウントが統合の認証に使用されます。

  3. アプリケーションの登録と最初のトークン発行

    Applicationを作成し、ステップ2のチャネルマネージャーアカウントに紐付けます。クライアントタイプはMACHINE_2_MACHINEを選択してください。これはエンドユーザーのリダイレクトを伴わないサーバー間統合です。Client IDとSecret Keyはすぐにコピーしてください。シークレットキーは一度しか表示されず、再取得できません。

    このアプリケーションがBearerトークンを発行し、本ガイドのすべての呼び出しでAuthorization: Bearer <access_token>として使用されます。client_credentialsグラントを使い、https://staging-iam.wink.travel/oauth2/tokenに対してintegrations.read integrations.writeスコープをリクエストしてトークンを取得してください。これを行わないとアカウント識別子の取得やチャネルマネージャーのエンドポイントへのアクセスができません。Authenticationでフロー全体、本番ホスト、スコープカタログを確認してください。

  4. ホテルアカウントの作成

    同じユーザーの下で2つ目のアカウントを作成し、Hotelアカウントタイプを選択してください。これは実際のホテルを使わずにテスト用の物件として利用できます。

  5. 両アカウントの承認確認

    承認されていないアカウントは使用できません。承認されていないチャネルマネージャーアカウントはホテルのチャネルマネージャーリストに表示されず、承認されていないホテルはAPIから返されません。

    • ステージング — 承認は自動です。作成直後から両アカウントは使用可能で、申請は不要です。
    • 本番 — 承認は手動です。Winkの統合担当者に両アカウント名とそれらが属するユーザー名を送信し、承認完了の連絡を待ってください。
  6. 2つのアカウントを接続

    ホテルアカウントにログインし、Channels → Channel managerに移動します。リストからチャネルマネージャーアカウントを選択し、物件と統合をリンクします。リストにアカウントがない場合は承認されていません。ステップ5を参照してください。

  7. 基本的な部屋タイプと料金プランの作成

    ホテルアカウント内で少なくとも1つの部屋タイプと1つの料金プランを作成してください。これらは統合が料金や空室状況をプッシュしたり、予約を取得したりする前提条件です。

  8. マッピングとテスト

    ご自身のシステムでAPIから返された部屋タイプと料金プランの識別子をマッピングします。料金更新と空室更新をプッシュし、テスト予約を行い、予約取得エンドポイントが正しく返すことを確認してください。

すべてのチャネルマネージャーAPIパスはご自身のアカウントにスコープされています:

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

{managingEntityIdentifier}はチャネルマネージャーアカウントのID(UUID)であり、ホテルのIDではありません。ユーザーが所有する他のすべてのアカウントのIDと現在のステータスとともに、Platform 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は各アカウントの承認状況を確認するために使います。特に本番環境で重要です。ホテルはACTIVEでなければ予約可能でもAPIに表示されません。チャネルマネージャーアカウントは認証を通過するまでPENDING_APPROVALのままですが、これは開発の妨げにはなりません。

認証は、統合が正しく在庫をマッピングし、料金と空室状況をプッシュし、予約をエンドツーエンドで受信できることを証明し、Winkが確認するプロセスです。セルフサービスを想定しており、ご自身のシステムからすべてのステップを実行し、最後に証拠のバンドルを提出します。Winkがレビューし合格すると、アフィリエイト / チャネルマネージャーアカウントのステータスがPENDING_APPROVALからACTIVEに変更されます。

認証はすべてステージング環境(https://staging-integrations.wink.travel)で行います。このセクションの内容は本番環境には影響しません。

  1. 認証。 OAuth2クライアントがアクセストークンを取得し、アフィリエイト / チャネルマネージャーアカウントに対して/pingエンドポイントを正常に呼び出せること。

  2. 在庫マッピング。 アカウントに接続されたホテルを一覧取得し、設定したマスターレート(部屋タイプ×料金プラン)を取得し、システムが対象とするmasterRateIdentifierを正しく特定できること。

  3. 料金・空室状況のプッシュ。 認証週の7日間すべてを独立して更新できること。各日で金額、数量、到着時クローズ/出発時クローズフラグ、最小/最大宿泊日数の異なる組み合わせを設定し、Winkから正確に読み戻せること。

  4. 予約の取得。 テスト物件に対してステージングで作成された実際の予約を取得し、自身のPMS/CM UIに正しい部屋滞在、ゲスト、合計金額で表示し、Winkが予約をキャンセル済みにマークした後にキャンセルを反映できること。

認証を開始する前に、統合手順のステップ1〜7を完了し、以下を準備してください:

  • ステージングのWinkユーザーにAffiliate / Channel Managerアカウントと、それに接続されたHotelアカウント(Channels → Channel manager)があること。ステージングアカウントは自動承認されるため申請不要です。
  • ホテルアカウント内に少なくとも1つの部屋タイプと1つの料金プランが作成されていること。ホテルを公開し、https://staging-book.wink.travel/hotel/<your-slug>で予約可能にしてください。
  • アフィリエイト / チャネルマネージャーアカウントに登録されたアプリケーションがあり、Client ID、Secret Key、およびintegrations.read integrations.writeスコープを持っていること(Authentication参照)。
  • アフィリエイト / チャネルマネージャーアカウントの**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グラントから取得します(Authentication参照)。
  • Wink-Versionヘッダーは必須です。省略するとv2 JSON APIにルーティングされません。
  • PUTリクエストでボディを送る場合はContent-Type: application/jsonが追加されます。

以下の例では、プレースホルダーは前提条件で取得した値に対応しています:

プレースホルダー意味
{managingEntityIdentifier}アフィリエイト / チャネルマネージャーアカウントID(UUID)— アカウント識別子の確認参照
{propertyIdentifier}チャネルマネージャーアカウントに接続されたホテルアカウントID
{masterRateIdentifier}認証対象のマスターレート(部屋タイプ×料金プラン)識別子
{bookingIdentifier}予約一覧呼び出しで返されたステージング予約ID

認証情報が期待するアフィリエイト / チャネルマネージャーアカウントに解決されることを確認します。

ターミナルウィンドウ
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のままです。

アカウントに紐づくホテルのページネーションされた一覧を取得し、テスト物件が存在することを確認します。

ターミナルウィンドウ
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です。identifierが{propertyIdentifier}に一致するエントリを探し、そのcurrencyCodeを記録してください。これはステップDの料金更新の解釈に必要です。

ステップC — マスターレート取得

Section titled “ステップ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 — 認証週の読み込み

Section titled “ステップD — 認証週の読み込み”

認証開始月の翌月の最初の7日間の7日間料金カレンダーを読み込みます。例えば、8月21日に認証を開始した場合は9月1日から9月7日までを対象とします。

7回の個別PUT呼び出しを行います。各日でstartDate == endDateとなります。各日は金額、数量、制限フラグ、宿泊日数制限の異なる組み合わせを意図的に設定し、すべての書き込み可能なフィールドを少なくとも1回は操作します。値は物件の通貨(ステップBで記録)で指定してください。currencyCodeは省略可能で、正しくデフォルトされます。

日付金額数量closedOnArrivalclosedOnDepartureminLengthOfStaymaxLengthOfStay証明内容
1100.005falsefalse130基準日
2125.004falsefalse114金額+数量+maxLengthOfStay変更
3150.003truefalse130closedOnArrivalの切り替え
4175.002falsetrue27closedOnDepartureの切り替え+宿泊日数制限の厳格化
5200.000falsefalse130売り切れ数量
6225.005falsefalse35制限の厳しい宿泊日数ウィンドウ
7250.001falsefalse130最後の1部屋の空室

Day 1のリクエストボディ例は以下の通りです。Day 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で返します(startDate == endDateの場合は1件)。このレスポンスを保存してください。証拠の一部となります。

ステップE — 認証週の読み戻し

Section titled “ステップE — 認証週の読み戻し”

1回の呼び出しで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で設定した通りでなければなりません。どれか1つでも不一致があれば、ステップDの対応するPUTが正しく反映されていないことを意味します。修正して再検証してください。

ステップF — テスト予約の作成

Section titled “ステップF — テスト予約の作成”

ブラウザで以下のURLを開き、<your-slug>を前提条件で公開したホテルアカウントのスラッグに置き換えてください:

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

認証週内に完全に収まる到着日と出発日を選択し、認証した部屋タイプ+料金プランの組み合わせを選んで予約を完了してください。ステージング環境はテスト決済経路を使用しており、実際のカードは課金されません。

確認ページが表示されたら、ゲストに表示される予約コード(形式はWNKxxxxx)を記録してください。

予約タイムスタンプを含む期間内に作成されたテスト物件のすべての予約を取得します。

ターミナルウィンドウ
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に表示された予約のスクリーンショットを撮影してください。これは証拠資料の1つです。

ステップH — 予約のキャンセルと検証

Section titled “ステップH — 予約のキャンセルと検証”

Winkチームに認証予約のキャンセルを依頼するか、ホテルアカウントのエクストラネットで権限があれば自身でキャンセルしてください。その後、ステップGの呼び出しで同じ予約を再取得します。

レスポンスに以下が含まれていることを確認してください:

  • cancelled: true
  • cancelDateタイムスタンプが設定されている
  • 返金ポリシーに応じてpaymentMethodStatusがCANCELLED、PARTIALLY_REFUNDED、またはFULLY_REFUNDEDとなっている

更新された予約を自身のUIに取り込み、キャンセル状態がオペレーターに見えることを確認してください。ステータス、キャンセル日時、返金インジケーターなどが表示されていることを確認し、キャンセル済み予約のスクリーンショットを撮影してください。これが最終の証拠資料です。

ステップI — 証拠バンドルの提出

Section titled “ステップI — 証拠バンドルの提出”

以下を1つのアーカイブ(.zip)にまとめ、ファイル名を wink-cert-<your-channel-manager-name>-<yyyy-mm-dd>.zipとしてください:

  1. 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エクスポートも許容されます。

  2. UIスクリーンショット:アクティブ予約。 ステップGで取得した認証予約を自身のPMS / チャネルマネージャーUIに表示したスクリーンショット。ゲスト、日付、部屋タイプ、料金プラン、合計が明瞭に読み取れること。

  3. UIスクリーンショット:キャンセル済み予約。 ステップHでキャンセル後の同じ予約を自身のUIに表示したスクリーンショット。キャンセル状態とタイムスタンプが明瞭に読み取れること。

  4. 認証概要。 アーカイブ内に短いREADME.mdを含め、以下を記載してください:

    • チャネルマネージャー / PMSの名称とバージョン
    • 使用したmanagingEntityIdentifier、propertyIdentifier、masterRateIdentifier、bookingIdentifier
    • ステージングホテルのスラッグ(https://staging-book.wink.travel/hotel/<your-slug>の<your-slug>部分)
    • 認証週の日付範囲(Day 1 → Day 7、ISO-8601形式)
    • 認証を実施したエンジニアの氏名とメールアドレス

アーカイブをWinkの統合担当者に送付してください。Winkがレビューし、不一致があればフォローアップします。合格するとアフィリエイト / チャネルマネージャーアカウントのステータスがPENDING_APPROVALからACTIVEに切り替わり、本番環境へのオンボーディング資格が得られます。

チャネルマネージャーのWebhookイベントを購読してリアルタイム通知を受け取ることができます:

  • channel-manager.update.rate — 料金更新通知
  • channel-manager.update.availability — 空室更新通知
  • channel-manager.update — 一般的なチャネルマネージャー更新通知

詳細はWebhook Events Catalogを参照してください。