Skip to Content
PMS CoreHóspedesVisão Geral

Hospedes

O que e o Diretorio de Hospedes

O Diretorio de Hospedes e o cadastro central de todas as pessoas que ja se hospedaram ou estao cadastradas nas suas propriedades. Ele funciona como um CRM hoteleiro, armazenando informacoes de contato, historico de estadias, preferencias e status VIP.

Cada hospede pertence ao tenant (conta) e pode ter reservas em qualquer propriedade dentro dessa conta. O cadastro e compartilhado entre propriedades — ou seja, se um hospede se hospedou no Hotel A e depois no Hotel B (da mesma rede), ele aparece como um unico registro.


Acessando o Diretorio

Acesse Menu lateral → Hospedes para visualizar a lista completa de hospedes cadastrados.

Informacoes na listagem

ColunaDescricao
NomeNome completo do hospede, com o icone de verificacao (verde = verificado, ambar = aguardando confirmacao) e o badge VIP
DocumentoTipo e documento mascarado (*** + ultimos 6 caracteres), com botao para revelar
E-mailEndereco de e-mail principal
TelefoneNumero de telefone
Total de EstadiasQuantidade de estadias registradas
Total GastoValor acumulado das estadias
TagsTags atribuidas ao hospede
AçõesVer Perfil, Definir/Remover VIP, Editar, Excluir e, para hospedes nao verificados, reenviar a confirmacao

Busca e Filtros

Busca por texto

Digite no campo Buscar hóspedes… para filtrar a lista pelo nome (busca parcial — “Maria” encontra “Maria Silva” e “Ana Maria”).

Pela API (GET /api/tenants/:tenantId/guests?search=), a busca tambem encontra hospedes pelos ultimos 6 caracteres do documento ou do e-mail.

Filtros disponiveis

O unico filtro da listagem e o botao VIP only, que exibe apenas hospedes VIP.


Criar um Novo Hospede

Para cadastrar um hospede manualmente:

  1. Acesse Hospedes → Novo Hospede (botao na barra da listagem; aparece apenas para papeis com permissao de criar hospedes)
  2. Preencha os campos obrigatorios e opcionais:

Campos do cadastro

CampoObrigatorioDescricao
NomeSimNome completo do hospede (minimo 2 caracteres)
PaísNaoPais emissor do documento (padrao: BR). Define os tipos de documento oferecidos
Tipo de Doc.NaoOpcoes conforme o pais (veja Verificacao de Documentos)
DocumentoNaoNumero do documento selecionado
E-mailNaoEndereco de e-mail para comunicacao e verificacao
TelefoneNaoNumero com DDD e codigo do pais
Data de nascimentoNaoData de nascimento do hospede
TagsNaoRotulos livres, separados por virgula
  1. Clique em Salvar

O cadastro e recusado se ja existir um hospede com o mesmo e-mail ou com os mesmos ultimos 6 caracteres de documento.

Nota: Hospedes tambem sao criados automaticamente quando fazem uma reserva pelo motor de reservas (Guest Booking Portal). Nesse caso, o cadastro ja vem marcado como verificado.

Importante: Documentos de identificacao sao armazenados com criptografia AES-256 via AWS KMS. Apenas os ultimos 6 caracteres ficam visiveis para consulta rapida na interface. E-mail e telefone tambem sao criptografados no banco, mas aparecem completos para a equipe.


Detalhes do Hospede

Ao clicar em Ver Perfil (coluna de acoes da lista), voce acessa o perfil do hospede com as seguintes secoes:

Cabecalho

Nome, badge VIP (quando o hospede e VIP, sem indicar o nivel) e tags.

Informacoes pessoais

As secoes Contato (e-mail e telefone) e Informações Pessoais (documento mascarado). O perfil e somente leitura — a edicao e feita pela listagem (veja abaixo).

Historico de estadias

Tabela cronologica com todas as reservas do hospede:

ColunaDescricao
DatasCheck-in → check-out
StatusStatus da reserva (pending, confirmed, checked_in, checked_out, cancelled, no_show)
TotalValor total da reserva

Nota: Preferencias, nivel VIP e consentimento LGPD nao aparecem no perfil.


Editar Informacoes do Hospede

  1. Na listagem de hospedes, clique em Editar (icone de lapis) na linha do hospede
  2. No dialogo Editar Hóspede, modifique os campos desejados — deixe o documento em branco para manter o existente
  3. Clique em Salvar

Atenção: O botao Excluir apaga o hospede definitivamente, junto com as reservas restantes dele. A exclusao e recusada enquanto o hospede tiver reserva pendente, confirmada ou com check-in realizado.


Mesclar Hospedes Duplicados

E comum que o mesmo hospede seja cadastrado mais de uma vez (por exemplo, uma vez pelo motor de reservas e outra manualmente pela recepcao). O Opero oferece uma funcionalidade de merge para unificar esses registros.

Como funciona o merge

Hoje a mesclagem so pode ser feita pela API: POST /api/tenants/:tenantId/guests/merge com sourceGuestId (registro secundario) e targetGuestId (registro principal). O botao Mesclar da listagem ainda nao executa nenhuma acao.

O que acontece apos o merge

  • O hospede secundario e marcado como mergedIntoId (referencia ao registro principal)
  • Todas as reservas do secundario sao reatribuidas ao registro principal
  • Estatisticas (numero de estadias, total gasto) sao somadas e a ultima estadia mais recente e mantida
  • E-mail, telefone e preferencias do secundario sao copiados apenas se o principal nao os tiver; as tags sao unidas
  • O registro secundario nao e deletado fisicamente — ele fica inativo e marcado como mesclado
  • A operacao e registrada no log de auditoria

Importante: O merge e irreversivel. Confira os dois registros antes de executar.


Badge de Verificacao

O badge de verificacao indica que o hospede confirmou seus dados pessoais. Existem quatro canais de verificacao:

CanalDescricao
E-mailHospede clicou no link magico enviado por e-mail
SMSHospede digitou o codigo de 6 digitos recebido por SMS
Self-serviceHospede se cadastrou pelo motor de reservas (auto-verificado)
LegacyHospede que ja existia quando a verificacao foi introduzida (marcado como verificado automaticamente)

Por que a verificacao importa

  • Seguranca: Garante que os dados de contato sao reais
  • Confiabilidade: Reservas de hospedes verificados tem menor risco de no-show
  • LGPD: A verificacao ajuda a comprovar que o hospede e o titular dos dados

Fluxo de verificacao

  1. Equipe cria o hospede (via dashboard ou API) → status: Nao verificado
  2. Sistema envia link magico (e-mail) e codigo de 6 digitos (SMS), validos por 15 minutos, para os contatos cadastrados
  3. Hospede confirma → status: Verificado (com data e canal registrados)

Para reenviar, use o botao Reenviar e-mail de confirmação + SMS na linha do hospede (no maximo uma vez por minuto). Confirmar uma reserva pelo link enviado por e-mail tambem marca o hospede como verificado (canal e-mail).

Hospedes que se cadastram diretamente pelo motor de reservas ja nascem verificados (canal “self”).


Menores de Idade

O cadastro do hospede possui campos para menores de idade (isMinor, parentGuardianId para o responsavel legal, consentRecorded), mas hoje o Opero nao os preenche: nao ha deteccao automatica pela data de nascimento, nem tela para vincular um responsavel, nem bloqueio de comunicacoes para menores.


Tags

Tags sao rotulos livres que voce pode atribuir a hospedes para identifica-los:

Exemplos de tags comuns:

  • business — viajantes corporativos
  • repeat — hospedes recorrentes
  • group-leader — lider de grupo/excursao
  • early-bird — costuma reservar com antecedencia
  • last-minute — reservas de ultima hora
  • evento-2026 — participante de evento especifico

Como usar tags

  1. Abra o dialogo Novo Hóspede ou Editar Hóspede
  2. No campo Tags, digite as tags separadas por virgula
  3. Para remover, apague a tag do campo e salve

As tags aparecem na listagem e no perfil do hospede. Elas ainda nao podem ser usadas como filtro nem em segmentacoes de campanhas (OCP).


Estatisticas do Hospede

O Opero mantem metricas automaticas que ajudam a entender o valor do hospede:

MetricaDescricao
Total de estadiasNumero de reservas concluidas (check-out realizado)
Total gastoSoma de todas as diarias + servicos consumidos
Ultima estadiaData do check-out mais recente

Essas metricas sao atualizadas automaticamente a cada check-out. A listagem exibe Total de Estadias e Total Gasto; a ultima estadia esta disponivel apenas pela API. O Opero nao usa essas metricas para calcular nivel VIP nem para segmentar campanhas.


Quem pode gerenciar hospedes

PapelPermissoes
AdminVe o menu Hóspedes e o botao Novo Hóspede
OperacionalVe o menu Hóspedes e o botao Novo Hóspede
FinanceiroVe o menu Hóspedes, sem o botao Novo Hóspede

Atenção: Hoje os papeis controlam apenas a visibilidade do menu e do botao Novo Hóspede. Os botoes Editar, VIP, Excluir e revelar documento aparecem para qualquer usuario com acesso a listagem, e a API de hospedes aceita essas operacoes de qualquer usuario autenticado da conta.


Integracao com outros modulos

  • Reservas → Toda reserva referencia um hospede cadastrado
  • Motor de Reservas (GBP) → Criacao automatica de hospedes verificados
  • Financeiro → Contas a receber vinculadas ao hospede
  • OCP (Comunicacao) → Envio de e-mails e WhatsApp para hospedes
  • Dashboard → Contagem de hospedes atualmente hospedados (check-in realizado)
Last updated on