Atualizações da API em tempo real

O inventário no sistema oscila ao longo do dia devido a novas reservas, cancelamentos e mudanças nas programações dos comerciantes. A API de atualização em tempo real é um mecanismo para notificar o Google sobre essas mudanças na disponibilidade do inventário. Também é possível usar atualizações da API em tempo real para notificar o Google sobre alterações feitas em reservas existentes.

Feeds e atualizações em tempo real da API

As atualizações em tempo real da API são usadas para notificar o Google sobre mudanças incrementais na disponibilidade de inventário e nas reservas em tempo real. Além de atualizações da API em tempo real, envie feeds completos de disponibilidade diariamente para garantir que o Google tenha o conhecimento mais preciso e atual sobre disponibilidade no seu sistema. Os feeds completos atuam como um snapshot do estado atual da disponibilidade do inventário no sistema.

Embora as atualizações da API possam ser usadas para atualizar qualquer informação fornecida pelos feeds, como informações sobre comerciantes e serviços, elas normalmente são usadas apenas para atualizar as informações de disponibilidade.

APIs de atualização em tempo real necessárias

APIs de atualização em tempo real (RTU, na sigla em inglês)
BookingNotification	Obrigatório	Envie RTUs do BookingNotification sempre que houver uma alteração na reserva (por exemplo, modificações ou cancelamentos).
RTU de substituição de disponibilidade	Obrigatório sob certas condições[1]	Envie RTUs de substituição em lote ou substituição única para enviar atualizações à disponibilidade do inventário. As alterações podem levar vários minutos para serem propagadas e refletidas.
RTU de comerciante	Opcional	Envie RTUs de comerciante se você quiser fazer alterações nas informações do comerciante em tempo real. As alterações podem levar várias horas para serem propagadas e refletidas.
RTU de serviço	Opcional	Envie RTUs de serviço para fazer mudanças nas informações do serviço em tempo real. Um caso de uso comum é se os preços dos serviços variarem muito durante o dia. Por isso, é recomendável implementar RTUs de serviço para evitar falhas de pedidos devido à incompatibilidade de preços. As alterações podem levar várias horas para serem propagadas e refletidas.

Observação: o requisito para esse endpoint muda de acordo com a integração. Verifique com seu contato do Google para determinar quais endpoints são necessários.

RTU da API Availability Replace

Use a API Location Replace para fornecer atualizações de disponibilidade nos seguintes casos de uso:

• Um usuário reserva uma reserva no seu sistema, portanto, o horário não está mais disponível.
• Um comerciante altera a disponibilidade dele no seu sistema.
• Um usuário faz uma reserva pelo Google, portanto, o horário não está mais disponível.
• Uma reserva feita pelo Google é cancelada diretamente pelo seu comerciante, por exemplo. Você precisa atualizar a reserva e a disponibilidade, porque o horário original está disponível novamente.
• Uma chamada BatchAvailabilityLookup do servidor de reserva retorna um inventário que não corresponde ao inventário real.

Para mais informações, consulte os seguintes recursos:

• Tutorial: como estruturar atualizações em tempo real
• Exemplo de cliente Java para atualizações em tempo real usando chamadas RESTful
• Página de referência da API de atualização de inventário

RTU da API Booking Notification

As APIs Booking notificam o Google sobre atualizações em reservas existentes. Ao enviar uma atualização sobre cancelamentos, envie apenas as informações essenciais na solicitação com o parâmetro de consulta updateMask. Exemplo:

Request:
PATCH https://mapsbooking.googleapis.com/v1alpha/notification/partners/<PARTNER_ID>/bookings/<BOOKING_ID>?updateMask=status

Body:
{"name":"partners/<PARTNER_ID>/bookings/<BOOKING_ID>", "status":"CANCELED"}

Como acessar a API

Crie uma conta de serviço

Use a guia Credenciais no Console de APIs do Google para criar uma conta de serviço. Armazene a chave privada no formato JSON em um local seguro. Ao criar a conta, você tem a opção de definir o papel como "Proprietário".

Autenticar as APIs Maps Booking

Depois de criar uma conta de serviço, autentique as seguintes APIs:

• API Google Maps Booking
• API Google Maps Booking (Dev)

Para ver um guia explicativo de como fazer isso, consulte o tutorial Como autenticar com a API Maps Booking.

Usar chamadas RESTful ou fazer o download da biblioteca de cliente

Recomendamos que você faça chamadas RESTful diretamente para a API Maps Booking com payloads JSON. Para mais informações, consulte a documentação da API REST.

Você também pode usar bibliotecas de cliente para se conectar à API.

Idioma	Link de download
Java	Biblioteca de cliente Java. Para mais informações, consulte as instruções do cliente Java.

Há outras Bibliotecas de Suporte disponíveis para download que gerenciam a autorização e outros aspectos das chamadas para as APIs do Google. Se necessário, consulte estas amostras.

Buscar o documento de descoberta

Para algumas bibliotecas de cliente, como Ruby, é necessário buscar o documento de descoberta da API, que descreve os métodos e parâmetros dela.

Use o seguinte comando para buscar o documento de descoberta:

curl -s -o 'mapsbooking_rest' 'https://mapsbooking.googleapis.com/$discovery/rest?version=v1alpha'

Para mais informações sobre como acessar a API pelo Ruby, siga estes links: Cliente da API Ruby e Biblioteca Ruby Auth.

Fazer chamadas autorizadas para a API

Ao fazer chamadas para a API, consulte Como se preparar para fazer uma chamada de API autorizada para autorizar a conta de serviço com a chave privada e o seguinte escopo do OAuth: https://www.googleapis.com/auth/mapsbooking.

Cotas da API

As atualizações da API têm,em média, uma cota de 1.500 solicitações a cada 60 segundos ou 25 solicitações por segundo. Quando uma cota é excedida (o que pode ocorrer quando você não adicionou o número correto do projeto do Google Cloud ao Portal do parceiro), o Google responde com a seguinte mensagem de erro:

{
  "error": {
    "code": 429,
    "message": "Insufficient tokens for quota ...",
    "status": "RESOURCE_EXHAUSTED",
    "details": [...]
  }
}

Para resolver isso, tente fazer a chamada novamente em intervalos exponencialmente maiores até que ela seja bem-sucedida. Se você esgotar a cota regularmente com ReplaceServiceAvailability, mude para BatchReplaceServiceAvailabily e reduza o número de chamadas de API. Esse método permite atualizar vários serviços em uma única chamada de API.

Endpoints de sandbox e produção

É possível fazer chamadas para os ambientes de sandbox e de produção usando a API. Verifique se você ativou as duas APIs no projeto do Google Cloud. As duas APIs usam o mesmo escopo, mas têm endpoints diferentes.

Endpoint de produção: https://mapsbooking.googleapis.com/

Endpoint de sandbox: https://partnerdev-mapsbooking.googleapis.com/

Veja a seguir um exemplo em Java de como alternar endpoints:

    // This block of code is for OAuth and is the same for prod and sandbox.
    GoogleCredential
      .fromStream(new FileInputStream(...))
      .createScoped(Collections.singleton("https://www.googleapis.com/auth/mapsbooking"))

    // This block of code sets the endpoint. This is what you'd change to connect to the sandbox.
    new GoogleMapsBookingAPI.Builder(...)
      .setApplicationName(...)
      .setRootUrl("https://partnerdev-mapsbooking.googleapis.com/") // you add this to change the endpoint to use partnerdev.
      .build()