Conexão à API pública

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

  1. Abra o Postman e crie uma nova solicitação (request).

  2. 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 o Access Key ou o ID 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.

  1. No Postman, configure a solicitação para o endpoint GetSurveysByProduct.

  2. Na seção de parâmetros, adicione:

    • Access Key: com o valor do seu Access Key do hotel.

    • product name: com o valor follow up ou on-site, dependendo do produto que você deseja consultar.

  3. 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.

  1. No Postman, crie uma nova solicitação para o endpoint GetServiceStructure.

  2. 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.

  3. 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.

  1. Crie uma nova solicitação no Postman para o endpoint GetServiceAnswers.

  2. 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.

  3. 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.

  1. Crie uma nova solicitação no Postman para o endpoint GetSurveyAnswerDetails.

  2. Na seção de parâmetros, adicione:

    • AnswersID: o ID da resposta que você copiou do passo anterior.

    • survey ID: o ID da pesquisa.

  3. 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.

  1. Crie uma nova solicitação no Postman para o endpoint GetSurveyNPS.

  2. 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.

  3. 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.

  1. 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.

  2. Selecione a linguagem de programação que você deseja (PHP, Node.js, Java, C#, etc.).

  3. 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.