Estructura las actualizaciones en tiempo real

Casos de uso de actualizaciones en tiempo real

Las actualizaciones en tiempo real siempre deben emitirse en los siguientes casos:

  • Cuando un usuario cancela una reserva en tu sistema, la ranura pasa a estar disponible.
  • Cuando un usuario hace una reserva a través del Centro de Acciones y el horario disponible deja de estar disponible.
  • Cuando se cancela una reserva realizada a través del Centro de acciones, por ejemplo, por el comercio directamente. Deberás actualizar la reserva y la disponibilidad, ya que el horario original está disponible nuevamente.

Además, si implementas la RTU de Availability Replace, se deben emitir actualizaciones en tiempo real en los siguientes casos:

  • Cuando un comercio cambia su programa (disponibilidad) en tu sistema.
  • Cuando un usuario hace una reserva en tu sistema y el horario disponible deja de estar disponible.
  • Si usas una integración heredada con CheckAvailability, cuando una llamada al servidor de reservas CheckAvailability muestre inventario que no coincide con el real.

No todas las llamadas a la API de Maps Booking son obligatorias. Los siguientes pasos son obligatorios:

Según el tipo de integración, es posible que lo siguiente también esté disponible o se requiera:

Actualizar la RTU de la reserva

En caso de que se actualice una reserva del Centro de Acciones (p.ej., cancelada o modificada) en tu sistema, se debe enviar una notification.partners.bookings.patch (BookingNotification.UpdateBooking).

Campos modificables

  • status
  • startTime
  • duration
  • partySize
  • paymentInformation.prepaymentStatus

Ejemplo de cancelación

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

Body:
{
  "name": "partners/<PARTNER_ID>/bookings/<BOOKING_ID>",
  "merchantId": "10001",
  "serviceId": "1001",
  "startTime": "2014-10-02T15:01:23.045123456Z",
  "duration": "3000s",
  "status": "CANCELED"
}

RTU de Availability Replace

Existen dos tipos de métodos de reemplazo disponibles para actualizar tu disponibilidad:

  • Batch Replace (InventoryUpdate.BatchServiceAvailability): Reemplaza por completo los datos de disponibilidad de un comercio y varios servicios.
    • Nota: Esta llamada por lotes no garantiza la atomicidad. Solo se mostrarán los horarios disponibles actualizados correctamente.
  • Single Replace (InventoryUpdate.ReplaceServiceAvailability): Reemplaza completamente la disponibilidad de un solo comercio y servicio.

Usa la siguiente referencia para obtener más detalles.

Las actualizaciones en tiempo real deben usar la misma estructura de disponibilidad que los datos que se envían a través de los feeds. Deben usar una de las siguientes opciones:

  • spotsOpen
  • recurrence

Cómo elegir un método de reemplazo para llamar

Usa la siguiente guía para determinar qué método de reemplazo es el más adecuado:

  • ¿Varios servicios se ven afectados con una sola reserva? Por ejemplo, un corte de cabello y colorear (cada uno es un Servicio diferente) se reserva con un estilista, por lo que se deben quitar todos los servicios vinculados al estilista para ese horario.
  • De vez en cuando, tu sistema se sincronizará con el de Google enviando todos los cambios de disponibilidad desde la última actualización (no se recomienda).
    • Reemplazo por lotes
    • Nota: Esperamos que la RTU del inventario se envíe en un plazo de 5 minutos después de que se produzca una actualización. Por lo tanto, debes revisar y enviar las actualizaciones al menos cada 5 minutos.
  • ¿No se aplica ninguna de estas opciones?
    • Reemplazo único
    • Nota: Puedes usar varias llamadas de reemplazo por lotes para emular una llamada de reemplazo por lotes, pero sería más eficiente usar una sola llamada de reemplazo por lotes.

Actualizaciones en tiempo real: Formato abierto de Spots

Es importante usar el mismo formato en los feeds, el servidor de reservas y las actualizaciones en tiempo real.

Un fragmento de feed spots_open se ve de la siguiente manera:

Fragmento de feed

   "availability": [
          {
            "merchant_id": "1001",
            "service_id": "12310",
            "spots_open": 2,
            "spots_total": 2,
            "start_sec": 1412263800, # October 02, 2014 15:30:00
            "duration_sec": 1800,
            "availabilityTag": "1000001"
          }
    ]

Para la API de Inventory Update, el formato del cuerpo de la solicitud de reemplazo para cuando se reserva un horario disponible a las 3:30 p.m.:

Reemplaza el fragmento de actualizaciones en tiempo real

  {
    "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": "1",
            "spotsTotal": "2",
            "availabilityTag": "1000001"
          }
        ]
      }
    ]
  }

Este es un ejemplo de lo que esperamos en el próximo feed diario en caso de que se reserve un nuevo horario disponible a las 3:30 p.m.:

Fragmento de feed

"availability": [
        {
          "merchant_id": "1001",
          "service_id": "12310",
          "spots_open": 1,
          "spots_total": 2,
          "start_sec": 1412263800, # October 02, 2014 15:30:00
          "duration_sec": 1800,
          "availabilityTag": "1000001"
        }
      ]

Actualizaciones en tiempo real: formato de recurrencia

Es importante usar el mismo formato en los feeds, el servidor de reservas y las actualizaciones en tiempo real.

Un feed que usa recurrencia se ve de la siguiente manera:

Fragmento de feed

  "availability": [
        {
          "merchant_id": "1001",
          "service_id": "12310",
          "spots_open": 1,
          "spots_total": 1,
          "start_sec": 1540890000, # October 30, 2018 9:00:00 AM
          "duration_sec": 1800,
          "recurrence": {
            "repeat_every_sec": 1800,
            "repeat_until_sec": 1540918800 # October 30, 2018 5:00:00 PM
          },
          "schedule_exception": [
            {
              "time_range": {
                "begin_sec": 1540902600, # October 30, 2018 12:30:00 PM
                "end_sec": 1540904400 # October 30, 2018 1:00:00 PM
              }
            }
          ],
        }
      ]

Para la API de Inventory Update, el formato del cuerpo de la solicitud de reemplazo para cuando se reserva un horario disponible a las 3:30 p.m. se ve de la siguiente manera:

  {
    "extendedServiceAvailability": [
      {
        "merchantId": "1001",
        "serviceId": "12310",
        "startTimeRestrict": "2018-10-30T15:01:23.045123456Z",
        "endTimeRestrict": "2018-10-30T19:01:23.045123456Z",
        "availability": [
          {
            "startTime": "2018-10-30T15:30:00.00Z",
            "duration": "3600s",
            "spotsOpen": "1",
            "scheduleException": [
             {
                "timeRange": {
                  "startTime": "2018-10-30T12:30:00.00Z",
                  "endTime": "2018-10-30T13:00:00.00Z"
                }
              },
              {
                "timeRange": {
                  "startTime": "2018-10-30T15:30:00.00Z",
                  "endTime": "2018-10-30T16:00:00.00Z"
                }
              }
            ]
          }
        ]
      }
    ]
  }

Este es un ejemplo de lo que se espera en el próximo feed diario. Ten en cuenta que corresponde a la disponibilidad completa del servicio para ese comercio, así como todas sus schedule_exceptions anteriores y nuevas:

Fragmento de feed

   "availability": [
        {
          "merchant_id": "1001",
          "service_id": "12310",
          "spots_open": 1,
          "spots_total": 1,
          "start_sec": 1540890000, # October 30, 2018 9:00:00 AM
          "duration_sec": 1800,
          "recurrence": {
            "repeat_every_sec": 1800,
            "repeat_until_sec": 1540918800 # October 30, 2018 5:00:00 PM
          },
          "schedule_exception": [
            {
              "time_range": {
                "begin_sec": 1540902600, # October 30, 2018 12:30:00 PM
                "end_sec": 1540904400 # October 30, 2018 1:00:00 PM
              }
            },
            {
              "time_range": {
                "begin_sec": 1540913400, # October 30, 2018 3:30:00 PM
                "end_sec": 1540915200 # October 30, 2018 4:00:00 PM
              }
            }
          ],
        }
      ]

Cuándo enviar actualizaciones en tiempo real

Las actualizaciones en tiempo real deben enviarse continuamente cada vez que cambie la disponibilidad. Esto se suma a un feed de disponibilidad integral que se debe enviar una vez al día para garantizar que la disponibilidad se sincronice entre tu sistema y el de Google.