# サイトコントローラー・PMS との連携

> **ご利用いただけるプラン**
>
> このページの機能は、すべてのプランでご利用いただけます。

VibeBooking は、貴社システムから施設の部屋タイプ・料金・在庫を取得し、AI アシスタント経由の予約を貴社システムに登録します。貴社の API に合わせたアダプター（接続部分）は、当社が作ります。

## 貴社システムに求める機能

| 機能 | 求める内容 |
| --- | --- |
| 部屋タイプ・料金・在庫の取得 | 料金プラン、日別の料金と在庫、最低泊数、チェックイン・チェックアウトの制限（CTA・CTD） |
| 予約の登録 | 1 回の宿泊を 1 件の予約として登録し、予約 ID を返す。当社の予約番号を予約に保持する |
| 受付不可と無応答の区別 | 受け付けられない予約には、明確なエラーを返す |
| 当社予約番号での検索 | 当社の予約番号で予約を検索できる |
| 予約 ID での照会 | 予約の有無、キャンセル済みかどうか、当社の予約番号を返す |
| 予約のキャンセル | 予約 ID でキャンセルできる。キャンセル済みの予約への再送もエラーにしない |
| キャンセル・変更時の在庫戻し | 在庫が自動で戻る設定かどうかを取得できる。戻らない施設の予約は、当社が受け付けない |
| 支払方法の記録 | 事前決済か現地払いか、決済済みの金額を記録できる |

タイムアウトとサーバーエラーは、予約が登録された可能性があるものとして扱います。

### 予約が入るまでの流れ

```mermaid
sequenceDiagram
    autonumber
    participant G as 宿泊者・AI アシスタント
    participant V as VibeBooking
    participant S as Stripe（施設のアカウント）
    participant P as 貴社システム
    G->>V: 予約を申し込む
    V->>P: 最新の料金と在庫を確認
    V->>S: カードの与信を取る
    V->>P: 予約を登録（当社の予約番号つき）
    P-->>V: 予約 ID
    V->>S: 売上を確定
    V-->>G: 予約確定のメール
```

### 決済

決済の主体は施設で、代金は施設ご自身の Stripe アカウントに入ります。当社は代金を預からず、手数料もいただきません。貴社システムに登録できなかった予約は、与信を取り消し、請求しません。

## 当社側で担保すること

- すべての API 呼び出しは冪等です。再送しても結果は変わりません。
- 同じ予約を二重に登録しません。
- 決済に失敗した予約は、貴社システム上でもキャンセルします。
- 予約データを定期的に突合し、差異があればお知らせします。
- 宿泊者情報は予約専用のデータベースにのみ保存し、貴社には必要な項目だけを送ります。

貴社システムから応答がないときは、次のように処理します。

```mermaid
sequenceDiagram
    participant V as VibeBooking
    participant P as 貴社システム
    participant S as Stripe
    V-xP: 予約を登録
    Note over V,P: タイムアウト。再送しない
    V->>P: 当社の予約番号で検索
    alt 予約あり
        V->>S: 売上を確定
    else 予約なし
        V->>S: 与信を取り消す
    end
```

## 送信する予約データ

予約 1 件ごとに、当社から貴社システムへ次の項目を送ります。

| 項目 | 内容 |
| --- | --- |
| 当社の予約番号 | 例: `VB-ABC123`。検索・照会・キャンセルにも使います |
| 部屋タイプ、料金プラン | 貴社システムの ID |
| チェックイン日、チェックアウト日 |  |
| 人数 | 大人、子供 |
| 1 泊ごとの料金、通貨 | 合計を泊数で割った額。現地払いの宿泊税を含みます |
| 支払い | 事前決済: 決済済みの額と Stripe の決済 ID。合計との差額は現地で受け取ります。現地払い: 全額を現地で受け取ります |
| 代表者の氏名、メールアドレス、電話番号 |  |
| ふりがな | 漢字の氏名の方 |
| 海外在住 | 海外にお住まいの方。日本国籍の場合はその旨も |
| 国籍、旅券番号 | 日本に住所のない外国籍の方。旅館業法で宿泊者名簿に記載する項目です |
| 流入元 ID | どの AI 経由の予約かを示す当社の ID |

項目を受け取れる欄が貴社システムにないときは、備考に 1 行ずつ書きます。旅券の確認は、チェックイン時に施設が対面で行います。カード情報は送りません。

## API の方式

貴社の API がどの方式でも、必要であれば当社が貴社専用のアダプターを作ります。予約の仕組みはそのままで、貴社ごとに接続部分だけを足すつくりです。

| 方式 | 対応 |
| --- | --- |
| REST（JSON） | 実装済み（Channex、Beds24） |
| SOAP・XML over HTTPS | 貴社の仕様に合わせて実装します |
| TravelXML | 貴社の仕様に合わせて実装します |
| 認証 | API キー、リフレッシュトークン |
| 通信 | HTTPS のみ |

### OpenTravel との対応

当社は OpenTravel（OTA）のメッセージを標準ではやり取りしません。貴社の API が OTA の XML（`http://www.opentravel.org/OTA/2003/05`）を使うときは、`OTA_HotelResNotifRQ` で次のように送ります。要素名とコードは OpenTravel 2017B に基づきます。

| 送信する項目 | OpenTravel の要素 |
| --- | --- |
| 当社の予約番号 | `UniqueID`（`Type="14"`） |
| 部屋タイプ、料金プラン | `RoomType@RoomTypeCode`、`RatePlan@RatePlanCode` |
| チェックイン日、チェックアウト日 | `TimeSpan@Start`、`TimeSpan@End` |
| 人数 | `GuestCount@AgeQualifyingCode`（大人 `10`、子供 `8`） |
| 1 泊ごとの料金、通貨 | `Rate/Base@AmountAfterTax`、`@CurrencyCode` |
| 支払い | `Guarantee@GuaranteeType`（事前決済は `PrePay`、現地払いは `None`）。決済済みの額は `DepositPayments` |
| 代表者の氏名、メールアドレス、電話番号 | `Customer` の `PersonName`、`Email`、`Telephone` |
| 国籍、旅券番号 | `CitizenCountryName`、`Document`（`DocType="2"`） |
| ふりがな、海外在住 | 対応する要素がないため、`ResGlobalInfo/Comments` に書きます |
| 流入元 ID | `POS/Source/BookingChannel` |
| キャンセル | `ResStatus="Cancel"` |

カード情報（`PaymentCard`）は送りません。

## 対応済みのシステム

### Channex

| 機能 | Channex での対応 |
| --- | --- |
| 取得 | 部屋タイプ、料金プラン、在庫、販売制限 |
| 予約の登録 | Booking CRS の `POST /bookings`（ステータス `new`、`ota_name` は `Offline`） |
| 当社予約番号の保持 | `ota_reservation_code` と `meta` |
| 当社予約番号での検索 | 予約一覧を当社の予約番号で照合 |
| 予約 ID での照会 | `GET /bookings/:id` |
| 予約のキャンセル | `PUT /bookings/:id`（ステータス `cancelled`） |
| 在庫戻し | `allow_availability_autoupdate_on_cancellation` と `allow_availability_autoupdate_on_modification` が両方オン |
| 事前決済 | `payment_collect` は `ota`、決済額はデポジットとして記録 |
| 現地払い | `payment_collect` は `property` |

ふりがなと宿泊者名簿の項目は、フロントで読めるよう、予約の備考（`notes`）に日本語で 1 行ずつ書きます。

| 宿泊者情報 | Channex での記録先 |
| --- | --- |
| 氏名 | `customer` の姓・名と、部屋ごとの宿泊者（`guests`） |
| メールアドレス、電話番号 | `customer` の `mail`、`phone` |
| ふりがな | 備考 `ふりがな: …` |
| 海外在住 | 備考 `居住: 海外`、日本国籍の方は `居住: 海外（日本国籍）` |
| 国籍 | 備考 `国籍: …` |
| 旅券番号 | 備考 `旅券番号: …` |
| テスト予約 | 備考の先頭に `[TEST]` |

- Channex に Booking CRS アプリをインストールしておく必要があります。
- 在庫を戻す設定は初期状態でオフです。施設が Channex でオンにします。
- API は非同期のため、登録直後の照会で 404 が返ることがあります。当社はこれを予約なしとは判断しません。

### 施設側の接続

施設は VibeBooking のコンソールで Channex の API キーを貼り付けて連携します。連携すると、「施設」の「連携」に Channex が表示されます。

![Channexと連携する画面。APIキーを貼り付ける欄と連携するボタンがある。](https://docs.vibebooking.ai/screenshots/ja/channex-key-desktop.webp)
*API キーを貼り付けて連携する画面。*

![施設の連携タブ。Channexと連携済みの表示が出ている。](https://docs.vibebooking.ai/screenshots/ja/channex-connected-desktop.webp)
*連携後の「連携」。*

## お問い合わせ

連携をご検討の事業者様は、hello@vibebooking.ai までご連絡ください。