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.
- Implementação das listas de espera de reservas: Usado quando você participa do programa piloto de listas de espera de reservas. Isso permite que a central de ações recupere estimativas de espera e crie entradas da lista de espera em nome do usuário.
- 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. Se quiser implementar um servidor de agendamento para a integração completa das reservas, consulte Implementar o servidor de agendamento de horá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 da lista de espera |
---|
Definição do serviço de lista de espera. Faça o download do arquivo de definição do serviço proto. |
Método | Solicitação HTTP |
---|---|
HealthCheck | GET /v3/HealthCheck/ |
BatchGetWaitEstimates | POST /v3/BatchGetWaitEstimates/ |
CreateWaitlistEntry | POST /v3/CreateWaitlistEntry/ |
GetWaitlistEntry | POST /v3/GetWaitlistEntry/ |
DeleteWaitlistEntry | POST /v3/DeleteWaitlistEntry/ |
Recursos de API
Waitlist
Estes recursos são usados para implementar o agendamento por lista de espera:
- WaitEstimate: uma estimativa de espera para um tamanho de grupo e um comerciante específicos.
- WaitlistEntry: a entrada de um usuário na lista de espera.
Fluxo: criar uma entrada da lista de espera
Nesta seção, explicamos como criar um agendamento para a integração das listas de espera de reservas.
![Figura 2: fluxo de trabalho para criar uma entrada da lista de espera](https://developers.google.cn/static/actions-center/images/waitlists/rest_api_v3_waitlist_flow.png?authuser=3&hl=pt)
Quando o usuário cria uma entrada da lista de espera, o Google envia o nome, sobrenome, número de telefone e e-mail dele. O e-mail é igual ao da Conta do Google do usuário e é tratado como um identificador exclusivo. Você precisa tratar essa lista de espera como uma compra sem login, porque o Reservar com o Google não pode procurar a conta do usuário no seu sistema. Verifique se a entrada final da lista de espera é idêntica às entradas dos comerciantes provenientes do seu sistema de lista de espera.
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 sem custo financeiro, 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.
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.
- Retorne o código de status HTTP definido como
Na integração de listas de espera de reservas, os erros de lógica de negócios são registrados em Falha de lógica de negócios na lista de espera e retornados na resposta HTTP. Erros de lógica de negócios podem ser encontrados quando um recurso é
criado, por exemplo, ao processar o método
CreateWaitlistEntry
. Os exemplos incluem, entre outros:
ABOVE_MAX_PARTY_SIZE
é usado quando a entrada da lista de espera excede o tamanho máximo de grupo permitido pelo comerciante.MERCHANT_CLOSED
é usado quando a lista de espera não está aberta porque o comerciante já está fechado.
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:
CreateWaitlistEntry
DeleteWaitlistEntry
Para cada mensagem de solicitação, exceto DeleteWaitlistEntry
, 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.
DeleteWaitlistEntry
é identificado
de forma exclusiva pelos IDs de entrada da lista de espera, 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
CreateWaitlistEntry
bem-sucedida inclui o ID da entrada da lista de espera criada. Se o mesmoCreateWaitlistEntryRequest
for recebido uma segunda vez (com o mesmoidempotency_token
), o mesmoCreateWaitlistEntryResponse
precisará ser retornado. Nenhuma segunda entrada da lista de espera será criada, e nenhum erro será retornado.Se uma tentativa
CreateWaitlistEntry
falhar e a mesma solicitação for reenviada, o back-end deverá tentar novamente.
O requisito de idempotência se aplica a todos os métodos que modificam o estado.