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 pela Central de ações e o horário não está mais disponível.
  • Quando uma reserva feita pelo Central de ações é cancelada diretamente pelo comerciante, por exemplo. Você precisa 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 deverã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 não está mais disponível.
  • Se você estiver usando uma integração legada com CheckAvailability, quando uma chamada CheckAvailability do servidor de reserva retorna 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 requisitos são obrigatórios:

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

Update Booking RTU

Se uma atualização for feita em uma reserva da Central de ações (por exemplo, cancelada ou modificada) no seu sistema, um notification.partners.bookings.patch (BookingNotification.UpdateBooking) precisará ser enviado.

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": "2025-01-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 vários comerciantes e 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.

Consulte a referência a seguir para mais detalhes.

As atualizações em tempo real precisam usar a mesma estrutura de disponibilidade dos dados enviados por feeds. É necessário 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 comerciantes são afetados? Por exemplo, substitua a disponibilidade de vários comerciantes em uma solicitação.
  • Seu sistema vai sincronizar com o Google de tempos em tempos 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é 5 minutos após uma atualização no seu lado. Portanto, verifique e envie atualizações pelo menos a cada 5 minutos.
  • Nenhuma dessas opções se aplica ou você só precisa atualizar uma única loja e serviço?
    • 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 de vagas abertas

É importante usar o mesmo formato em todos os feeds, no servidor de reservas 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": 1735831800, # January 02, 2025 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 das 15h30 é reservado:

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

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": 1735831800, # January 02, 2025 15:30:00
          "duration_sec": 1800,
          "availabilityTag": "1000001"
        }
      ]

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

É importante usar o mesmo formato em todos os feeds, no servidor de reservas 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 das 15h30 é reservado é assim:

  {
    "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. Observe que é a disponibilidade total do serviço para esse comerciante e todos os schedule_exceptions anteriores e novos:

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 muda. Além disso, envie um feed de disponibilidade completo uma vez por dia para garantir que a disponibilidade seja sincronizada entre os sistemas do Google e os seus.