Este procedimento detalha os passos para se conectar à API pública do MyHotel e obter dados, usando o Postman como ferramenta de teste e visualização.
Esta função está disponível para usuários com perfil de Administrador, Coordinador e Consultor.
Procedimento: Conexão e Uso da API Pública do MyHotel
Requisitos Prévios
Antes de começar, certifique-se de ter o seguinte:
-
Um Access Key do hotel ao qual você deseja acessar.
-
Um X-API Key, fornecido pelo MyHotel para a sua rede ou hotel.
-
Um usuário com credenciais de acesso à propriedade (nome de usuário e senha).
-
A ferramenta Postman instalada para realizar os testes.
Passo 1: Configuração Inicial no Postman
-
Abra o Postman e crie uma nova solicitação (
request
). -
Para cada
endpoint
que você for consultar, você deverá configurar os seguintes elementos em sua solicitação:-
Authorization (Autorização): Insira as credenciais do seu usuário (nome de usuário e senha).
-
Headers (Cabeçalhos): Adicione um novo
header
chamado X-API-Key e atribua o valor que lhe foi fornecido. -
Parâmetros (Parameters/Path Variables): Adicione os parâmetros exigidos por cada
endpoint
, como oAccess Key
ou oID
de pesquisas.
-
Passo 2: Obter as Pesquisas Disponíveis
O primeiro endpoint
que você deve consultar é o GetSurveysByProduct
. Este lhe permitirá obter uma lista de todas as pesquisas disponíveis para um produto específico.
-
No Postman, configure a solicitação para o
endpoint
GetSurveysByProduct
. -
Na seção de parâmetros, adicione:
-
Access Key
: com o valor do seu Access Key do hotel. -
product name
: com o valorfollow up
ouon-site
, dependendo do produto que você deseja consultar.
-
-
Clique em Send.
-
Resultado: A API retornará um JSON com uma lista de pesquisas, incluindo seus nomes, traduções e um ID de pesquisa (
survey base ID
), que você precisará para os próximos passos.
Passo 3: Obter a Estrutura de uma Pesquisa
Uma vez que você tenha o ID
da pesquisa, você pode usar o endpoint
GetServiceStructure
para obter os detalhes de sua estrutura.
-
No Postman, crie uma nova solicitação para o
endpoint
GetServiceStructure
. -
Na seção de parâmetros, adicione:
-
Access Key
: o Access Key do seu hotel. -
survey base ID
: o ID que você obteve no passo anterior.
-
-
Clique em Send.
-
Resultado: A API lhe devolverá um JSON com a estrutura completa da pesquisa, incluindo suas seções e perguntas.
Passo 4: Obter as Respostas de uma Pesquisa
Para obter as respostas de uma pesquisa em um período de tempo específico, use o endpoint
GetServiceAnswers
.
-
Crie uma nova solicitação no Postman para o
endpoint
GetServiceAnswers
. -
Na seção de parâmetros, adicione:
-
Access Key
: o Access Key do hotel. -
survey ID
: o ID da pesquisa. -
start date
: a data de início do período de busca. -
end date
: a data de término do período de busca.
-
-
Clique em Send.
-
Resultado: A API lhe devolverá um JSON com uma lista de respostas para esse período, cada uma com um ID de resposta (
AnswersSurvey ID
).
Passo 5: Ver o Detalhe de uma Resposta Específica
Se você precisar ver o detalhe de uma resposta em particular, use o endpoint
GetSurveyAnswerDetails
.
-
Crie uma nova solicitação no Postman para o
endpoint
GetSurveyAnswerDetails
. -
Na seção de parâmetros, adicione:
-
AnswersID
: o ID da resposta que você copiou do passo anterior. -
survey ID
: o ID da pesquisa.
-
-
Clique em Send.
-
Resultado: A API lhe devolverá um JSON com os detalhes completos dessa resposta específica.
Passo 6: Obter o NPS de uma Pesquisa
Para obter a pontuação de NPS (Net Promoter Score) para uma pesquisa e um período de tempo, use o endpoint
GetSurveyNPS
.
-
Crie uma nova solicitação no Postman para o
endpoint
GetSurveyNPS
. -
Na seção de parâmetros, adicione:
-
Access Key
: o Access Key do hotel. -
start date
: a data de início do período. -
end date
: a data de término do período. -
survey ID
: o ID da pesquisa.
-
-
Clique em Send.
-
Resultado: A API lhe devolverá um JSON com o NPS, o número de promotores, passivos e detratores, e o total de respostas para o período selecionado.
Recomendação Adicional: Gerar Código para sua Aplicação
O Postman permite que você gere o código das chamadas à API em diversas linguagens de programação.
-
Uma vez que você tenha verificado que sua solicitação funciona corretamente no Postman, clique no botão Code (Código) que se encontra no lado direito da interface.
-
Selecione a linguagem de programação que você deseja (PHP, Node.js, Java, C#, etc.).
-
Copie o código gerado e cole-o em sua aplicação para integrar a API.
Com estes passos, você pode consultar toda a informação que precisar da API pública do MyHotel.