启用异步预订

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

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

预订在可用性级别指定为同步或异步。这也意味着,对于给定的商家和服务,可能既有同步可用性,又有异步可用性空档。

如需确定适当的实现方式,请先确定您的广告资源所属的类别:

异步预订使用条件

  • 不支持通过“通过 Google 预订”修改异步预订。
  • 支持需要付款的异步预订。
  • 商家应该能够通过合作伙伴的在线系统(例如餐厅的托管面板)接受或拒绝预订。允许代表用户致电商家以确定商家是接受还是拒绝预订。
  • 支持商家建议的新预订时间。您必须在最初状态下接受或拒绝预订请求。

仅启用同步预订

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

启用异步预订

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

  • 确认模式:可用性空档的所有表示法现在都包含一个 confirmation_mode 字段,用于描述如何确认该可用性空档的预订。为以下各项指定每个可用性空档的 confirmation_mode

    • 在可用性 Feed 中,confirmation_mode 是在可用性级别指定的
    • 在 Booking Server API 方法中,在空档级别指定 confirmation_mode
    • 在 Real-Time Updates API 方法中,confirmation_mode 是在可用性级别指定的
  • 预订状态:所有预订表示均包含一个 status 字段,该字段代表预订状态。引入了三个新的异步状态值:PENDING_CONFIRMATIONDECLINED_BY_MERCHANTFAILED。在处理异步预订的创建、拒绝和失败时,请使用这些新的状态值。
  • 预订更新:对预订状态的所有异步更新都应通过 Booking Notification API 的 bookings.patch 方法进行报告。

下图显示了典型的异步预订互动中如何使用确认模式和预订状态。

图 1:异步预订流程
图 1:异步预订流程
  1. 可用性 Feed 已更新,以便指定每个可用性空档的确认模式。请务必在 Feed 中包含此信息,以便我们在流程的早期阶段向用户说明预订的异步性质。
  2. 调用 BatchAvailabilityLookupCheckAvailability 时,我们会传递确认模式,最好返回相同的确认模式。这样可确保向用户显示适当的消息。
  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,并通过 BatchAvailabilityLookupRequestCheckAvailabilityRequest 进行传递。

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。这适用于以下方法:

Inventory 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