Autenticação
Todos os endpoints da API (exceto /v1/status) exigem uma API Key válida. A key é enviada em cada requisição através do header HTTP Authorization, no formato Bearer Token.
A validação é feita pelo middleware EnsureValidApiKey, que verifica se a key existe na base de dados e está ativa. Não há cookies, sessões ou JWT — cada requisição é autenticada de forma independente.
Como enviar a API Key
Adicione o header Authorization com o prefixo Bearer seguido da sua key:
Authorization: Bearer {sua_api_key}
Nunca exponha sua API Key em repositórios públicos, código client-side ou URLs. Trate-a como uma senha.
Exemplos de código
curl -H "Authorization: Bearer test-api-key-free-sandbox" \
https://api.dadosfutebol.com.br/v1/campeonatos
Erros de autenticação
Quando a autenticação falha, a API retorna HTTP 401 com um JSON explicativo.
API Key não fornecida
O header Authorization está ausente ou vazio.
{
"erro": "Não autorizado",
"mensagem": "API Key não fornecida. Informe o token no header Authorization: Bearer {api_key}"
}
API Key inválida ou inativa
A key foi fornecida, mas não existe na base de dados ou foi desativada.
{
"erro": "Não autorizado",
"mensagem": "API Key inválida ou inativa"
}
Rate Limiting
Cada API Key tem um limite de requisições por período, determinado pelo plano associado a ela.
| Plano | Limite | Janela de tempo |
|---|
| Free | 1.000 requisições | Por dia |
| Pro | 100.000 requisições | Por mês |
| Enterprise | Ilimitado | — |
429 Too Many Requests:
{
"erro": "Limite de requisições atingido",
"mensagem": "Você atingiu o limite do plano Free (1.000 req/dia). Aguarde a renovação ou faça upgrade."
}
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
Chaves de Sandbox
Para desenvolvimento e testes, três keys pré-configuradas estão disponíveis sem necessidade de cadastro:
| Key | Plano simulado | Uso recomendado |
|---|
test-api-key-free-sandbox | Free (1.000 req/dia) | Testes básicos e aprendizado |
test-api-key-pro-sandbox | Pro (100.000 req/mês) | Testes de volume e integração |
test-api-key-enterprise-sandbox | Enterprise (ilimitado) | Testes de carga e CI/CD |
As keys de sandbox funcionam apenas no ambiente de produção (api.dadosfutebol.com.br). Para testes locais, configure seu próprio ambiente com as keys de sandbox registradas no banco.
Obtendo uma API Key de produção
Keys de produção são gerenciadas pelo painel administrativo em /admin/api-keys. O administrador pode:
- Criar keys associadas a um cliente ou aplicação
- Definir o plano (free, pro, enterprise)
- Ativar ou desativar uma key a qualquer momento
- Excluir keys comprometidas
A key é exibida uma única vez no momento da criação. Guarde-a em local seguro — não é possível recuperá-la depois.