Chaves de API

As chaves de API permitem que sistemas externos acessem os dados do seu tenant de forma programatica, sem a necessidade de login interativo. Sao ideais para integracoes com ERPs, channel managers, sistemas de BI e automacoes.

Requisitos

O acesso via API e controlado pelo sistema de Entitlements:

Feature	Plano	Escopo
`api.read_only`	Professional+	Leitura de dados (GET)
`api.read_write`	Enterprise (ou add-on)	Leitura + escrita (GET, POST, PUT, DELETE)

Se o seu plano nao inclui acesso a API, voce pode adquirir o add-on na Loja Opero.

Como Criar uma Chave

Acesse Configuracoes > Chaves de API
Clique em “Nova Chave”
Preencha:
- Label — nome descritivo (ex: “Integracao Power BI”, “Channel Manager”)
- Escopo — READ_ONLY ou READ_WRITE
Clique em “Gerar”
Copie a chave imediatamente — ela sera exibida apenas uma vez

Atenção: A chave completa e exibida somente no momento da criacao. Apos fechar o dialogo, apenas o prefixo (12 primeiros caracteres) fica visivel para identificacao. Se voce perder a chave, sera necessario gerar uma nova.

Seguranca das Chaves

O Opero adota praticas rigorosas de seguranca para chaves de API:

Aspecto	Como funciona
Armazenamento	Apenas o hash SHA-256 da chave e armazenado no banco. O texto original nunca e salvo.
Identificacao	O prefixo (12 caracteres) e salvo separadamente para exibicao na UI.
Transmissao	Chaves devem ser enviadas no header `Authorization: Bearer <chave>` via HTTPS.
Auditoria	Toda requisicao via API key e registrada com IP, user-agent e timestamp.
Ultimo uso	A coluna “Ultimo uso” mostra quando a chave foi utilizada pela ultima vez.

Escopos

Escopo	Metodos HTTP	Descricao
READ_ONLY	`GET`	Consulta de dados: reservas, hospedes, financeiro, propriedades. Nao permite criacao, edicao ou exclusao.
READ_WRITE	`GET`, `POST`, `PUT`, `DELETE`	Acesso completo a API. Permite criar reservas, registrar pagamentos, atualizar hospedes, etc.

Nota: Mesmo com escopo READ_WRITE, a chave respeita os limites do tenant. Nao e possivel acessar dados de outro tenant via API.

Gerenciar Chaves

Listar Chaves Ativas

Em Configuracoes > Chaves de API, voce ve todas as chaves do tenant:

Coluna	Descricao
Label	Nome descritivo da chave
Prefixo	Primeiros 12 caracteres (para identificacao)
Escopo	`READ_ONLY` ou `READ_WRITE`
Criada em	Data de criacao
Ultimo uso	Data/hora da ultima requisicao com esta chave
Status	Ativa ou Revogada

Revogar uma Chave

Localize a chave na lista
Clique no menu de contexto (tres pontos)
Selecione “Revogar”
Confirme a acao

A revogacao e imediata e irreversivel. Qualquer sistema que esteja usando esta chave deixara de funcionar instantaneamente.

Dica: Antes de revogar, certifique-se de que nenhuma integracao critica depende desta chave. Crie a nova chave primeiro, atualize as integracoes e so entao revogue a antiga.

Usando a Chave na API

Autenticacao

Inclua a chave no header de autorizacao:


GET /api/reservations
Authorization: Bearer opk_a1b2c3d4e5f6...
Content-Type: application/json

Resposta de Erro (Chave Invalida)


{
  "statusCode": 401,
  "message": "Invalid or revoked API key",
  "error": "Unauthorized"
}

Resposta de Erro (Escopo Insuficiente)


{
  "statusCode": 403,
  "message": "API key scope READ_ONLY does not allow POST",
  "error": "Forbidden"
}

Rotacao de Chaves

Recomendamos a rotacao periodica das chaves de API para minimizar riscos:

Crie uma nova chave com o mesmo escopo
Atualize as integracoes para usar a nova chave
Monitore por alguns dias para confirmar que tudo funciona
Revogue a chave antiga

Periodicidade recomendada: A cada 90 dias para ambientes de producao.

Limites e Metragem

Para chaves com escopo READ_WRITE, o uso e medido por requisicao (metered billing):

Metrica	Descricao
Requisicoes/mes	Total de chamadas a API no periodo
Franquia	Depende do plano e add-on contratado
Excedente	Cobrado por requisicao adicional conforme tabela da feature

O uso acumulado pode ser consultado em Configuracoes > Entitlements.

Boas Praticas

Uma chave por integracao — Facilita auditoria e revogacao seletiva
Menor escopo possivel — Use READ_ONLY se a integracao nao precisa escrever
Nunca exponha chaves no frontend — Chaves de API sao para uso server-side
Armazene em cofre de segredos — Use variavel de ambiente ou secret manager (AWS Secrets Manager, Vault, etc.)
Monitore o uso — Verifique periodicamente a coluna “Ultimo uso” para identificar chaves abandonadas
Revogue imediatamente — Se uma chave for comprometida, revogue-a sem hesitar