Autenticação

Métodos de autenticação

O Opero suporta dois métodos de autenticação:

1. Bearer Token (Sessão)

Usado por aplicações frontend e integrações que atuam em nome de um usuário.

Obter um token:


POST /api/auth/sign-in/email
Content-Type: application/json
 
{
  "email": "usuario@hotel.com",
  "password": "sua-senha-segura"
}

Resposta:


{
  "token": "eyJhbGciOiJIUzI1NiJ9...",
  "user": {
    "id": "uuid-do-usuario",
    "email": "usuario@hotel.com",
    "name": "Maria Silva",
    "role": "admin"
  }
}

Usar o token:


GET /api/tenants/:tenantId/reservations
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9...

Importante: Tokens expiram após 24 horas. Use o endpoint de refresh para obter um novo token sem re-autenticar.

2. API Key

Usado por integrações servidor-a-servidor (channel managers, scripts, automações).

Criar uma API Key:

Vá em Configurações → Chaves de API
Clique “Gerar nova chave”
Defina um nome e escopo
Copie a chave (exibida apenas uma vez!)

Usar a API Key:


GET /api/tenants/:tenantId/reservations
X-API-Key: opk_live_abc123def456ghi789...

Segurança: Nunca exponha API Keys em código frontend ou repositórios públicos. Use variáveis de ambiente.

Gerenciamento de sessões

Listar sessões ativas


GET /api/auth/sessions
Authorization: Bearer <token>

Revogar uma sessão específica


DELETE /api/auth/sessions/:tokenPrefix
Authorization: Bearer <token>

Revogar todas as sessões


POST /api/auth/revoke-all
Authorization: Bearer <token>

Refresh token


POST /api/auth/refresh
Authorization: Bearer <token-expirado>

Contexto de tenant

Após autenticação, defina o tenant ativo:


PUT /api/auth/tenant-context
Authorization: Bearer <token>
Content-Type: application/json
 
{
  "tenantId": "uuid-do-tenant"
}

Isso é necessário para usuários que pertencem a múltiplos tenants.

Permissões (CASL)

A API respeita as permissões definidas pelo papel do usuário. Se um usuário com papel “Financeiro” tentar acessar um endpoint de gestão de usuários, receberá:


{
  "statusCode": 403,
  "message": "Forbidden: insufficient permissions",
  "error": "ForbiddenException"
}

Endpoints públicos (sem autenticação)

Os seguintes endpoints são acessíveis sem token — usados pelo portal de reservas público:

Método	Endpoint	Descrição
GET	`/api/public/property/:id/config`	Configuração da propriedade
GET	`/api/public/property/:id/rooms`	Lista de quartos/tarifas
GET	`/api/public/property/:id/availability`	Disponibilidade
GET	`/api/public/property/:id/gallery`	Galeria de fotos
GET	`/api/public/property/:id/payment-methods`	Métodos de pagamento
POST	`/api/public/reservations/hold`	Criar hold de reserva
POST	`/api/public/payments/create`	Processar pagamento
POST	`/api/public/reservations/confirm`	Confirmar reserva
POST	`/api/public/reservations/cancel`	Cancelar reserva
GET	`/api/public/payments/:id/status`	Status do pagamento

Exemplos de código

cURL


# Listar reservas
curl -X GET "https://api.opero.global/api/tenants/TENANT_ID/reservations?status=confirmed" \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json"

JavaScript (fetch)


const response = await fetch(
  `https://api.opero.global/api/tenants/${tenantId}/reservations`,
  {
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json',
    },
  }
);
const data = await response.json();

Python (requests)


import requests
 
response = requests.get(
    f"https://api.opero.global/api/tenants/{tenant_id}/reservations",
    headers={"Authorization": f"Bearer {token}"}
)
data = response.json()