Etapa 4: implementar o servidor de agendamento

Você precisa ativar um servidor de agendamento para permitir que a Central de ações faça callbacks para criar e atualizar reservas em seu nome.

• A implementação padrão. Isso permite que a Central de ações crie horários, agendamentos e reservas com você em nome do usuário.

Consulte a documentação do Portal do parceiro para saber como configurar a conexão com seus servidores de reserva de sandbox e de produção.

Implementar uma interface da API REST

Implementar uma interface de API baseada em REST. Assim, o Google pode enviar solicitações do servidor de agendamento por HTTP.

Para começar, configure um servidor de reserva de sandbox ou de desenvolvimento que possa ser conectado ao ambiente de sandbox da Central de ações. Só mude para um ambiente de produção depois que o servidor de sandbox for totalmente testado.

Métodos

Para cada tipo de servidor de agendamento, é necessário um conjunto diferente de métodos de API. Opcionalmente, faça o download da definição do serviço no formato proto para começar a implementação da API. As tabelas a seguir mostram os métodos para cada implementação e incluem links para os formatos proto do serviço.

Implementação padrão
Definição do serviço padrão: faça o download do arquivo de definição do serviço proto.

Método	Solicitação HTTP
HealthCheck	GET /v3/HealthCheck/
BatchAvailabilityLookup	POST /v3/BatchAvailabilityLookup/
CreateBooking	POST /v3/CreateBooking/
UpdateBooking	POST /v3/UpdateBooking/
GetBookingStatus	POST /v3/GetBookingStatus/
ListBookings	POST /v3/ListBookings/

Recursos de API

Reserva

Os seguintes tipos de recurso são usados na implementação padrão:

• Slot: um slot de inventário.
• Agendamento: um horário para um horário do inventário.

Fluxo: criar um agendamento

Nesta seção, explicamos como criar um agendamento para a implementação padrão.

Figura 1: fluxo de trabalho para criar um agendamento com base em um horário disponível

Quando um usuário cria um agendamento, o Google envia o nome, sobrenome, número de telefone e e-mail dele. Do seu ponto de vista, esse agendamento precisa ser tratado como uma compra sem login, porque a Central de ações não pode procurar a conta do usuário no seu sistema. Verifique se a reserva final é idêntica às reservas dos comerciantes feitas no seu sistema.

Segurança e autenticação

Toda a comunicação com o servidor de agendamento acontece por HTTPS. Por isso, é essencial que o servidor tenha um certificado TLS válido que corresponda ao nome DNS dele. Para ajudar a configurar o servidor, recomendamos o uso de uma ferramenta de verificação SSL/TLS disponível publicamente, como o SSL Server Test da Qualys.

Todas as solicitações que o Google fizer ao seu servidor serão autenticadas usando a autenticação HTTP básica. As credenciais básicas de autenticação (nome de usuário e senha) do servidor de agendamento podem ser inseridas na página de configuração do servidor no Portal do parceiro. As senhas precisam ser alternadas a cada seis meses.

Observação:é preciso definir o nome de usuário e a senha para o sandbox e a produção separadamente usando o seletor de ambiente.

Exemplos de implementações da estrutura

Para começar, confira os seguintes exemplos de esqueleto de um servidor de agendamento escrito para frameworks Node.js e Java:

• Estrutura do Node.js js-maps-booking-rest-server-v3-skeleton
• Estrutura do Java java-maps-booking-rest-server-v3-skeleton

Esses servidores usam os métodos REST em testes.

Requisitos

Erros HTTP e de lógica de negócios

Quando seu back-end gerencia solicitações HTTP, podem ocorrer dois tipos de erro.

• Erros relacionados à infraestrutura ou a dados incorretos
  • Retorne esses erros ao cliente com códigos de erro HTTP padrão. Veja a lista completa de códigos de status HTTP.
• Erros relacionados à lógica de negócios
  • Retorne o código de status HTTP definido como 200 OK e especifique a falha de lógica de negócios no corpo da resposta. Os tipos de erro de lógica de negócios que podem ser encontrados são diferentes para os diversos tipos de implementações de servidor.

Para a implementação padrão, os possíveis erros de lógica de negócios são registrados em Falha no agendamento e retornados na resposta HTTP. Erros de lógica de negócios podem ser encontrados quando um recurso é criado ou atualizado. Por exemplo, quando você manipula os métodos CreateBooking ou UpdatingBooking. Os exemplos incluem, sem limitação, o seguinte:

• SLOT_UNAVAILABLE será usado se o slot solicitado não estiver mais disponível.
• PAYMENT_ERROR_CARD_TYPE_REJECTED será usado se o tipo de cartão de crédito informado não for aceito.

Idempotência

A comunicação pela rede nem sempre é confiável, e o Google poderá repetir solicitações HTTP se nenhuma resposta for recebida. Por esse motivo, todos os métodos que modificam o estado precisam ser idempotentes:

• CreateBooking
• UpdateBooking

Para cada mensagem de solicitação, exceto UpdateBooking, os tokens de idempotência são incluídos para identificar exclusivamente a solicitação. Isso permite distinguir entre uma chamada REST repetida, com a intenção de criar uma única solicitação, e duas solicitações separadas. UpdateBooking é identificado de maneira exclusiva pelos IDs de entrada da reserva, respectivamente. Portanto, nenhum token de idempotência é incluído nas solicitações.

Veja a seguir alguns exemplos de como os servidores de agendamento lidam com a idempotência:

• Uma resposta HTTP CreateBooking bem-sucedida inclui o agendamento criado. Em alguns casos, o pagamento é processado como parte do fluxo de reserva. Se o mesmo CreateBookingRequest for recebido uma segunda vez (com o mesmo idempotency_token), o mesmo CreateBookingResponse precisará ser retornado. O segundo agendamento não é criado, e o usuário é cobrado exatamente uma vez, se aplicável.

  Se uma tentativa CreateBooking falhar e a mesma solicitação for reenviada, o back-end precisará repetir o processo nesse caso.

O requisito de idempotência se aplica a todos os métodos que modificam o estado.