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
Substitua SUA_API_KEY pela key fornecida após o cadastro.
curl -H "Authorization: Bearer SUA_API_KEY" \
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"
}
Planos e acesso a endpoints
Cada API Key pertence a um plano que determina quais endpoints e campeonatos estão disponíveis.
Plano Free
O plano free tem acesso limitado a campeonatos brasileiros e aos endpoints de tabela, artilharia e rodadas.
| Endpoint | Free | Pro / Enterprise |
|---|
GET /v1/campeonatos | Filtrado (Série A/B/C/D e Copa do Brasil) | Completo |
GET /v1/campeonatos/:id | Série A/B/C/D e Copa do Brasil | Todos |
GET /v1/campeonatos/:id/tabela | Série A/B/C/D e Copa do Brasil | Todos |
GET /v1/campeonatos/:id/artilharia | Série A/B/C/D e Copa do Brasil | Todos |
GET /v1/campeonatos/:id/rodadas | Série A/B/C/D e Copa do Brasil | Todos |
GET /v1/campeonatos/:id/partidas | Bloqueado | Completo |
GET /v1/campeonatos/:id/fases | Bloqueado | Completo |
GET /v1/partidas/ao-vivo | Bloqueado | Completo |
GET /v1/partidas/:id/eventos | — | Indisponível (501)¹ |
GET /v1/partidas/:id/estatisticas | Bloqueado | Completo |
GET /v1/times | Bloqueado | Completo |
GET /v1/jogadores | Bloqueado | Completo |
GET /v1/me | Permitido | Permitido |
¹ A coleta de eventos de partida está temporariamente indisponível. O endpoint responde 501 Not Implemented para partidas existentes — independentemente do plano. O schema permanece para reativação futura.
Acessar um endpoint ou campeonato fora do seu plano retorna HTTP 403:
{
"erro": "Plano insuficiente",
"mensagem": "Seu plano (free) não tem acesso a este recurso. Faça upgrade para pro ou enterprise."
}
Plano Pro
Acesso completo a todos os endpoints e campeonatos, incluindo Copa do Mundo, partidas ao vivo, estatísticas, times e jogadores. (O endpoint de eventos por partida está temporariamente indisponível — ver nota acima.)
Plano Enterprise
Mesmo acesso do Pro, com limites de requisições personalizados.
Rate Limiting
Cada API Key tem um limite de requisições por período, determinado pelo plano associado a ela.
| Plano | Limite diário | Limite mensal |
|---|
| Free | 100 requisições | 3.000 requisições |
| Pro | 1.000 requisições | 30.000 requisições |
| Enterprise | Sob demanda | Sob demanda |
429 Too Many Requests até a renovação da janela.
{
"erro": "Limite de requisições atingido",
"mensagem": "Você atingiu o limite do plano Free (100 requisições por dia ou 3.000 por mês). Aguarde a renovação ou faça upgrade."
}
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 47
Obtendo uma API Key
A API é oferecida apenas em produção. Cada cliente recebe uma key própria — não há ambiente de testes público nem keys de sandbox.
As keys são gerenciadas em https://dadosfutebol.com.br/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 pode ser consultada novamente e também revogada/excluída a qualquer momento. Guarde-a em local seguro e não a compartilhe.