Atualizações da API em tempo real

O inventário no seu sistema oscila ao longo do dia devido a novas reservas, cancelamentos e mudanças na programação 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 as atualizações em tempo real da API para notificar o Google sobre mudanças feitas nas reservas atuais.

As atualizações em tempo real não são necessárias se todos os comerciantes usam o recurso de lista de espera.

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 à medida que ocorrem em tempo real. Além das atualizações da API em tempo real, envie feeds de disponibilidade completos diariamente para garantir que o Google tenha o conhecimento mais preciso e atual sobre a disponibilidade no seu sistema. Os feeds completos atuam como um resumo do estado atual da disponibilidade de inventário no seu sistema.

As atualizações da API podem ser usadas para atualizar qualquer informação fornecida pelos feeds, como informações sobre comerciantes e serviços, mas 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 as RTUs do BookingNotification sempre que houver uma mudança no agendamento (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 alguns minutos para serem propagadas e aplicadas.
RTU de comerciante	Opcional	Envie RTUs do comerciante para alterar as informações do comerciante em tempo real. As alterações podem levar várias horas para serem propagadas e aplicadas.
RTU de serviço	Opcional	Envie RTUs de serviço se quiser fazer alterações nas informações do serviço em tempo real. Um caso de uso comum é quando os preços dos serviços variam drasticamente durante o dia. É recomendável implementar RTUs de serviço para evitar falhas nos pedidos devido à incompatibilidade de preços. As alterações podem levar várias horas para serem propagadas e aplicadas.

RTU da API Availability Replace

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

• Um usuário faz uma reserva no seu sistema, assim 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, então o horário não está mais disponível.
• Uma reserva feita pelo Google é cancelada diretamente pelo 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 reservas 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 Notification notificam o Google sobre atualizações nas reservas atuais. Ao enviar uma atualização sobre cancelamentos, envie apenas as informações essenciais na solicitação com o parâmetro de consulta updateMask. Confira um 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 sobre 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.

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

Outras Bibliotecas de suporte estão disponíveis para download. Elas processam autorização e outros aspectos das chamadas às APIs do Google. Se necessário, consulte estes exemplos (link em inglês).

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.

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 no Ruby, siga estes links: Cliente da API Ruby e Biblioteca de autenticação Ruby.

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 sua 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 uma cota de 1.500 solicitações a cada 60 segundos ou 25 solicitações por segundo, em média. Quando uma cota é excedida (o que pode ocorrer quando você não adicionou o número correto do projeto do Google Cloud no 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 lidar com 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. Com esse método, é possível atualizar vários serviços em uma única chamada de API.

Endpoints de sandbox e produção

É possível fazer chamadas para os ambientes do sandbox e de produção usando a API. Verifique se você ativou as duas APIs no projeto do Google Cloud. Ambas as 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()