Skip to Content
PMS CoreHóspedesPerfis de Hóspedes

Perfis de Hospedes

O perfil do hospede e o registro central que reune todas as informacoes de uma pessoa no Opero: dados pessoais, documentos, historico de estadias, preferencias e tags. Cada hospede pertence a um tenant (conta) e pode ter reservas em qualquer propriedade desse tenant — o cadastro e compartilhado entre propriedades da mesma rede.

Este guia detalha a estrutura completa do perfil, como criar e editar registros, e funcionalidades avancadas como mesclagem de duplicatas e busca.


Criando um Perfil de Hospede

Ha tres formas de criar um perfil:

  1. Manual pelo painel — Acesse Hospedes > Novo Hospede e preencha o formulario
  2. Durante uma reserva — Clique em “Criar novo hospede” no fluxo de reserva
  3. Automatico via Guest Booking Portal — Quando o hospede faz uma reserva pelo motor de reservas, o perfil e criado automaticamente e ja nasce verificado

Formulario de cadastro

O dialogo de criacao (guest-form-dialog) solicita os seguintes campos:

CampoObrigatorioDescricao
NomeSimNome completo do hospede (minimo 2 caracteres)
PaísNaoPais emissor do documento (padrao: BR)
Tipo de Doc.NaoOpcoes conforme o pais (ex.: CPF, CNPJ, RG, Passaporte ou Outro para BR)
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

Ao salvar, o sistema gera automaticamente um slug unico a partir do nome (ex: maria-silva, maria-silva-2 em caso de homonimo). O slug e um identificador interno.

Nota: Endereco, contato de emergencia, nacionalidade e validade do documento existem no cadastro, mas nao ha campos para eles no painel — nem na criacao, nem na edicao.


Campos do Perfil

O perfil completo do hospede contem os seguintes campos:

Dados pessoais

CampoTipoDescricao
nameTextoNome completo do hospede
slugTexto (auto)Identificador unico gerado a partir do nome
emailTextoEndereco de e-mail
phoneTextoTelefone com codigo do pais
birthDateDataData de nascimento
nationalityTextoPais de origem
isActiveBooleanoIndica se o perfil esta ativo (padrao: true)

Documento de identificacao

CampoTipoDescricao
documentTexto (criptografado)Numero completo do documento — armazenado com criptografia AES-256-GCM via AWS KMS
documentLast6Texto (mascarado)Ultimos 6 caracteres do documento para exibicao: ***LAST6
documentTypeTextoCodigo do tipo de documento, conforme o pais (ex.: CPF, RG, PASSPORT, DNI, CC, OTHER)
documentCountryTextoPais emissor do documento (codigo ISO)
documentExpirationDataData de validade (sem campo no painel)

Seguranca: O campo document nunca e exibido em tela. A interface mostra apenas o documentLast6 no formato ***LAST6 (ex: ***456789). Para revelar o documento completo, use o botao de revelar na coluna Documento da listagem; a acao e registrada na trilha de auditoria. Veja mais em LGPD e Privacidade.

Endereco

CampoTipoDescricao
addressJSONBObjeto com: street, number, complement, neighborhood, city, state, zip, country

Contato de emergencia

CampoTipoDescricao
emergencyContactJSONBObjeto com: name, phone, relationship

Estatisticas de Estadia

O perfil mantem tres metricas calculadas automaticamente a cada check-out:

MetricaCampoDescricao
Total de estadiasstayCountNumero de reservas concluidas (com check-out realizado)
Total gastototalSpentSoma de todas as diarias e servicos consumidos
Ultima estadialastStayDateData do check-out mais recente

Hoje essas metricas sao apenas exibidas (Total de Estadias e Total Gasto na listagem). O sistema nao as usa para calcular nivel VIP, segmentar campanhas no OCP ou gerar relatorios.

Importante: O campo totalSpent e armazenado como decimal com 2 casas (nao em centavos). A listagem exibe o valor formatado como BRL, sem centavos.


Preferencias

O campo preferences armazena em JSONB as preferencias pessoais do hospede:

PreferenciaChaveValores de exemplo
Tipo de quartoroomTypesuite, standard, dormitory
Andar preferidofloorhigh, low, any
Configuracao de camabedConfigdouble, twin, bunk
Restricoes alimentaresdietaryvegetarian, vegan, gluten-free, none
Acessibilidadeaccessibilitywheelchair, visual, hearing, none
Solicitacoes especiaisspecialRequestsTexto livre (ex: “travesseiro extra”, “longe do elevador”)

Como registrar preferencias

Hoje as preferencias so podem ser gravadas pela API (PATCH /api/tenants/:tenantId/guests/:id/preferences), que mescla os valores enviados com os ja existentes. Elas nao aparecem no painel — nem no perfil, nem no check-in, na governanca ou nas reservas.


Tags

Tags sao rotulos livres armazenados como array JSONB no perfil do hospede. Elas permitem classificar hospedes sem depender de campos fixos.

Exemplos de tags comuns

TagUso
businessViajantes corporativos
repeatHospedes recorrentes (retorno frequente)
group-leaderLider de grupo ou excursao
early-birdCostuma reservar com antecedencia
last-minuteReservas de ultima hora
evento-2026Participante de evento especifico
alta-manutencaoHospede que demanda atencao extra da equipe

Gerenciando 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. Elas ainda nao funcionam como filtro na listagem, nem na segmentacao de campanhas do OCP, nem em relatorios.


Mesclagem de Hospedes (Deduplicacao)

E comum que o mesmo hospede exista em duplicata — por exemplo, cadastrado manualmente pela recepcao e depois criado automaticamente pelo motor de reservas. O Opero oferece uma funcionalidade de merge para unificar esses registros.

Passo a passo

Hoje a mesclagem so pode ser feita pela API (o botao Mesclar da listagem ainda nao executa nenhuma acao):

POST /api/tenants/:tenantId/guests/merge Content-Type: application/json { "sourceGuestId": "<id do hospede que sera absorvido>", "targetGuestId": "<id do hospede que permanece>" }

A API recusa a mesclagem de um hospede com ele mesmo e de um hospede de origem que ja foi mesclado.

O que acontece tecnicamente

O merge envolve dois identificadores: sourceGuestId (hospede que sera absorvido) e targetGuestId (hospede que permanece ativo).

AcaoDescricao
Transferencia de reservasTodas as reservas do sourceGuestId sao reatribuidas ao targetGuestId
Combinacao de estatisticasstayCount e totalSpent sao somados; lastStayDate fica com a data mais recente dos dois registros
Dados complementaresE-mail, telefone e preferencias da origem sao copiados apenas se o destino nao os tiver; as tags sao unidas
Marcacao do registro origemO sourceGuestId recebe o campo mergedIntoId apontando para o targetGuestId e e marcado como isMerged: true e isActive: false
Preservacao do historicoO registro de origem nao e deletado fisicamente — permanece no banco para rastreabilidade
AuditoriaA operacao e registrada na trilha de auditoria com ambos os IDs, os nomes e as estatisticas combinadas

Atenção: O merge e irreversivel. Em caso de duvida, consulte o historico de estadias de ambos os registros para ter certeza de que sao a mesma pessoa.


Busca de Hospedes

No painel, o campo Buscar hóspedes… da listagem filtra apenas pelo nome.

A API (GET /api/tenants/:tenantId/guests?search=) suporta busca textual com correspondencia parcial (ILIKE) nos seguintes campos:

CampoExemplo de buscaResultado
NomeMariaEncontra “Maria Silva”, “Ana Maria Santos”
Final do e-mailil.comCompara com os ultimos 6 caracteres alfanumericos do e-mail (ex.: AILCOM em maria@gmail.com)
Ultimos 6 do documento456789Encontra hospedes cujo documentLast6 contem “456789”

A busca e case-insensitive e funciona com digitacao parcial — nao e necessario digitar o valor completo. Telefone e slug nao sao pesquisados.

Filtros avancados

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


Mascaramento de PII e Auditoria

O Opero trata dados pessoais (PII) com rigor em conformidade com a LGPD e GDPR:

Criptografia em repouso

  • Os campos document, email e phone sao criptografados com AES-256-GCM via AWS KMS antes de serem gravados no banco
  • A chave mestra fica no KMS; o servidor usa chaves de dados por conta, geradas pelo KMS e mantidas apenas em memoria
  • Mesmo com acesso direto ao banco de dados, o numero do documento e ilegivel sem a chave KMS

Mascaramento na interface

  • A interface exibe documentos no formato ***LAST6 (ex: ***456789)
  • O campo documentLast6 e armazenado separadamente para permitir busca sem descriptografar
  • A revelacao do documento completo requer acionamento de um endpoint especifico

Revelacao auditada

Para visualizar o documento completo de um hospede:

  1. Na listagem, clique no icone de olho (Revelar documento (registrado)) na coluna Documento
  2. O sistema registra na trilha de auditoria: quem solicitou, quando, de qual IP e de qual hospede (o numero revelado nao e gravado)
  3. O documento e exibido por 30 segundos e depois volta a ser mascarado (ou antes, ao clicar em Ocultar documento)

Importante: Toda revelacao de documento e registrada com proposito de compliance. Acessos frequentes ou injustificados podem ser flaggeados em auditorias internas.


Boas Praticas

  1. Cadastro completo desde o inicio — Preencha o maximo de campos possivel no primeiro contato. Perfis incompletos dificultam a operacao e a comunicacao futura.

  2. Use tags consistentes — Defina um conjunto padrao de tags com a equipe e evite variacoes (ex: nao use corporativo, business e corp para o mesmo conceito).

  3. Verifique antes de criar — Sempre busque pelo nome antes de criar um novo hospede. Duplicatas geram confusao no historico e nas estatisticas.

  4. Mescle duplicatas imediatamente — Ao identificar uma duplicata, faca o merge o quanto antes. Quanto mais reservas se acumulam em registros separados, mais confuso fica o historico.

  5. Atualize preferencias a cada estadia — Pergunte ao hospede no check-in se suas preferencias mudaram. Informacoes desatualizadas podem gerar experiencias negativas.

  6. Nao compartilhe documentos — Nunca copie ou exporte numeros de documentos fora do sistema. Use o campo mascarado (***LAST6) para comunicacao interna.

  7. Respeite o consentimento LGPD — Antes de usar dados do hospede para marketing ou comunicacao nao essencial, verifique se ha consentimento registrado. Veja LGPD e Privacidade.

  8. Mantenha tags limpas — Revise periodicamente as tags em uso. Remova tags obsoletas (ex: evento-2024) e consolide tags redundantes.

Last updated on