Voltar a Central de Ajuda
Integrações

API de Hospedagem

Como o sistema do hotel (PMS) cadastra hóspedes e libera o acesso Wi-Fi automaticamente: geração da chave, endpoints, exemplos e o fluxo de login do hóspede.

30/08/2026 13 visualizacoes Destacado

O que esta API faz

Permite que o sistema do hotel (PMS) cadastre hóspedes e libere o acesso Wi-Fi automaticamente, sem que ninguém precise abrir o painel. O hóspede entra na rede com um usuário definido pelo hotel — número do quarto, código da reserva, o que você preferir — e uma senha.

A credencial pertence à estadia, não à pessoa. No check-out ela é apagada: quem não está hospedado não tem usuário. O cadastro da pessoa permanece, para o histórico e para reencontrá-la numa próxima estadia.

1. Gerando a chave de API

  1. No painel, abra Integrações.
  2. Localize API de Hospedagem e clique em configurar.
  3. Ative a integração.
  4. No bloco Chaves de API, dê um nome (ex.: PMS do hotel) e clique em Gerar chave.
  5. Copie a chave imediatamente.

A chave é exibida uma única vez. O sistema guarda apenas um resumo criptográfico dela — nem o suporte consegue recuperá-la depois. Se você perder a chave, gere outra e revogue a anterior.

Cada chave mostra na tela seu prefixo e a data do último uso, o que ajuda a identificar qual está em uso antes de revogar.

2. Autenticação

Toda requisição leva a chave no cabeçalho:

Authorization: ApiKey wlk_SUA_CHAVE_AQUI

Respostas de erro relacionadas à chave:

  • 401 — chave ausente, inválida ou revogada.
  • 429 — excesso de requisições. Reduza a frequência das chamadas.

A chave define sozinha a que empresa os dados pertencem. Você nunca informa identificador de empresa nas chamadas — e não consegue enxergar dados de outro cliente, mesmo conhecendo os identificadores dele.

3. O fluxo, em ordem

Uma vez, na implantação:
  GET /api/public/v1/hotspots
     -> guarde o "estabelecimento" (identificador do ponto de acesso)

A cada hóspede:
  1. GET  /api/public/v1/guests/lookup?documento=XXX
        vazio            -> hóspede novo   -> POST /guests
        encontrou alguém -> hóspede já existe -> POST /guests com o "id"

  2. No check-out:
        PUT /api/public/v1/guests/{id}   com  "checkout": true

A consulta prévia é um recurso, não uma obrigação: você pode cadastrar direto. Ela existe para evitar duplicar a mesma pessoa e para reencontrar um hóspede quando o PMS não guardou o id.

A decisão é sua, não da API. Documento é um identificador forte, mas não infalível — pode haver erro de digitação, ou o mesmo documento cadastrado com nomes diferentes. Quem tem o hóspede na frente é a recepção.

4. Endpoints

GET /api/public/v1/hotspots

Lista os pontos de acesso da sua empresa. Faça esta chamada primeiro: o valor de estabelecimento é obrigatório no cadastro de hóspedes, e só aqui você o obtém. 

curl -X GET "https://SEU-DOMINIO/api/public/v1/hotspots" \
  -H "Authorization: ApiKey wlk_SUA_CHAVE_AQUI"
{
  "success": true,
  "data": [
    {
      "estabelecimento": "a1b2c3d4e5f6",
      "nome_fantasia": "Hotel Exemplo",
      "local": "Recepção",
      "endereco": {
        "logradouro": "Rua das Flores",
        "numero": "100",
        "bairro": "Centro",
        "cidade": "São Paulo",
        "estado": "SP",
        "cep": "01000-000"
      },
      "modelo": "mikrotik",
      "mac": "AA:BB:CC:DD:EE:FF",
      "ip": "10.0.0.1",
      "ativo": true
    }
  ]
}

Se o hotel tiver vários pontos de acesso (recepção, restaurante, andares) usando a mesma licença, todos compartilham o mesmo estabelecimento e um único cadastro vale em todos eles. Se forem licenças distintas, cada ponto tem seu próprio identificador e o hóspede precisa ser cadastrado em cada um.

GET /api/public/v1/guests/lookup

Procura hóspedes já cadastrados com aquele documento.

curl -X GET "https://SEU-DOMINIO/api/public/v1/guests/lookup?documento=AB123456" \
  -H "Authorization: ApiKey wlk_SUA_CHAVE_AQUI"
{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "nome": "João da Silva",
      "documento": "AB123456",
      "tipo_documento": "OUTRO"
    }
  ]
}

Lista vazia ("data": []) significa hóspede novo — é resposta normal, não erro. A busca ignora maiúsculas/minúsculas e espaços nas pontas.

A resposta traz apenas o mínimo para você reconhecer a pessoa. Telefone, e-mail e endereço não são retornados.

POST /api/public/v1/guests

Cadastra o hóspede e abre a estadia.

CampoObrigatórioObservação
estabelecimentoSimObtido em /hotspots
loginSimO que o hóspede vai digitar (quarto, reserva…)
senhaSimEm texto puro; é armazenada com hash
nomeSim
documentoSimCPF, CNPJ ou documento estrangeiro
tipo_documentoSimCPF, CNPJ ou OUTRO
liberado_ateSimData/hora do check-out, em ISO 8601
idNãoInforme para reaproveitar um cadastro vindo do lookup
email, telefoneNão
curl -X POST "https://SEU-DOMINIO/api/public/v1/guests" \
  -H "Authorization: ApiKey wlk_SUA_CHAVE_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "estabelecimento": "a1b2c3d4e5f6",
    "login": "101",
    "senha": "bemvindo2026",
    "nome": "João da Silva",
    "documento": "AB123456",
    "tipo_documento": "OUTRO",
    "liberado_ate": "2026-09-05T12:00:00"
  }'
{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "nome": "João da Silva",
    "documento": "AB123456",
    "tipo_documento": "OUTRO",
    "estabelecimento": "a1b2c3d4e5f6",
    "login": "101",
    "liberado_ate": "2026-09-05T12:00:00.000Z"
  }
}

Guarde o id. É com ele que você estende a estadia ou faz o check-out. Perdido, recupere-o pelo lookup.

Reutilizar o mesmo login é esperado. Se o quarto 101 já tiver uma estadia ativa, ela é encerrada no mesmo instante em que a nova é criada — o hóspede anterior perde o acesso mesmo sabendo a senha antiga. É exatamente o comportamento de um hotel.

Sobre o documento: a estrutura não é validada. Um passaporte como AB123456 é aceito e gravado como você enviou. Use tipo_documento: "OUTRO" para hóspedes estrangeiros.

PUT /api/public/v1/guests/{id}

Atualiza dados, estende a estadia ou faz o check-out.

Ao mexer na estadia (login, senha, liberado_ate ou checkout), o campo estabelecimento passa a ser obrigatório: a mesma pessoa pode estar vinculada a mais de um ponto, e é preciso dizer qual estadia alterar.

Estender a hospedagem:

curl -X PUT "https://SEU-DOMINIO/api/public/v1/guests/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: ApiKey wlk_SUA_CHAVE_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "estabelecimento": "a1b2c3d4e5f6",
    "liberado_ate": "2026-09-08T12:00:00"
  }'

Check-out:

curl -X PUT "https://SEU-DOMINIO/api/public/v1/guests/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: ApiKey wlk_SUA_CHAVE_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "estabelecimento": "a1b2c3d4e5f6",
    "checkout": true
  }'

O check-out apaga usuário e senha da estadia. O cadastro da pessoa e o histórico de acessos permanecem.

GET /api/public/v1/visits

Lista os acessos em um período.

curl -X GET "https://SEU-DOMINIO/api/public/v1/visits?from=2026-09-01&to=2026-09-30" \
  -H "Authorization: ApiKey wlk_SUA_CHAVE_AQUI"
{
  "success": true,
  "data": [
    {
      "id": 12345,
      "hospede_id": "550e8400-e29b-41d4-a716-446655440000",
      "data": "2026-09-03T14:22:10.000Z",
      "duracao_minutos": 60,
      "metodo": "hospedagem",
      "estabelecimento": "a1b2c3d4e5f6",
      "nome_fantasia": "Hotel Exemplo",
      "identificacao": "Hospedagem: 101"
    }
  ],
  "meta": { "limit": 500, "offset": 0, "count": 1 }
}

Parâmetros opcionais: limit (máximo e padrão 500) e offset, para paginar.

Esta listagem devolve deliberadamente o mínimo: não inclui documento, telefone ou e-mail. Os dados são dos titulares, e uma consulta de volume não é motivo para exportá-los. Para dados cadastrais, use o lookup, um hóspede por vez.

5. Como o hóspede entra na rede

  1. Conecta-se ao Wi-Fi e a tela de acesso abre.
  2. Escolhe a opção de hóspede.
  3. Digita o usuário e a senha que a recepção informou.
  4. Entra direto — sem preencher cadastro, já que o hotel enviou os dados.

Para que a opção apareça, o modo hospedagem precisa estar ativado no ponto de acesso, em Aparelhos → Editar → Hospedagem. O texto do botão é configurável nos rótulos do portal (ex.: "Quarto e Senha").

O acesso deixa de funcionar sozinho quando liberado_ate passa — não é preciso fazer nada no vencimento. O check-out apenas antecipa isso.

6. Gerenciando pelo painel

Os hóspedes cadastrados pela API aparecem em Visitantes, onde a recepção pode consultar, corrigir dados, trocar a senha ou ajustar a validade sem depender do PMS.

Na ficha de cada hóspede, a aba de acessos mostra o quarto usado em cada conexão — inclusive depois do check-out, quando a credencial já não existe mais.

7. Erros comuns

SituaçãoRespostaO que fazer
Chave ausente, inválida ou revogada 401 Confira o cabeçalho Authorization: ApiKey ...
Faltou um campo obrigatório 400 A resposta indica o campo em field
tipo_documento fora da lista 400 Use CPF, CNPJ ou OUTRO
Identificador de ponto de acesso desconhecido 404 Consulte /hotspots; ele pode ter mudado
PUT em hóspede sem vínculo com o ponto 404 Use POST para abrir a estadia naquele ponto
Hóspede diz que a senha não funciona — Verifique se liberado_ate já passou, ou se o mesmo quarto foi cadastrado para outra pessoa depois
Muitas requisições 429 Espere e reduza a frequência

Recomendações de segurança

  • Guarde a chave no cofre de segredos do PMS, nunca no código-fonte.
  • Use uma chave por sistema integrado: revogar uma não derruba as outras.
  • Evite senhas previsíveis, como só o número do quarto ou só o CPF.
  • Faça o check-out no PMS assim que o hóspede sai — é o que corta o acesso na hora.
Ultima atualizacao: 30/08/2026
Voltar a Central de Ajuda
Precisa de mais ajuda? Explore nossa base de conhecimento

WiFi Liberado - Central de Ajuda