Como estruturar 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 cenários:

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

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

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

Nem todas as chamadas da API Maps Booking são obrigatórias. Os seguintes itens são obrigatórios:

Dependendo do tipo de integração, os seguintes itens também podem estar disponíveis ou serem necessários:

RTU de atualização de agendamento

Se uma reserva do Centro de ações tiver sido atualizada (por exemplo, cancelada ou modificada) no seu sistema, será necessário enviar uma notification.partners.bookings.patch (BookingNotification.UpdateBooking).

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 sua disponibilidade:

  • Substituição em lote (InventoryUpdate.BatchServiceAvailability): substitui completamente os dados de disponibilidade de um comerciante e vários serviços.
    • Observação: essa chamada em lote não garante a atomicidade. Somente os horários disponíveis atualizados com êxito serão retornados.
  • Substituição única (InventoryUpdate.ReplaceServiceAvailability): substitui completamente a disponibilidade de um único comerciante e serviço.

Use a referência abaixo para mais detalhes.

As atualizações em tempo real precisam usar a mesma estrutura de disponibilidade dos dados enviados pelos feeds. Eles precisam usar um dos seguintes:

  • 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 de cabelo e uma coloração (cada um é um serviço distinto) são agendados com um cabeleireiro. Portanto, todos os serviços vinculados ao cabeleireiro para esse horário precisam ser removidos.
  • Seu sistema vai sincronizar com o do Google de tempos em tempos, enviando todas as mudanças de disponibilidade desde a última atualização (não recomendada).
    • Substituir em lote
    • Observação: esperamos que o RTU do inventário seja enviado em até cinco minutos após uma atualização ocorrer do seu lado. Portanto, verifique e envie atualizações pelo menos a cada 5 minutos.
  • Nenhuma delas se aplica?
    • Substituir único
    • 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 anúncios

É 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 esta 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 quando um horário de 3:30 PM é reservado:

Snippet "Replace Real-Time Updates"

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

Confira 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 tem esta aparência:

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

Para a API Inventory Update, o formato do corpo da solicitação de substituição quando um horário de 3h30 da tarde é 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"
                }
              }
            ]
          }
        ]
      }
    ]
  }

Confira um exemplo do que é esperado no próximo feed diário. Ela é a disponibilidade de todo o serviço para esse comerciante e todas as schedule_exceptions anteriores e novas:

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 precisam ser enviadas continuamente sempre que a disponibilidade mudar. Além disso, é necessário enviar um feed de disponibilidade abrangente uma vez por dia para garantir que a disponibilidade seja sincronizada entre seus sistemas e os do Google.