Chaves API
Crie, configure e faça a gestão de chaves de API no seu painel.
As chaves de API autenticam os seus pedidos à API. Faça a gestão completa pelo painel: defina uma categoria, restrinja o uso com cotas deslizantes, adicione uma data de expiração e monitorize a atividade por chave através dos Registros API.
Para saber como incluir uma chave num pedido, consulte a Introdução.
Criar uma chave
Preencher os campos
Dê à chave um alias (rótulo único para a sua referência), escolha uma categoria e opcionalmente configure cotas e uma data de expiração.
Copiar o segredo
Após guardar, o segredo é exibido uma única vez. Copie-o imediatamente e armazene-o numa variável de ambiente. Ele não pode ser recuperado novamente.
Campos da chave
| Campo | Descrição |
|---|---|
| Alias | Rótulo único por conta. Aparece em registros e filtros do painel. |
| Categoria | Etiqueta de organização (veja Categorias). Não afeta o comportamento da API. |
| Ativa | Ativa ou desativa a chave. Chaves inativas são rejeitadas imediatamente com 401 Inactive API Key. |
| Expira | Data opcional após a qual a chave para de funcionar. Deixe em branco para sem expiração. |
| Cotas de pedidos | Limites opcionais por chave em janelas deslizantes (veja Cotas por chave). |
Categorias
As categorias etiquetam as chaves para a sua organização. Aparecem nos filtros e análises do painel, mas não mudam como a API processa um pedido.
| Categoria | Uso típico |
|---|---|
production | Tráfego em produção, sistemas voltados ao cliente |
development | Desenvolvimento local e testes |
staging | Ambientes de pré-produção e CI |
| Personalizada | Qualquer rótulo livre, p. ex. sandbox, partner-acme |
Mantenha uma chave por ambiente para poder revogá-la ou rotacioná-la de forma independente.
Cotas por chave
Cada chave pode ter limites máximos independentes sobre o volume de pedidos, aplicados em janelas deslizantes (não limites de calendário):
| Cota | Janela |
|---|---|
| Total | Histórico: a chave é bloqueada permanentemente quando atingido |
| Diária | Últimas 24 horas (deslizante, não de meia-noite a meia-noite) |
| Semanal | Últimos 7 dias (deslizante) |
| Mensal | Últimos 30 dias (deslizante) |
Deixe um campo em branco para não aplicar limite para essa janela. Quando uma cota é atingida, a API retorna 401 com Rate limit exceeded for the API key: e o nome da cota na mensagem:
{ "error": "Rate limit exceeded for the API key: quota total" }{ "error": "Rate limit exceeded for the API key: quota daily" }{ "error": "Rate limit exceeded for the API key: quota weekly" }{ "error": "Rate limit exceeded for the API key: quota monthly" }Os contadores de cota são agregados a partir dos registros de pedidos e armazenados em cache por até 24 horas. A aplicação é precisa dentro dessa janela, não para o pedido exata.
As cotas por chave são distintas dos limites de taxa em nível de plano (limites por segundo e por minuto que se aplicam a toda a conta). Ambos retornam 401, com uma mensagem que identifica o limite que atingiu. Consulte Tratamento de erros para detalhes.
Expiração
Defina uma data de expiração em chaves usadas em scripts, pipelines de CI ou integrações com parceiros. Após a data, a API retorna:
{ "error": "Expired API Key" }Código de status HTTP 401. Crie e implante uma chave substituta antes da data de expiração para evitar qualquer tempo de inatividade.
Registros de pedidos
Cada pedido feito com uma chave é registado em Chaves API → Registros no painel. Cada entrada mostra:
| Campo | Descrição |
|---|---|
| Endpoint | Método HTTP e caminho |
| Status | Código de status da resposta |
| Duração | Tempo até o primeiro byte (ms) |
| IP | Endereço IP do chamador |
| Créditos | Créditos cobrados por esta pedido |
Use os registros para auditar a atividade por chave, depurar erros inesperados ou identificar tráfego de chaves comprometidas.
Desativar vs. excluir
| Ação | Efeito |
|---|---|
| Desativar | A chave é bloqueada imediatamente. O histórico de uso e as configurações são mantidos. Pode ser reativada. |
| Excluir | Remove permanentemente a chave e a sua configuração. Só é possível se a chave nunca foi usada. |
Prefira desativação à exclusão. Se uma chave tem histórico de pedidos, não pode ser excluída. O histórico é mantido para faturação e auditoria.
Rotacionar uma chave
Criar a chave substituta
Aceda a painel → Chaves API → Nova e crie uma nova chave com as mesmas definições de categoria e cota. Dê-lhe um novo alias para a distinguir.
Implantar a nova chave
Atualize a variável de ambiente em cada sistema que usa a chave antiga e reimplante.
Desativar a chave antiga
Defina a chave antiga como inativa no painel. Isso bloqueia os pedidos restantes sem remover o seu histórico.
Referência de erros
| Erro | Status | Causa |
|---|---|---|
Invalid API Key | 401 | Chave não encontrada ou malformada |
Inactive API Key | 401 | Chave está desativada |
Expired API Key | 401 | Chave ultrapassou a sua data de expiração |
Rate limit exceeded for the API key: quota … | 401 | Cota deslizante por chave atingida |
Rate limit exceeded: You've exceeded the … rate limit on your subscription | 401 | Limite por segundo ou por minuto em nível de plano |
IP temporarily blocked | 403 | Muitas tentativas de autenticação falhas do mesmo IP |
Veja também: Melhores práticas para diretrizes de segurança e Glossário para definições de termos.