Agrega reservas asíncronas

Nota: No aceptamos socios nuevos para reservas asíncronas. Además, este tipo de reservas solo se admiten en las integraciones de la versión 3 de la API basada en REST.

Las reservas síncronas se definen como aquellas que se confirman o rechazan en tiempo real.

Las reservas asíncronas se definen como aquellas que el comercio confirma o rechaza más adelante.

Se debe especificar si una reserva es síncrona o asíncrona a nivel de disponibilidad. Esto también implica que, para un comercio y un servicio determinados, puede haber horarios disponibles síncronos y asíncronos.

Para determinar la implementación adecuada, primero identifica a qué categoría pertenece tu inventario:

• Habilitación de las reservas síncronas únicamente: Todos los comercios y servicios se confirman al instante.
• Habilitación de las reservas asíncronas: Algunos o todos los comercios y servicios requieren la confirmación manual del comercio.

Criterios de las reservas asíncronas

• No se admite la modificación de las reservas asíncronas en el Centro de acciones.
• Los comercios deben poder aceptar o rechazar la reserva mediante el sistema en línea del socio (p.ej., el panel para anfitriones del restaurante). No se admiten las llamadas al comercio en nombre del usuario para determinar si el primero acepta o rechaza una reserva.
• No se admiten las propuestas del comercio de un nuevo horario de reserva. Se debe aceptar o rechazar la solicitud de reserva en el estado original.

Habilitación de las reservas síncronas únicamente

De forma predeterminada, la implementación estándar se establece en reservas síncronas. Consulta la documentación de integración de extremo a extremo de Reservations para obtener más información.

Habilitación de la reserva asíncrona

Si algunos o todos los comercios utilizan un flujo de reservas asíncrono, se deben realizar los siguientes cambios:

• Modo de confirmación: Todas las representaciones de los horarios disponibles ahora contienen un campo confirmation_mode que describe cómo se confirman las reservas de ese horario disponible. Especifica el campo confirmation_mode de cada horario disponible para los siguientes elementos:

  • En el feed de disponibilidad, confirmation_mode se especifica a nivel de la disponibilidad.
  • En los métodos de la API de Booking Server, confirmation_mode se especifica a nivel del horario disponible.
  • En los métodos de la API de actualizaciones en tiempo real, confirmation_mode se especifica a nivel de la disponibilidad.
• Estado de la reserva: Todas las representaciones de las reservas contienen un campo status que indica el estado de la reserva. Se introdujeron tres nuevos valores de estado asíncrono: PENDING_CONFIRMATION, DECLINED_BY_MERCHANT y FAILED. Utilízalos al procesar creaciones, rechazos y errores de las reservas asíncronas.
• Actualizaciones de reservas: Todas las actualizaciones asíncronas en el estado de las reservas se deben registrar a través del método bookings.patch de la API de Booking Notification.

En el siguiente diagrama, se muestra cómo se utilizan el modo de confirmación y el estado de la reserva en una interacción típica de reserva asíncrona.

Figura 1: Flujo de reserva asíncrona

1. Se actualizaron los feeds de disponibilidad para especificar el modo de confirmación de cada horario disponible. Es importante incluir esta información en el feed para que podamos explicarle al usuario la naturaleza asíncrona de la reserva al comienzo del flujo.
2. Cuando se llama a BatchAvailabilityLookup o a CheckAvailability, pasamos el modo de confirmación, y lo ideal sería que se muestre ese mismo modo. Esto garantiza que el usuario reciba el mensaje adecuado.
3. Cuando se llama a CreateBooking, pasamos el modo de confirmación para indicar el modo de confirmación anticipado. Cuando se envía la solicitud de reserva asíncrona, la reserva se muestra con el estado PENDING_MERCHANT_CONFIRMATION.
4. Cuando el comercio acepta o rechaza una solicitud de reserva, el estado de la reserva se actualiza en tiempo real a través del método bookings.patch de la API de Booking Notification. Si deseas rechazar automáticamente las reservas que no se responden de manera oportuna, hazlo con el mismo método de actualización en tiempo real.

Feeds de disponibilidad

En el feed de disponibilidad, especifica si cada horario disponible es síncrono o asíncrono. Para ello, establece el nuevo campo confirmation_mode.

Nota: El campo confirmation_mode se almacena en la sección de disponibilidad de los feeds de disponibilidad y las actualizaciones en tiempo real. Sin embargo, se almacena a nivel del horario disponible en las APIs de Booking Server.

// 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;
}

Si bien suponemos que se debe utilizar la opción síncrona cuando no se especifica un modo de confirmación determinado, se recomienda que explicites la opción deseada, ya que de esta manera eliminarás cualquier duda y se evitarán omisiones accidentales.

Asíncrono

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

Modo síncrono

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

Modos asíncrono y síncrono

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

  ]
}

Servidor de reservas

BatchAvailabilityLookup o CheckAvailability

En BatchAvailabilityLookupResponse (BAL) o CheckAvailabilityResponse (CA), muestra el mismo confirmation_mode que se especifica en el feed de disponibilidad y se pasa a través de BatchAvailabilityLookupRequest o CheckAvailabilityRequest.

BAL: modo asíncrono

{
  "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: modo síncrono

{
  "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: modo asíncrono

{
  "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: modo síncrono

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

Asegúrate de mostrar el estado correcto de la reserva mediante las opciones disponibles a continuación:

// 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;
}

En CreateBookingResponse, muestra el confirmation_mode actual correspondiente al horario disponible agregado de la reserva que se proporcionó en CreateBookingRequest. Además, cuando la reserva sea asíncrona, establece el estado (status) en PENDING_MERCHANT_CONFIRMATION. Asegúrate de que el modo de confirmación (confirmation_mode) sea aquel que esperan el usuario y Reserva con Google para evitar confusiones.

Asíncrono

{
  "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": "[e-mail]",
      "family_name": "John",
      "given_name": "Smith",
      "telephone": "[phone]",
      "user_id": "2017492857928759285"
    },
    "payment_information": {
      "prepayment_status": "PREPAYMENT_NOT_PROVIDED"
    },
    "status": "PENDING_MERCHANT_CONFIRMATION"
  }
}

Modo síncrono

{
  "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": "[e-mail]",
      "family_name": "John",
      "given_name": "Smith",
      "telephone": "[phone]",
      "user_id": "2017492857928759285"
    },
    "payment_information": {
      "prepayment_status": "PREPAYMENT_NOT_PROVIDED"
    },
    "status": "CONFIRMED"
  }
}

UpdateBooking

En la versión asíncrona inicial, no se admite que el usuario modifique una reserva existente. En cambio, el usuario debe cancelar la reserva y crear una nueva.

Actualizaciones en tiempo real

Para las actualizaciones de disponibilidad en tiempo real, se debe especificar el campo confirmation_mode. Esto se aplica a los siguientes métodos:

RTU de inventario (ReplaceServiceAvailability o BatchReplaceServiceAvailability)

Con el método availability.replace (por lotes) o el método services.availability.replace, establece confirmation_mode en CONFIRMATION_MODE_ASYNCHRONOUS en Availability.

Asíncrono

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

Modo síncrono

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

Modos asíncrono y síncrono

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

API de Booking Notification

Las actualizaciones asíncronas de un estado de reserva se deben realizar mediante el método bookings.patch de la API de Booking Notification.

Cuando actualices el estado, asegúrate de incluir el nombre del campo status en el updateMask.

Estado	Descripción
CONFIRMED	El comercio confirmó la reserva.
FAILED	El socio no pudo confirmar ni rechazar la reserva con el comercio.
DECLINED_BY_MERCHANT	El comercio rechazó la reserva.

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

En caso de que se produzca una falla en la reserva, establece el estado de la reserva en FAILED y especifica el campo booking_failure. Si el estado se establece en otra opción, se ignora booking_failure.

Nota: Los campos booking_failure se pasan como argumentos de búsqueda en la URL.

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

Notificaciones por correo electrónico

Para las reservas asíncronas, existen cinco posibles correos electrónicos relacionados con el estado de la reserva que se envían a los usuarios.

Nota: Los correos electrónicos de recordatorio y comentarios se enviarán además de aquellos correspondientes a los siguientes estados de la reserva:

• PENDING_MERCHANT_CONFIRMATION
• CONFIRMED
• DECLINED_BY_MERCHANT
• FAILED
• CANCELED