Estructura las actualizaciones en tiempo real

Casos de uso de las actualizaciones en tiempo real

Las actualizaciones en tiempo real siempre se deben emitir en las siguientes situaciones:

  • Cuando un usuario cancela una reserva en tu sistema y el horario queda disponible.
  • Cuando un usuario reserva a través del Centro de acciones y el horario ya no está disponible
  • Cuando se cancela una reserva realizada a través del Centro de acciones por tu parte, 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 las siguientes situaciones:

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

No se requieren todas las llamadas a la API de Maps Booking. Los siguientes campos son obligatorios:

Según el tipo de integración, es posible que también estén disponibles o se requieran los siguientes elementos:

Actualización en tiempo real de Update Booking

En el caso de que se haya realizado una actualización en una reserva de Actions Center (p.ej., se haya cancelado o modificado) en tu sistema, se debe enviar un 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": "2025-01-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 varios comercios y servicios.
    • Nota: Esta llamada por lotes no garantiza la atomicidad. Solo se devolverán los horarios disponibles actualizados correctamente.
  • Single Replace (InventoryUpdate.ReplaceServiceAvailability): Reemplaza por completo la disponibilidad de un solo comercio y servicio.

Consulta 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 más adecuado:

  • ¿Se ven afectados varios comercios? Por ejemplo, reemplazar la disponibilidad de varios comercios en una sola solicitud
  • Tu sistema se sincronizará con el de Google de vez en cuando enviando todos los cambios de disponibilidad desde la última actualización (no se recomienda).
    • Reemplazar por lotes
    • Nota: Esperamos que la RTU de inventario se envíe en un plazo de 5 minutos después de que se produzca una actualización de tu lado. Por lo tanto, debes verificar y enviar las actualizaciones al menos cada 5 minutos.
  • ¿Ninguna de estas opciones se aplica a tu caso o solo necesitas actualizar un comercio y un servicio?
    • Reemplazo único
    • Nota: Puedes usar varias llamadas de reemplazo único 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 del feed

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

En el caso de la API de Inventory Update, este es el formato del cuerpo de la solicitud de reemplazo cuando se reserva un horario de las 3:30 p.m.:

Reemplazar el fragmento de actualización en tiempo real

  {
    "extendedServiceAvailability": [
      {
        "merchantId": "1001",
        "serviceId": "12310",
        "startTimeRestrict": "2025-01-02T15:01:23.045123456Z",
        "endTimeRestrict": "2025-01-02T19:01:23.045123456Z",
        "availability": [
          {
            "startTime": "2025-01-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 si se reserva un horario nuevo a las 3:30 p.m.:

Fragmento del feed

"availability": [
        {
          "merchant_id": "1001",
          "service_id": "12310",
          "spots_open": 1,
          "spots_total": 2,
          "start_sec": 1735831800, # January 02, 2025 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 del 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
              }
            }
          ],
        }
      ]

En el caso de la API de Inventory Update, el formato del cuerpo de la solicitud de reemplazo cuando se reserva un horario de las 3:30 p.m. es el siguiente:

  {
    "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 se trata de la disponibilidad completa del servicio para ese comercio y todos sus schedule_exceptions anteriores y nuevos:

Fragmento del 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 se deben enviar de forma continua 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 tus sistemas y los de Google.