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 chamadaCheckAvailability
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:
-
notification.partners.bookings.patch
(BookingNotification.UpdateBooking
)
Dependendo do tipo de integração, os itens a seguir também podem estar disponíveis ou necessários:
inventory.partners.availability.replace
(InventoryUpdate.BatchServiceAvailability
) OUinventory.partners.merchants.services.availability.replace
(InventoryUpdate.ReplaceServiceAvailability
)
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.