Estruturação de atualizações em tempo real

Casos de uso para atualizações em tempo real

As atualizações em tempo real precisam ser emitidas nos seguintes casos:

  • Quando um usuário cancela uma reserva no seu sistema e o espaço fica disponível.
  • Quando um usuário faz uma reserva pelo Reservar com o Google e o horário não está mais disponível.
  • Quando uma reserva feita pelo Reservar com o Google é cancelada do seu lado, por exemplo, diretamente pelo comerciante. Você precisará atualizar a reserva e a disponibilidade porque o horário original está disponível novamente.

Além disso, se você implementar a RTU de substituição de disponibilidade, as atualizações em tempo real serão emitidas nos seguintes cenários:

  • Quando um comerciante muda a programação (disponibilidade) no seu sistema.
  • Quando um usuário reserva uma reserva no seu sistema e o horário não está mais disponível.
  • Se você estiver usando a integração legada com o CheckAvailability, quando uma chamada do servidor de agendamento CheckAvailability retorna um inventário que não corresponde ao inventário real.

Nem todas as chamadas da API Maps Booking são obrigatórias. Veja a seguir os requisitos:

Dependendo do tipo de integração, os itens a seguir também podem estar disponíveis ou ser obrigatórios:

Atualizar RTU de reserva

Caso uma atualização tenha sido feita em um agendamento do Reservar com o Google, por exemplo, cancelada ou modificada, uma notification.partners.bookings.patch (BookingNotification.UpdateBooking) precisa ser enviada.

Campos modificáveis

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

Exemplo de cancelamento

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 substituição de disponibilidade

Há dois tipos de métodos de substituição disponíveis para atualizar a disponibilidade:

  • Substituição de lote (InventoryUpdate.BatchServiceAvailability): substitui completamente os dados sobre disponibilidade de um comerciante e vários serviços.
    • Observação: essa chamada em lote não garante a atomicidade. Serão retornados apenas os horários disponíveis.
  • Single replace (InventoryUpdate.ReplaceServiceAvailability): substitui completamente a disponibilidade de um único comerciante e serviço.

Para mais informações, consulte a referência a seguir.

As atualizações em tempo real precisam usar a mesma estrutura de disponibilidade dos dados enviados pelos feeds. Ele precisa usar uma das seguintes opções:

  • spotsOpen
  • recurrence

Como escolher um método de substituição para chamar

Use o guia a seguir para determinar qual método de substituição é mais adequado:

  • Vários serviços são afetados por uma única reserva? Por exemplo, um corte e coloração de cabelo (cada um deles é um serviço diferente) é reservado com um cabeleireiro. Por isso, todos os serviços vinculados ao cabeleireiro nesse horário precisam ser removidos.
  • O sistema é sincronizado periodicamente com o Google enviando todas as alterações de disponibilidade desde a última atualização (não recomendado).
    • Substituição em lote
    • Observação: esperamos que a RTU do inventário seja enviada até cinco minutos após uma atualização ocorrer no seu lado. Por isso, verifique e envie as atualizações pelo menos a cada cinco minutos.
  • Nenhuma dessas opções se aplica?
    • Substituição única
    • Observação: é possível usar várias chamadas de substituição única para emular uma chamada de substituição em lote, mas seria mais eficiente usar uma única chamada de substituição em lote.

Atualizações em tempo real: formato aberto de vagas

É importante usar o mesmo formato nos feeds, no servidor de agendamento e nas atualizações em tempo real.

Um snippet de feed spots_open tem a seguinte aparência:

Snippet do 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 a API Inventory Update, o formato do corpo da solicitação de substituição para quando um horário das 15h30 for reservado:

Substituir snippet de atualizações em tempo 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"
          }
        ]
      }
    ]
  }

Veja um exemplo do que esperamos no próximo feed diário, se um novo horário às 15h30 for reservado:

Snippet do 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"
        }
      ]

Atualizações em tempo real: formato de recorrência

É importante usar o mesmo formato nos feeds, no servidor de agendamento e nas atualizações em tempo real.

Um feed que usa recorrência é assim:

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

Na API Inventory Update, o formato do corpo da solicitação de substituição para quando um horário das 15h30 é reservado é semelhante a este:

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

Veja um exemplo do que é esperado no próximo feed diário. Observe que é a disponibilidade de todo o serviço desse comerciante e toda a schedule_exceptions nova e anterior:

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

Quando enviar atualizações em tempo real

As atualizações em tempo real devem ser enviadas continuamente sempre que a disponibilidade mudar. Além de um feed de disponibilidade abrangente que precisa ser enviado uma vez por dia, para garantir que a disponibilidade seja sincronizada entre você e os sistemas do Google.