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:
- Manual pelo painel — Acesse Hospedes > Novo Hospede e preencha o formulario
- Durante uma reserva — Clique em “Criar novo hospede” no fluxo de reserva
- 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:
| Campo | Obrigatorio | Descricao |
|---|---|---|
| Nome | Sim | Nome completo do hospede (minimo 2 caracteres) |
| País | Nao | Pais emissor do documento (padrao: BR) |
| Tipo de Doc. | Nao | Opcoes conforme o pais (ex.: CPF, CNPJ, RG, Passaporte ou Outro para BR) |
| 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 |
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
| Campo | Tipo | Descricao |
|---|---|---|
name | Texto | Nome completo do hospede |
slug | Texto (auto) | Identificador unico gerado a partir do nome |
email | Texto | Endereco de e-mail |
phone | Texto | Telefone com codigo do pais |
birthDate | Data | Data de nascimento |
nationality | Texto | Pais de origem |
isActive | Booleano | Indica se o perfil esta ativo (padrao: true) |
Documento de identificacao
| Campo | Tipo | Descricao |
|---|---|---|
document | Texto (criptografado) | Numero completo do documento — armazenado com criptografia AES-256-GCM via AWS KMS |
documentLast6 | Texto (mascarado) | Ultimos 6 caracteres do documento para exibicao: ***LAST6 |
documentType | Texto | Codigo do tipo de documento, conforme o pais (ex.: CPF, RG, PASSPORT, DNI, CC, OTHER) |
documentCountry | Texto | Pais emissor do documento (codigo ISO) |
documentExpiration | Data | Data de validade (sem campo no painel) |
Seguranca: O campo
documentnunca e exibido em tela. A interface mostra apenas odocumentLast6no 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
| Campo | Tipo | Descricao |
|---|---|---|
address | JSONB | Objeto com: street, number, complement, neighborhood, city, state, zip, country |
Contato de emergencia
| Campo | Tipo | Descricao |
|---|---|---|
emergencyContact | JSONB | Objeto com: name, phone, relationship |
Estatisticas de Estadia
O perfil mantem tres metricas calculadas automaticamente a cada check-out:
| Metrica | Campo | Descricao |
|---|---|---|
| Total de estadias | stayCount | Numero de reservas concluidas (com check-out realizado) |
| Total gasto | totalSpent | Soma de todas as diarias e servicos consumidos |
| Ultima estadia | lastStayDate | Data 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
totalSpente 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:
| Preferencia | Chave | Valores de exemplo |
|---|---|---|
| Tipo de quarto | roomType | suite, standard, dormitory |
| Andar preferido | floor | high, low, any |
| Configuracao de cama | bedConfig | double, twin, bunk |
| Restricoes alimentares | dietary | vegetarian, vegan, gluten-free, none |
| Acessibilidade | accessibility | wheelchair, visual, hearing, none |
| Solicitacoes especiais | specialRequests | Texto 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
| Tag | Uso |
|---|---|
business | Viajantes corporativos |
repeat | Hospedes recorrentes (retorno frequente) |
group-leader | Lider de grupo ou excursao |
early-bird | Costuma reservar com antecedencia |
last-minute | Reservas de ultima hora |
evento-2026 | Participante de evento especifico |
alta-manutencao | Hospede que demanda atencao extra da equipe |
Gerenciando 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. 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).
| Acao | Descricao |
|---|---|
| Transferencia de reservas | Todas as reservas do sourceGuestId sao reatribuidas ao targetGuestId |
| Combinacao de estatisticas | stayCount e totalSpent sao somados; lastStayDate fica com a data mais recente dos dois registros |
| Dados complementares | E-mail, telefone e preferencias da origem sao copiados apenas se o destino nao os tiver; as tags sao unidas |
| Marcacao do registro origem | O sourceGuestId recebe o campo mergedIntoId apontando para o targetGuestId e e marcado como isMerged: true e isActive: false |
| Preservacao do historico | O registro de origem nao e deletado fisicamente — permanece no banco para rastreabilidade |
| Auditoria | A 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:
| Campo | Exemplo de busca | Resultado |
|---|---|---|
| Nome | Maria | Encontra “Maria Silva”, “Ana Maria Santos” |
| Final do e-mail | il.com | Compara com os ultimos 6 caracteres alfanumericos do e-mail (ex.: AILCOM em maria@gmail.com) |
| Ultimos 6 do documento | 456789 | Encontra 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,emailephonesao 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
documentLast6e 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:
- Na listagem, clique no icone de olho (Revelar documento (registrado)) na coluna Documento
- O sistema registra na trilha de auditoria: quem solicitou, quando, de qual IP e de qual hospede (o numero revelado nao e gravado)
- 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
-
Cadastro completo desde o inicio — Preencha o maximo de campos possivel no primeiro contato. Perfis incompletos dificultam a operacao e a comunicacao futura.
-
Use tags consistentes — Defina um conjunto padrao de tags com a equipe e evite variacoes (ex: nao use
corporativo,businessecorppara o mesmo conceito). -
Verifique antes de criar — Sempre busque pelo nome antes de criar um novo hospede. Duplicatas geram confusao no historico e nas estatisticas.
-
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.
-
Atualize preferencias a cada estadia — Pergunte ao hospede no check-in se suas preferencias mudaram. Informacoes desatualizadas podem gerar experiencias negativas.
-
Nao compartilhe documentos — Nunca copie ou exporte numeros de documentos fora do sistema. Use o campo mascarado (
***LAST6) para comunicacao interna. -
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.
-
Mantenha tags limpas — Revise periodicamente as tags em uso. Remova tags obsoletas (ex:
evento-2024) e consolide tags redundantes.