Trilha de Auditoria
A trilha de auditoria registra automaticamente toda acao relevante realizada no sistema. Cada criacao, edicao ou exclusao de dados gera um registro imutavel que pode ser consultado a qualquer momento para fins de compliance, investigacao e transparencia.
Por que Auditar?
A auditoria e essencial para:
- Compliance — Atender requisitos de LGPD, GDPR e normas contabeis (IFRS, USALI)
- Seguranca — Detectar acessos indevidos ou acoes suspeitas
- Investigacao — Rastrear quem fez o que e quando em caso de incidentes
- Transparencia — Dar visibilidade a gestores sobre acoes da equipe
- Reversao — Entender o estado anterior de um registro antes de uma alteracao
O que e Registrado
Toda mutacao (criacao, atualizacao ou exclusao) em entidades de negocio gera um registro de auditoria. Alguns exemplos:
| Acao | Entidade | Exemplo |
|---|---|---|
| CREATE | Reserva | ”Usuario Maria criou a reserva #RES-2026-001847” |
| UPDATE | Hospede | ”Usuario Joao atualizou o telefone do hospede Carlos Silva” |
| DELETE | Lancamento | ”Usuario Ana excluiu o lancamento contabil #LC-00412” |
| REVERSE | Movimentacao | ”Usuario Pedro estornou a movimentacao de caixa #MV-00198” |
| READ | Tenant (N2) | “Superuser N2 acessou dados do tenant Hotel Solar” |
Nota: Leituras normais (GET) nao sao registradas para evitar volume excessivo. A excecao sao acessos de suporte (N2), que registram toda leitura cross-tenant.
Campos do Registro
Cada entrada na trilha de auditoria contem:
| Campo | Descricao | Exemplo |
|---|---|---|
id | Identificador unico do registro (UUIDv7, ordenavel por tempo) | 019...abc |
tenantId | Tenant onde a acao ocorreu (nulo para acoes cross-tenant N2) | tenant-uuid |
tableName | Nome da tabela/entidade afetada | reservations |
recordId | ID do registro criado, editado ou excluido | record-uuid |
action | Tipo da acao | CREATE, UPDATE, DELETE, REVERSE, READ |
userId | ID do usuario que realizou a acao | user-uuid |
superuserLevel | Se a acao foi de um superuser: n1 ou n2 | n1 |
origin | Origem da acao | API, INTEGRATION, AUTOMATION, SYSTEM, SUPERUSER |
oldValue | Estado anterior do registro (para UPDATE e DELETE) | { "status": "pending" } |
newValue | Novo estado do registro (para CREATE e UPDATE) | { "status": "confirmed" } |
ipAddress | IP de origem da requisicao | 189.40.72.15 |
userAgent | Navegador/cliente que realizou a acao | Mozilla/5.0... |
createdAt | Data/hora exata da acao | 2026-05-26T14:30:00Z |
Protecao de Dados Pessoais (PII)
A trilha grava os valores que cada modulo registra (oldValue / newValue); nao ha mascaramento automatico de dados pessoais nos registros de auditoria. Os dados pessoais de hospedes sao criptografados no proprio cadastro, e toda revelacao do documento de um hospede gera um registro READ. Numeros de cartao nunca sao registrados.
Imutabilidade
Registros de auditoria sao imutaveis por design:
- Nao podem ser editados, nem por administradores
- Nao podem ser excluidos, nem por superusuarios N1
- A tabela nao possui operacao UPDATE nem DELETE na API
- IDs usam UUIDv7 (ordenados por tempo), garantindo sequenciamento
Importante: A unica remocao de registros e a rotina automatica de retencao (veja Retencao), que apaga diariamente os registros mais antigos que o periodo contratado.
Como Consultar
Via Interface
- Acesse Configuracoes > Log de Auditoria (requer papel Admin)
- Use os filtros disponiveis:
| Filtro | Descricao |
|---|---|
| Periodo | Data inicial e final |
| Usuario | Quem realizou a acao |
| Entidade | Tabela afetada (reservas, hospedes, financeiro, etc.) |
| Acao | CREATE, UPDATE, DELETE, REVERSE |
- Clique em uma linha para expandir os detalhes (valores anteriores e novos)
Via API
A API aceita tambem os filtros recordId e userId:
GET /api/tenants/:tenantId/audit/logs?tableName=reservations&action=UPDATE&startDate=2026-05-01&endDate=2026-05-31
Authorization: Bearer <token>Origens das Acoes
| Origem | Descricao |
|---|---|
API | Acao realizada via interface web (dashboard) |
INTEGRATION | Acao originada por integracao via chave de API |
AUTOMATION | Acao automatica do sistema (ex: no-show automatico, depreciacao programada) |
SYSTEM | Operacao interna do sistema (ex: seed de dados, migracoes) |
SUPERUSER | Acao de um superuser N1 ou N2 |
Casos de Uso Comuns
Quem cancelou uma reserva?
Filtre por tableName = reservations, action = UPDATE, e procure por registros onde newValue.status = "cancelled". O campo userId mostra quem fez a acao e createdAt mostra quando.
Quando um usuario foi alterado?
Filtre por tableName = users e recordId = <id-do-usuario>. A trilha mostra todas as alteracoes, incluindo mudanca de papel (role).
O suporte Opero acessou meus dados?
Filtre por origin = SUPERUSER. Toda acao de N1/N2 e registrada com o campo superuserLevel preenchido.
Rastrear alteracoes financeiras
Filtre por tableName em (accrual_entries, cash_movements, accounts_payable, etc.) para ver todas as operacoes financeiras e quem as realizou.
Retencao
Os registros de auditoria sao mantidos por 30 dias em todos os planos. Para guardar por mais tempo, contrate na Loja a retencao de 1 ano (audit.retention_1y) ou ilimitada (audit.retention_unlimited). Apos o periodo de retencao, uma rotina diaria apaga os registros antigos.
Permissoes
| Papel | Acesso a Trilha de Auditoria |
|---|---|
| Admin / Tenant Admin | Leitura completa |
| Financeiro | Sem acesso |
| Operacional | Sem acesso |
| POS / Fornecedores | Sem acesso |
| Superuser N1 | Leitura completa (cross-tenant) |
| Superuser N2 | Leitura (se acesso de suporte aprovado) |