Você precisa criar um servidor de agendamento para permitir que o Reservar com o Google faça callbacks para criar e atualizar agendamentos em seu nome.
- Implementação padrão. Isso permite que o Reservar com o Google crie horários e agendamentos com você em nome do usuário.
Consulte a documentação do Portal de parceiros para saber como configurar a conexão com o sandbox e os servidores de reserva de produção.
Implementar uma interface da API REST
Implementar uma interface de API com base no REST. Isso permite que o Google envie solicitações do servidor de agendamento por HTTP.
Para começar, configure um servidor de reserva de desenvolvimento ou sandbox que possa ser conectado ao ambiente de sandbox do Reservar com o Google. Mude para um ambiente de produção somente depois que o servidor de sandbox for totalmente testado.
Métodos
Para cada tipo de servidor de agendamento, é necessário usar um conjunto diferente de métodos de API. Você também pode fazer 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 de serviço.
Implementação padrão |
---|
Definição de 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 espaço de inventário.
- Agendamento: um horário em um horário de inventário.
Fluxo: criar um agendamento
Nesta seção, explicamos como criar um agendamento para a implementação padrão.
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, essa reserva precisa ser tratada como uma finalização de compra sem login, porque o Reservar com o Google não pode procurar a conta do usuário no seu sistema. Verifique se a reserva final aparece idêntica às reservas dos comerciantes feitas no seu sistema.
Segurança e autenticação
Todas as comunicações com o servidor de reserva ocorrem por HTTPS. Portanto, é essencial que o servidor tenha um certificado TLS válido que corresponda ao nome DNS. Para configurar o servidor, recomendamos o uso de uma ferramenta de verificação SSL/TLS disponível publicamente, como o Qualys' SSL Server Test.
Todas as solicitações que o Google fizer para seu servidor de reserva 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 "Configuração do servidor de agendamento", no Portal de parceiros. As senhas precisam ser trocadas a cada seis meses.
Exemplos de implementações da estrutura
Para começar, veja os seguintes esqueletos de amostra de um servidor de agendamento escritos para frameworks do Node.js e Java:
- Esqueleto do Node.js js-maps-booking-rest-server-v3-bone
- Esqueleto Java java-maps-booking-rest-server-v3-bone
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 a infraestrutura ou dados incorretos
- Retorne esses erros ao cliente com os 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 da lógica de negócios no corpo da resposta. Os tipos de erro de lógica de negócios podem variar de acordo com o tipo de implementação do servidor.
- Retorne o código de status HTTP definido como
Para a implementação padrão, os possíveis erros de lógica de negócios são
capturados em
Falha na reserva 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ê processa os métodos CreateBooking
ou
UpdatingBooking
. Os exemplos incluem, entre outros:
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 fornecido não for aceito.
Idempotência
A comunicação pela rede nem sempre é confiável, e o Google pode 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
a solicitação de maneira exclusiva. Assim, é possível distinguir entre uma chamada REST repetida, com a intenção de criar uma única solicitação, e duas solicitações separadas.
UpdateBooking
é identificado exclusivamente pelos IDs de entrada do agendamento, 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 a reserva criada. Em alguns casos, o pagamento é processado como parte do fluxo de reserva. Se o mesmoCreateBookingRequest
for recebido uma segunda vez (com o mesmoidempotency_token
), o mesmoCreateBookingResponse
precisará ser retornado. Nenhuma segunda reserva é criada, e o usuário recebe uma cobrança exatamente uma vez, se aplicável.Se uma tentativa de
CreateBooking
falhar e a mesma solicitação for reenviada, o back-end tentará novamente.
O requisito de idempotência se aplica a todos os métodos que modificam o estado.