添加异步预订

同步预订是指可实时确认或拒绝的预订。

异步预订是指稍后由商家确认或拒绝的预订。

可在可用性级别将预订指定为同步或异步预订。此外，对于特定的商家和服务，可同时存在同步和异步可用性空档。

如需确定合适的实现方式，请先确定您的商品目录属于哪种类别：

异步预订使用条件

  • 不支持在 Action Center 中修改异步预订。
  • 商家应能够通过合作伙伴的线上系统（例如餐厅的主机面板）接受或拒绝预订。不允许合作伙伴代表用户致电商家来确认商家是否接受预订。
  • 不支持商家建议的新预订时间。必须在原始状态下接受或拒绝预订请求。

仅启用同步预订

标准实现默认为同步预订。如需了解详情，请参阅预订端到端集成文档。

启用异步预订

如果部分或所有商家使用的是异步预订流程，则需要进行以下更改：

  • 确认模式：所有可用性空档的表示法现已都包含 confirmation_mode 字段，以说明相应可用性空档的预订确认方式。请针对以下情况指定每个可用性空档的 confirmation_mode：

    • 在可用性 Feed 中，在可用性级别指定 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. 可用性 Feed 已更新，以便指定每个可用性空档的确认模式。请务必在 Feed 中提供此信息，以便我们能够在流程中尽早向用户说明预订的异步特性。
  2. 调用 BatchAvailabilityLookup 或 CheckAvailability 时，我们会传递确认模式，且理想情况下会返回同一确认模式。这样可以确保向用户显示合适的消息。
  3. 调用 CreateBooking 时，我们会传递确认模式以指明预期的确认模式。提交异步预订请求后，系统会返回状态为 PENDING_MERCHANT_CONFIRMATION 的预订。
  4. 当商家接受或拒绝预订请求时，系统会通过实时更新 Booking Notification API 的 bookings.patch 方法进行更新。如果您想自动拒绝未及时回复的预订，请使用相同的实时更新方法。

可用性 Feed

在可用性 Feed 中，请指定每个空档的特点是同步还是异步。为此，请设置新的 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) 中，返回在可用性 Feed 中指定的同一 confirmation_mode，并通过 BatchAvailabilityLookupRequest 或 CheckAvailabilityRequest 进行传递。

BAL-Async

{
  "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-Sync

{
  "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-Async

{
  "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-Sync

{
  "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"}

电子邮件通知

对于异步预订，系统可能会向用户发送 5 种与预订状态相关的电子邮件。

：
  • PENDING_MERCHANT_CONFIRMATION
  • CONFIRMED
  • DECLINED_BY_MERCHANT
  • FAILED
  • CANCELED