Autenticação

O acesso é concedido por meio de uma conta de parceiro cadastrada pela HMS. A conta de parceiro recebe uma apiKey e um apiSecret, e a HMS autoriza quais hotéis ela pode acessar. O endpoint de login troca essas credenciais por um token vinculado ao hotel.

Login e token#

Requisição
POST /external/public/login HTTP/1.1
Host: test.hms.gen.tr
Content-Type: application/x-www-form-urlencoded

apiKey=5y94tLmALIKDyUVdEPlAAjg5xWGQNgQtnALlV4%2BAm7Q%3D&apiSecret=a143d640…&hotelCode=1000
Resposta · 200
{
    "success": true,
    "hotelCode": "1000",
    "token": "eyJlbmREYXRlIjp7ImRhdGUiOiIyMDI2LTA5LTE1IDEwOjI0OjMxLjAwMDAwMCIs…",
    "hotelSeoUrl": "demo-otel"
}
CampoDescrição
apiKeyChave do parceiro. Contém caracteres base64, por isso precisa ser codificada para URL em um corpo de formulário (+ → %2B, = → %3D). As bibliotecas HTTP fazem isso por você.
apiSecretChave secreta. Mantenha-a somente no servidor; nunca a inclua em um navegador ou aplicativo móvel.
hotelCodeID do hotel no HMS. Se o parceiro não tiver autorização para o hotel, é retornado hotel_permission_is_not_found.
hotelSeoUrlSlug de SEO do hotel. Usado no lugar de hotelCode apenas pelo próprio motor de reservas do HMS; integrações de terceiros enviam hotelCode.

Cabeçalho Bearer#

Todos os endpoints, exceto o login, esperam o token no cabeçalho Authorization:

Requisição
GET /external/currencies HTTP/1.1
Host: test.hms.gen.tr
Authorization: Bearer eyJlbmREYXRlIjp7ImRhdGUiOiIyMDI2LTA5LTE1IDEwOjI0OjMxLjAwMDAwMCIs…

Se o cabeçalho estiver ausente, malformado (sem o prefixo Bearer) ou o token for desconhecido, a API retorna 401:

401 Unauthorized
{
    "success": false,
    "error": "Authentication required"
}

Validade e renovação do token#

  • O token é válido por 7 dias. Renove-o fazendo login novamente antes que expire; o login é leve e pode ser repetido para o mesmo hotel.
  • Não tente interpretar o token. Embora seja uma estrutura codificada em base64, o formato não é garantido; armazene-o e repasse-o como uma string opaca.
  • Ao receber 401, faça login mais uma vez e repita a requisição; um segundo 401 indica que o par de chaves ou a autorização do hotel mudou.

Contexto do hotel#

Cada token fica vinculado a um único hotel. O parâmetro hotelID dos endpoints deve corresponder a esse hotel; consultar outro hotel resulta em erro de autorização ou em resultados vazios. Em integrações com vários hotéis, obtenha um token para cada hotel e guarde-o em cache por hotel.

Erros de login#

messageSignificado
partner_is_not_foundO par apiKey / apiSecret não confere. Verifique as chaves e a codificação de URL.
hotel_is_not_foundNenhum hotel corresponde ao hotelSeoUrl.
hotel_permission_is_not_foundO parceiro não tem autorização para este hotel, ou a autorização está inativa. Fale com o suporte da HMS.

Esses erros retornam como HTTP 200 com success: false e token: null.

Última atualização: 21 de setembro de 2026Encontrou um erro? Avise-nos