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

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

環境

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

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

APIリファレンス

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

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

統合手順

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

staging-app.wink.travelでサインアップします。以下のすべての手順はステージング環境で行い、本番稼働前に本番環境でも同じプロセスを繰り返します。
アフィリエイト / チャネルマネージャーアカウントの作成

新しいユーザーの下でアカウントを作成し、アフィリエイト / チャネルマネージャーアカウントタイプを選択します。このアカウントが統合の認証に使用されます。
アプリケーションの登録と最初のトークン発行

アプリケーションを作成し、ステップ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スコープをリクエストしてトークンを取得してください。これを行わないとアカウント識別子の取得やチャネルマネージャーのエンドポイントへのアクセスができません。認証でフロー全体、本番ホスト、スコープカタログを確認してください。
ホテルアカウントの作成

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

承認されていないアカウントは使用できません。承認されていないチャネルマネージャーアカウントはホテルのチャネルマネージャーリストに表示されず、承認されていないホテルはAPIから返されません。
- ステージング — 承認は自動です。作成直後から両アカウントは使用可能で、申請は不要です。
- 本番 — 承認は手動です。Winkの統合担当者に両アカウント名とそれらが属するユーザー名を送信し、承認完了の連絡を待ってください。
2つのアカウントを接続

ホテルアカウントにログインし、Extranet → Distribution → Channel Managerに移動します。リストからチャネルマネージャーアカウントを選択し、物件と統合をリンクします。リストにアカウントがない場合は承認されていません。ステップ5を参照してください。
基本的な部屋タイプと料金プランの作成

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

自社システムで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で各アカウントの承認状況を確認します。特に本番環境で重要です。ホテルはACTIVEでなければ予約可能でもAPIに表示されません。チャネルマネージャーアカウントは認証を通過するまでPENDING_APPROVALのままですが、これは開発の妨げにはなりません。

認証

認証は、統合が正しく在庫をマッピングし、料金・空室をプッシュし、予約をエンドツーエンドで受信できることをWinkに証明し、Winkが確認するプロセスです。セルフサービスを想定しており、すべてのステップを自社システムから実行し、最後に証拠バンドルを提出します。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）。ステージングアカウントは自動承認されるため申請不要。
ホテルアカウント内に少なくとも1つの部屋タイプと1つの料金プランを作成し、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"

レスポンスはSpringのPage形式でChannelManagerPropertyエントリの配列です。identifierが{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日から9月7日までを対象とします。

7回の個別PUT呼び出しを行い、各日でstartDate == endDateとします。各日は金額、数量、制限フラグ、宿泊日数制限の組み合わせを意図的に変え、すべての書き込み可能なフィールドを少なくとも1回は操作します。値は物件の通貨（ステップ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部屋の空室

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エントリの配列（startDate == endDateの場合は1件）を200で返します。このレスポンスは証拠の一部として保存してください。

ステップ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 — テスト予約の作成

ブラウザで以下の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 — 証拠バンドルの提出

以下を1つのアーカイブ（.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>）
- 認証週の日付範囲（Day 1 → Day 7、ISO-8601形式）
- 認証を実施したエンジニアの氏名とメールアドレス

アーカイブをWinkの統合担当者に送付してください。Winkは審査し、不一致があればフォローアップし、合格するとアフィリエイト / チャネルマネージャーアカウントのステータスをPENDING_APPROVALからACTIVEに切り替えます。これで本番導入が可能になります。

Webhook通知

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

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

詳細はWebhookイベントカタログを参照してください。

さらに読む

チャネルマネージャーAPI — APIエンドポイントの完全なドキュメント
料金プロバイダー — Extranetでの料金プロバイダー管理
Webhookイベントカタログ — 購読可能なすべてのイベント
Winkでの開発 — 開発者向けプラットフォーム概要