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 | Add-on da Loja (todos os planos) | Leitura de dados (GET) |
api.read_write | Add-on da Loja (todos os planos) | Leitura + escrita (GET, POST, PUT, DELETE) |
Nenhum plano inclui acesso a API: adquira 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_ONLYouREAD_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 X-API-Key: <chave> via HTTPS. |
| 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 |
Chaves revogadas deixam de aparecer na lista.
Revogar uma Chave
- Localize a chave na lista
- Clique no botao “Revoke” da linha
- 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 X-API-Key:
GET /api/tenants/:tenantId/reservations
X-API-Key: opk_a1b2c3d4e5f6...
Content-Type: application/jsonResposta de Erro (Chave Invalida)
{
"statusCode": 401,
"message": "Invalid or revoked API key",
"error": "Unauthorized"
}Resposta de Erro (Escopo Insuficiente)
{
"statusCode": 403,
"message": "This API key has READ_ONLY scope and cannot perform write operations.",
"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 |
| Mensalidade | Valor fixo do add-on api.read_write (US$ 149/mes) |
| Por requisicao | Cada requisicao e cobrada conforme a tabela da feature (US$ 0,001) |
O consumo e apurado no fechamento mensal da fatura; hoje nao ha tela para consultar o uso acumulado.
Boas Praticas
- Uma chave por integracao — Facilita auditoria e revogacao seletiva
- Menor escopo possivel — Use
READ_ONLYse 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