Como estruturar atualizações em tempo real

Casos de uso para atualizações em tempo real

As Atualizações em tempo real sempre precisam ser emitidas nos seguintes cenários:

  • Quando um usuário cancela uma reserva no sistema e o slot fica disponível.
  • Quando um usuário faz uma reserva na Central de ações e o horário não está mais disponível.
  • Quando uma reserva feita pela Central de ações é cancelada no 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 precisarão ser emitidas nos seguintes cenários:

  • Quando um comerciante altera a programação (disponibilidade) no seu sistema.
  • Quando um usuário faz uma reserva no seu sistema e o horário 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 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 itens a seguir também podem estar disponíveis ou necessários:

Atualizar RTU de reserva

Caso uma atualização tenha sido feita em um agendamento da Central de ações (por exemplo, cancelado ou modificado) no seu sistema, é necessário enviar um 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 a disponibilidade:

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

Use a referência a seguir para ver mais detalhes.

As atualizações em tempo real precisam usar a mesma estrutura de disponibilidade dos dados enviados por feeds. Eles precisam usar uma destas opções:

  • spotsOpen
  • recurrence

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

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

  • Vários serviços são afetados com um único agendamento? Por exemplo, um corte de cabelo e coloração (cada um é um serviço diferente) são agendados com um estilista. Portanto, todos os serviços vinculados ao estilista nesse horário precisam ser removidos.
  • Seu sistema será sincronizado com o Google periodicamente, enviando todas as mudanças de disponibilidade desde a última atualização (não recomendado).
    • Substituição em lote
    • Observação: esperamos que a RTU de inventário seja enviada em 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.
  • Nenhum desses casos 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 é mais eficiente usar uma única chamada de substituição em lote

Atualizações em tempo real: formato Spots Open

É 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 para quando um espaço às 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"
          }
        ]
      }
    ]
  }

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 para quando um espaço às 15h30 for reservado é semelhante a:

  {
    "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 do próximo feed diário. Observe que essa é a disponibilidade do serviço para esse comerciante e todas as schedule_exceptions anteriores e novas dele:

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

Atualizações em tempo real devem ser enviadas continuamente sempre que a disponibilidade mudar. Esse recurso complementa um feed de disponibilidade abrangente que precisa ser enviado uma vez por dia para garantir que a disponibilidade seja sincronizada entre seu sistema e o do Google.