Cómo habilitar las reservas asíncronas

Nota: Comunícate con tu contacto de Google si te interesa habilitar las reservas asíncronas. Además, las reservas asíncronas solo son compatibles con 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.

Una reserva se especifica como síncrona o asíncrona a nivel de disponibilidad. Esto también significa que, para un comercio y servicio determinados, puede haber ranuras de disponibilidad síncronas y asíncronas.

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

• Habilitar solo reservas síncronas: Todos los comercios y servicios se confirman al instante.
• Habilita las reservas asíncronas: Algunos o todos los comercios y servicios requieren la confirmación manual.

Criterios de las reservas asíncronas

• No se admite la modificación de una reserva asíncrona en Reserva con Google.
• No se admiten las reservas asíncronas que requieren pagos.
• Los comercios deben poder aceptar o rechazar la reserva a través del sistema en línea del socio (p.ej., el panel de host del restaurante). No se permite llamar al comercio en nombre del usuario para determinar si acepta o rechaza una reserva.
• No se admiten las propuestas del comercio de un nuevo horario de reserva. La solicitud de reserva debe aceptarse o rechazarse 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 guía de integración de extremo a extremo para obtener más información.

Habilita la reserva asíncrona

Si algunos o todos los comercios usan 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 esos horarios. Especifica el confirmation_mode de cada horario disponible para lo siguiente:

  • En el feed de disponibilidad, se especifica confirmation_mode a nivel de la disponibilidad.
  • En los métodos de la API del servidor de reservas, se especifica confirmation_mode a nivel del espacio.
  • En los métodos de la API de actualizaciones en tiempo real, confirmation_mode se especifica a nivel de disponibilidad.
• Estado de la reserva: Todas las representaciones de las reservas contienen un campo status que representa el estado de la reserva. Se introdujeron tres valores de estado asíncronos nuevos: PENDING_CONFIRMATION, DECLINED_BY_MERCHANT y FAILED. Usa estos nuevos valores de estado cuando proceses creaciones, rechazos y fallas de reservas asíncronas.
• Actualizaciones de reservas: Todas las actualizaciones asíncronas del estado de las reservas deben informarse a través del método bookings.patch de la API de Booking Notification.

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

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 tener esta información en el feed para poder explicar la naturaleza asíncrona de la reserva al usuario al principio del flujo.
2. Cuando se llama a BatchAvailabilityLookup o CheckAvailability, pasamos el modo de confirmación y, lo idealmente, el mismo modo que se mostrará. Esto garantiza que se muestre al usuario 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, esta se muestra con el estado PENDING_MERCHANT_CONFIRMATION.
4. Cuando el comercio acepta o rechaza una solicitud de reserva, el estado se actualiza mediante el método bookings.patch de la API de Booking Notification. Si deseas rechazar automáticamente las reservas que no se responden de manera oportuna, usa el mismo método de actualización en tiempo real.

Feeds de disponibilidad

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

Nota: confirmation_mode se almacena en la sección de disponibilidad de los feeds de disponibilidad y actualizaciones en tiempo real. Sin embargo, este campo se almacena en el nivel de espacio para las API del servidor de reservas.

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

Aunque se supone que el modo de confirmación es síncrono si no se especifica uno, se recomienda especificar de forma explícita un modo, ya que quita cualquier confusión sobre las omisiones accidentales.

Modo 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 el BatchAvailabilityLookupResponse (BAL) o el CheckAvailabilityResponse (CA), muestra el mismo confirmation_mode que se especificó 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 con 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 del espacio agregado de la reserva proporcionado en CreateBookingRequest. Además, cuando la reserva sea asíncrona, establece status en PENDING_MERCHANT_CONFIRMATION. Asegúrate de que confirmation_mode sea lo que el usuario y lo que Reserva con Google espera evitar.

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

Sincronización

{
  "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 inicial de async, no se admiten las modificaciones del usuario a 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 confirmation_mode. Esto se aplica a los siguientes métodos:

RTU del inventario (ReplaceServiceAvailability o BatchReplaceServiceAvailability)

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

Modo 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 deben realizarse 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 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"}

Si se produce un error en la reserva, establece el estado de la reserva en FAILED y especifica el campo reserve_failure. Si el estado se establece en otra cosa, se ignora booking_failure.

Nota: Los campos booking_failure se pasan como argumentos de consulta 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, hay cinco correos electrónicos potenciales relacionados con el estado de la reserva que se envían a los usuarios.

Nota: Además de los correos electrónicos correspondientes a los siguientes estados de reserva, se enviarán recordatorios y comentarios por correo electrónico:

• PENDING_MERCHANT_CONFIRMATION
• CONFIRMED
• DECLINED_BY_MERCHANT
• FAILED
• CANCELED