Se usó la API de Cloud Translation para traducir esta página.

Cómo estructurar las actualizaciones en tiempo real

Casos de uso para 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 deja de estar disponible.
Cuando un usuario hace una reserva a través del Centro de Acciones y el horario correspondiente deja de estar disponible.
Cuando se cancela una reserva hecha a través de Actions Center, por ejemplo, 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 programación (disponibilidad) en tu sistema.
Cuando un usuario hace una reserva en tu sistema y el horario correspondiente deja de estar disponible.
Si usas una integración heredada con CheckAvailability, cuando una llamada al servidor de reservas CheckAvailability muestra un inventario que no coincide con el real.

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

notification.partners.bookings.patch (BookingNotification.UpdateBooking)

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

inventory.partners.availability.replace (InventoryUpdate.BatchServiceAvailability) O inventory.partners.merchants.services.availability.replace (InventoryUpdate.ReplaceServiceAvailability)

RTU de Update Booking

En caso de que se haya realizado una actualización en una reserva de Actions Center (p.ej., se canceló o modificó) en tu sistema, se debe enviar un notification.partners.bookings.patch (BookingNotification.UpdateBooking).

Campos modificables

status
startTime
duration
partySize
paymentInformation.prepaymentStatus

Nota: Se deben especificar name, merchant_id, service_id y el campo específico que cambia. Todos los demás campos son opcionales. En algunas circunstancias, varios campos pueden cambiar al mismo tiempo. En este caso, las comas separan los campos en updateMask (p. ej., updateMask=partySize,startTime).

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:

Reemplazo por lotes (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.
Reemplazo único (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. Debe 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 servicios con una sola reserva? Por ejemplo, se reserva un corte de cabello y un tinte (cada uno es un servicio distinto) con un estilista, por lo que se deben quitar todos los servicios vinculados al estilista para ese horario.
- Reemplazo por lotes
Tu sistema se sincronizará con el de Google de vez en cuando y enviará 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 realice una actualización de tu parte. Por lo tanto, debes verificar y enviar actualizaciones al menos cada 5 minutos.
¿Ninguna de estas opciones se aplica?
- 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 de Spots Open

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 cuando se reserva un horario de 3:30 p.m. es el siguiente:

Cómo reemplazar 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 siguiente feed diario, si se reserva un nuevo horario 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"
        }
      ]

Nota: En caso de que no haya más disponibilidad (spots_open sea 0), existen 2 formatos posibles para enviar la solicitud de reemplazo a la API de Inventory.

Especificación explícita: Este es el método recomendado si tienes spots_total > 1.

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

Especificación vacía: Se recomienda solo si spots_total = 1 para la mayoría de los comercios y servicios.

  {
  "extendedServiceAvailability": [
    {
      "merchantId": "1001",
      "serviceId": "12310",
      "startTimeRestrict": "2014-10-02T15:01:23.045123456Z",
      "endTimeRestrict": "2014-10-02T19:01:23.045123456Z",
      "availability": [
        {}
      ]
    }
  ]
}

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
              }
            }
          ],
        }
      ]

En el caso de la API de Inventory Update, el formato del cuerpo de la solicitud de reemplazo para cuando se reserva un horario de 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"
                }
              }
            ]
          }
        ]
      }
    ]
  }

Nota: Las actualizaciones en tiempo real deben contener todos los schedule_exceptions para los intervalos reservados. El motivo es que el método de la API reemplaza la disponibilidad de ese servicio y comercio específicos. Si lo reemplazas por otra información, esta debe ser la información completa sobre la disponibilidad de ese servicio y debe incluir todos los horarios reservados.

Este es un ejemplo de lo que se espera en el próximo feed diario. Ten en cuenta que es la disponibilidad de todo el servicio para ese comercio y todos sus schedule_exceptions anteriores y nuevos:

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 se deben enviar de forma continua cada vez que cambia 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 esté sincronizada entre tus sistemas y los de Google.