Atualizações da API em tempo real

O inventário no seu sistema oscila ao longo do dia devido a novas reservas, cancelamentos e alterações 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. Você também pode usar as atualizações em tempo real da API para informar 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 usarem 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 de forma dinâmica. Além das atualizações de API em tempo real, envie feeds de disponibilidade completos diariamente para garantir que o Google tenha o conhecimento mais preciso e atualizado da disponibilidade no seu sistema. Os feeds completos atuam como um snapshot do estado atual da disponibilidade de inventário no seu sistema.

Embora as atualizações da API possam ser usadas para atualizar qualquer informação enviada nos feeds, como dados sobre comerciantes e serviços, elas geralmente são aplicadas para a atualização 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 BookingNotification sempre que houver uma mudança 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 mudanças podem levar vários minutos para serem propagadas e refletidas.
RTU de comerciante Opcional Envie RTUs de comerciante para fazer alterações nas informações do comerciante em tempo real. As mudanças podem levar várias horas para serem propagadas e refletidas.
RTU de serviço Opcional Envie RTUs de serviço para fazer alterações nas informações do serviço em tempo real. Um caso de uso comum é quando os preços dos serviços flutuam muito ao longo do dia. É recomendável implementar RTUs de serviço para evitar falhas de pedidos devido à incompatibilidade de preços. As mudanças podem levar várias horas para serem propagadas e refletidas.

RTU da API Availability Replace

Use a API Availability 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, assim, 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 reserva retorna um inventário que não corresponde ao inventário real.

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

RTU da API Booking Notification

As APIs Booking Notification informam o Google sobre atualizações nas reservas. Ao enviar atualizações de cancelamentos, transmita apenas as informações essenciais nas solicitações 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

Criar 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ê pode definir a função 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 conferir 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 e lidam com a autorização e outros aspectos de chamadas para APIs do Google. Se necessário, confira estes exemplos.

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 comando a seguir 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, acesse estes links: Cliente de API do Ruby e Biblioteca de autenticação do Ruby.

Fazer chamadas autorizadas para a API

Ao fazer chamadas para a API, consulte Como 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,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 adiciona 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 resolver esse problema, repita a chamada em intervalos exponencialmente maiores até que ela seja bem-sucedida. Se você esgotar a cota regularmente com ReplaceServiceAvailability, mude para BatchReplaceServiceAvailabily para reduzir 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

Você pode 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. 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()