新增非同步預訂

「同步預訂」是指即時確認或拒絕的預訂。

「非同步預訂」是指商家稍後才會確認或拒絕的預訂。

某筆預訂屬於同步或非同步，則是在供應情形層級進行指定。這也表示對於特定商家和服務來說，可能會同時有同步和非同步供應時段的情況。

首先請確認您提供的預約服務屬於哪個類別，以便決定適當的導入方式：

非同步預訂條件

  • 不支援修改 Actions Center 上的非同步預訂。
  • 商家可透過合作夥伴的線上系統 (例如餐廳的訂位系統) 接受或拒絕預訂。不得代表使用者致電商家，詢問商家是否接受或拒絕預訂。
  • 不支援商家提議新的預訂時間，商家必須就預訂要求的原始條件決定接受或拒絕。

只啟用同步預訂功能

標準導入作業預設為同步預訂。詳情請參閱「預訂服務端對端整合」說明文件。

啟用非同步預訂

如果部分或所有的商家採用了非同步預訂流程，則必須執行以下變更：

  • 確認模式：供應時段的所有表示法中現在都包含一個 confirmation_mode 欄位，說明該供應時段的預訂確認方式。請針對下列項目為每個供應時段指定 confirmation_mode：

    • 在供應情形動態饋給中，confirmation_mode 是在供應情形層級指定
    • 在 Booking Server API 方法中，confirmation_mode 是在時段層級指定
    • 在 Real-Time Updates API 方法中，confirmation_mode 是在供應情形層級指定
  • 預訂狀態：預訂的所有表示法中都包含一個 status 欄位，代表該預訂的狀態。我們推出了三種新的非同步狀態值：PENDING_CONFIRMATION、DECLINED_BY_MERCHANT 和 FAILED。處理非同步預訂的建立項目、拒絕項目和失敗項目時，請使用這些新狀態值。
  • 預訂更新：所有針對預訂狀態的非同步更新，都應透過 Booking Notification API 的 bookings.patch 方法來回報。

下圖顯示的是確認模式和預訂狀態在一般非同步預訂模式互動中的使用方式。

圖 1：非同步預訂流程
圖 1：非同步預訂流程
  1. 供應情形動態饋給已更新，現可指定每個供應時段的確認模式。請務必在動態饋給中提供這項資訊，以便我們在預訂流程中，盡早向使用者說明該預訂可能無法即時確認的非同步性質。
  2. 當系統呼叫 BatchAvailabilityLookup 或 CheckAvailability 時，我們會傳送確認模式，理想的情況下是也能傳回同樣的確認模式，以確保使用者能看到適當的訊息。
  3. 當系統呼叫 CreateBooking 時，我們會傳送確認模式，以指出預期的確認模式。提交非同步預訂要求時，系統會將預訂以 PENDING_MERCHANT_CONFIRMATION 的狀態傳回。
  4. 商家接受或拒絕預訂要求時，系統會透過即時更新的 Booking Notification API 的 bookings.patch 方法更新預訂狀態。如果您想要讓系統自動拒絕未即時回應的預訂，請透過同樣的即時更新方法執行。

供應情形動態饋給

在供應情形動態饋給中，指定各個時段是同步或非同步。做法是設定新的 confirmation_mode 欄位。

// Mode by which bookings for an availability slot are confirmed.
enum ConfirmationMode {
  // The confirmation mode was not specified.
  // Synchronous confirmation will be assumed.
  CONFIRMATION_MODE_UNSPECIFIED = 0;

  // Bookings for this availability will be confirmed synchronously.
  CONFIRMATION_MODE_SYNCHRONOUS = 1;

  // Bookings for this availability will be confirmed asynchronously.
  CONFIRMATION_MODE_ASYNCHRONOUS = 2;
}

雖然在未指定任何模式的情況下，系統會預設採用同步確認模式，但強烈建議您還是要明確指定模式，以免意外遺漏任何項目而造成混淆。

非同步

{
  "availability": [
    {
      "merchant_id": "10001",
      "service_id": "1000",
      "spots_open": 3,
      "spots_total": 3,
      "duration_sec": 3600,
      "start_sec": 1535806800,
      "resources": {
        "party_size": 4
      },
      "confirmation_mode": "CONFIRMATION_MODE_ASYNCHRONOUS"
    }
  ]
}

同步

{
  "availability": [
    {
      "merchant_id": "10001",
      "service_id": "1000",
      "spots_open": 3,
      "spots_total": 3,
      "duration_sec": 3600,
      "start_sec": 1535806800,
      "resources": {
        "party_size": 4
      },
      "confirmation_mode": "CONFIRMATION_MODE_SYNCHRONOUS"
    }
  ]
}

非同步與同步

{
  "availability": [
    {
      "merchant_id": "10001",
      "service_id": "1000",
      "spots_open": 3,
      "spots_total": 3,
      "duration_sec": 3600,
      "start_sec": 1535806800,
      "resources": {
        "party_size": 4
      },
      "confirmation_mode": "CONFIRMATION_MODE_SYNCHRONOUS"
    },
    {
      "merchant_id": "10002",
      "service_id": "1000",
      "spots_open": 4,
      "spots_total": 4,
      "duration_sec": 3600,
      "start_sec": 1535806800,
      "resources": {
        "party_size": 2
      },
      "confirmation_mode": "CONFIRMATION_MODE_ASYNCHRONOUS"
    }

  ]
}

預訂伺服器

BatchAvailabilityLookup 或 CheckAvailability

在 BatchAvailabilityLookupResponse (BAL) 或 CheckAvailabilityResponse (CA) 中，傳回與供應情形動態饋給中指定的項目相同的 confirmation_mode，然後透過 BatchAvailabilityLookupRequest 或 CheckAvailabilityRequest 傳送。

BAL-非同步

{
  "slot_time_availability": [
    {
      "slot_time": {
        "duration_sec": "3600",
        "resource_ids": {
          "party_size": 3
        },
        "service_id": "1000",
        "start_sec": "1546458300",
        "confirmation_mode": "CONFIRMATION_MODE_ASYNCHRONOUS"
      },
      "available": true
    }
  ]
}

BAL-同步

{
  "slot_time_availability": [
    {
      "slot_time": {
        "duration_sec": "3600",
        "resource_ids": {
          "party_size": 3
        },
        "service_id": "1000",
        "start_sec": "1546458300",
        "confirmation_mode": "CONFIRMATION_MODE_SYNCHRONOUS"
      },
      "available": true
    }
  ]
}

CA-非同步

{
  "slot": {
    "duration_sec": "3600",
    "merchant_id": "317652",
    "resources": {
      "party_size": 3
    },
    "service_id": "1000",
    "start_sec": "1546458300",
    "confirmation_mode": "CONFIRMATION_MODE_ASYNCHRONOUS"
  },
  "count_available": 1,
  "duration_requirement": "DO_NOT_SHOW_DURATION"
}

CA-同步

{
  "slot": {
    "duration_sec": "3600",
    "merchant_id": "317652",
    "resources": {
      "party_size": 3
    },
    "service_id": "1000",
    "start_sec": "1546458300",
    "confirmation_mode": "CONFIRMATION_MODE_SYNCHRONOUS"
  },
  "count_available": 1,
  "duration_requirement": "DO_NOT_SHOW_DURATION"
}

CreateBooking

請務必使用下列可用選項，為預訂傳回正確的狀態：

// Status of a booking.
//
// Updating booking status does not change the status of the associated payment.
// Prepayment status updates should be done using the PrepaymentStatus enum.
enum BookingStatus {
  // Not specified.
  BOOKING_STATUS_UNSPECIFIED = 0;

  // Booking has been confirmed
  CONFIRMED = 1;

  // Booking is awaiting confirmation by the merchant before it can transition
  // into CONFIRMED status. Only applicable to non-payments Dining or
  // Beauty verticals.
  PENDING_MERCHANT_CONFIRMATION = 2;

  // Booking has been canceled on behalf of the user.
  // The merchant can still trigger a manual refund.
  CANCELED = 3;

  // User did not show for the appointment
  NO_SHOW = 4;

  // User did not show for the appointment in violation of the cancellation
  // policy.
  NO_SHOW_PENALIZED = 5;

  // Booking could not be completed by the async backend due to a failure.
  FAILED = 6;

  // Booking was asynchronously declined by the merchant. Only applicable to
  // non-payments Dining or Beauty verticals.
  DECLINED_BY_MERCHANT = 7;
}

在 CreateBookingResponse 中，針對 CreateBookingRequest 中提供的預訂匯總時段，傳回目前的 confirmation_mode。此外，如果是非同步預訂，請將 status 設為 PENDING_MERCHANT_CONFIRMATION。請確保 confirmation_mode 是使用者和「透過 Google 預訂」服務預期的內容，避免造成使用者混淆。

非同步

{
  "booking": {
    "slot": {
      "duration_sec": "3600",
      "merchant_id": "100001",
      "resources": {
        "party_size": 2
      },
      "service_id": "1000",
      "start_sec": "1546647234",
      "confirmation_mode": "CONFIRMATION_MODE_ASYNCHRONOUS"
    },
    "user_information": {
      "email": "johnsmith@gmail.com",
      "family_name": "John",
      "given_name": "Smith",
      "telephone": "+1 800-123-4567",
      "user_id": "2017492857928759285"
    },
    "payment_information": {
      "prepayment_status": "PREPAYMENT_NOT_PROVIDED"
    },
    "status": "PENDING_MERCHANT_CONFIRMATION"
  }
}

同步

{
  "booking": {
    "slot": {
      "duration_sec": "3600",
      "merchant_id": "100001",
      "resources": {
        "party_size": 2
      },
      "service_id": "1000",
      "start_sec": "1546647234",
      "confirmation_mode": "CONFIRMATION_MODE_SYNCHRONOUS"
    },
    "user_information": {
      "email": "johnsmith@gmail.com",
      "family_name": "John",
      "given_name": "Smith",
      "telephone": "+1 800-123-4567",
      "user_id": "2017492857928759285"
    },
    "payment_information": {
      "prepayment_status": "PREPAYMENT_NOT_PROVIDED"
    },
    "status": "CONFIRMED"
  }
}

UpdateBooking

在非同步的初始版本中，系統不支援使用者修改現有的預訂。使用者應改為取消預訂並建立新的預訂。

即時更新

如要即時更新供應情形，則必須指定 confirmation_mode。這適用於下列方法：

庫存 RTU (ReplaceServiceAvailability 或 BatchReplaceServiceAvailability)

使用 availability.replace (批次) 方法或 services.availability.replace 方法，將 Availability 中的 confirmation_mode 設為 CONFIRMATION_MODE_ASYNCHRONOUS

非同步

{
  "extendedServiceAvailability": [
    {
      "merchantId": "1001",
      "serviceId": "12310",
      "startTimeRestrict": "2014-10-02T15:01:23.045123456Z",
      "endTimeRestrict": "2014-10-02T19:01:23.045123456Z",
      "availability": [
        {
          "startTime": "2014-10-02T15:30:00.00Z",
          "duration": "3600s",
          "spotsOpen": "0",
          "spotsTotal": "2",
          "availabilityTag": "1000001",
          "confirmation_mode": "CONFIRMATION_MODE_ASYNCHRONOUS"
        }
      ]
    }
  ]
}

同步

{
  "extendedServiceAvailability": [
    {
      "merchantId": "1001",
      "serviceId": "12310",
      "startTimeRestrict": "2014-10-02T15:01:23.045123456Z",
      "endTimeRestrict": "2014-10-02T19:01:23.045123456Z",
      "availability": [
        {
          "startTime": "2014-10-02T15:30:00.00Z",
          "duration": "3600s",
          "spotsOpen": "0",
          "spotsTotal": "2",
          "availabilityTag": "1000001",
          "confirmation_mode": "CONFIRMATION_MODE_SYNCHRONOUS"
        }
      ]
    }
  ]
}

非同步與同步

{
  "extendedServiceAvailability": [
    {
      "merchantId": "1001",
      "serviceId": "12310",
      "startTimeRestrict": "2014-10-02T15:01:23.045123456Z",
      "endTimeRestrict": "2014-10-02T19:01:23.045123456Z",
      "availability": [
        {
          "startTime": "2014-10-02T15:30:00.00Z",
          "duration": "3600s",
          "spotsOpen": "0",
          "spotsTotal": "2",
          "availabilityTag": "1000001",
          "confirmation_mode": "CONFIRMATION_MODE_ASYNCHRONOUS"
        },
        {
          "startTime": "2014-10-03T11:00:00.00Z",
          "duration": "5400s",
          "spotsOpen": "1",
          "spotsTotal": "1",
          "availabilityTag": "1000002",
          "confirmation_mode": "CONFIRMATION_MODE_SYNCHRONOUS"
        }
      ]
    }
  ]
}

Booking Notification API

如要以非同步方式更新預訂狀態，必須使用 Booking Notification API 的 bookings.patch 方法。

更新狀態時，請務必在 updateMask 中納入 status 欄位名稱。

狀態 說明
CONFIRMED 商家已確認預訂
FAILED 合作夥伴無法向商家確認或拒絕預訂
DECLINED_BY_MERCHANT 商家拒絕預訂 
Request:
PATCH https://mapsbooking.googleapis.com/v1alpha/notification/partners/<PARTNER_ID>/bookings/<BOOKING_ID>?updateMask=status

Body:
{"name":"partners/<PARTNER_ID>/bookings/<BOOKING_ID>", "status":"DECLINED_BY_MERCHANT"}

在預訂失敗事件中，請將預訂狀態設為 FAILED，並指定 booking_failure。如果設為其他狀態，系統會忽略 booking_failure。

Request:
PATCH https://mapsbooking.googleapis.com/v1alpha/notification/partners/<PARTNER_ID>/bookings/<BOOKING_ID>?updateMask=status&booking_failure.cause="SLOT_UNAVAILABLE"

Body:
{"name":"partners/<PARTNER_ID>/bookings/<BOOKING_ID>", "status":"FAILED"}

電子郵件通知

針對非同步預訂，系統可能會傳送五種不同預訂狀態的電子郵件通知給使用者。

  • PENDING_MERCHANT_CONFIRMATION
  • CONFIRMED
  • DECLINED_BY_MERCHANT
  • FAILED
  • CANCELED