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
| Coluna | Descricao |
|---|---|
| Nome | Nome completo do hospede, com o icone de verificacao (verde = verificado, ambar = aguardando confirmacao) e o badge VIP |
| Documento | Tipo e documento mascarado (*** + ultimos 6 caracteres), com botao para revelar |
| Endereco de e-mail principal | |
| Telefone | Numero de telefone |
| Total de Estadias | Quantidade de estadias registradas |
| Total Gasto | Valor acumulado das estadias |
| Tags | Tags atribuidas ao hospede |
| Ações | Ver 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:
- Acesse Hospedes → Novo Hospede (botao na barra da listagem; aparece apenas para papeis com permissao de criar hospedes)
- Preencha os campos obrigatorios e opcionais:
Campos do cadastro
| Campo | Obrigatorio | Descricao |
|---|---|---|
| Nome | Sim | Nome completo do hospede (minimo 2 caracteres) |
| País | Nao | Pais emissor do documento (padrao: BR). Define os tipos de documento oferecidos |
| Tipo de Doc. | Nao | Opcoes conforme o pais (veja Verificacao de Documentos) |
| Documento | Nao | Numero do documento selecionado |
| Nao | Endereco de e-mail para comunicacao e verificacao | |
| Telefone | Nao | Numero com DDD e codigo do pais |
| Data de nascimento | Nao | Data de nascimento do hospede |
| Tags | Nao | Rotulos livres, separados por virgula |
- 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:
| Coluna | Descricao |
|---|---|
| Datas | Check-in → check-out |
| Status | Status da reserva (pending, confirmed, checked_in, checked_out, cancelled, no_show) |
| Total | Valor total da reserva |
Nota: Preferencias, nivel VIP e consentimento LGPD nao aparecem no perfil.
Editar Informacoes do Hospede
- Na listagem de hospedes, clique em Editar (icone de lapis) na linha do hospede
- No dialogo Editar Hóspede, modifique os campos desejados — deixe o documento em branco para manter o existente
- 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:
| Canal | Descricao |
|---|---|
| Hospede clicou no link magico enviado por e-mail | |
| SMS | Hospede digitou o codigo de 6 digitos recebido por SMS |
| Self-service | Hospede se cadastrou pelo motor de reservas (auto-verificado) |
| Legacy | Hospede 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
- Equipe cria o hospede (via dashboard ou API) → status: Nao verificado
- Sistema envia link magico (e-mail) e codigo de 6 digitos (SMS), validos por 15 minutos, para os contatos cadastrados
- 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 corporativosrepeat— hospedes recorrentesgroup-leader— lider de grupo/excursaoearly-bird— costuma reservar com antecedencialast-minute— reservas de ultima horaevento-2026— participante de evento especifico
Como usar tags
- Abra o dialogo Novo Hóspede ou Editar Hóspede
- No campo Tags, digite as tags separadas por virgula
- 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:
| Metrica | Descricao |
|---|---|
| Total de estadias | Numero de reservas concluidas (check-out realizado) |
| Total gasto | Soma de todas as diarias + servicos consumidos |
| Ultima estadia | Data 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
| Papel | Permissoes |
|---|---|
| Admin | Ve o menu Hóspedes e o botao Novo Hóspede |
| Operacional | Ve o menu Hóspedes e o botao Novo Hóspede |
| Financeiro | Ve 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)