> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dadosfutebol.com.br/llms.txt
> Use this file to discover all available pages before exploring further.
# Introdução
> Bem-vindo à API Dados Futebol — a API REST do futebol brasileiro.
# API Dados Futebol
A **API Dados Futebol** é uma API REST que fornece dados estruturados do futebol brasileiro: campeonatos, rodadas, partidas, tabelas de classificação, artilharia e elencos dos clubes.
Todas as respostas são em **português**, com chaves JSON semânticas como `placar_mandante`, `campeonato_id` e `ao_vivo`. A API segue o padrão REST sobre HTTPS, retorna JSON em todas as rotas e usa autenticação via **API Key no header `Authorization`**.
## O que você pode fazer
Liste competições, filtre por temporada e status, e consulte a classificação completa com pontos, saldo e aproveitamento.
Consulte placares e histórico de jogos, com filtros por rodada, status, time e intervalo de datas.
Busque clubes por nome ou sigla, veja elencos completos e consulte artilheiros por campeonato.
Entenda como usar sua API Key, os planos disponíveis e os headers de rate limiting retornados em cada resposta.
Conecte os dados a Claude e Cursor via Model Context Protocol — 23 ferramentas que espelham os endpoints da API.
## Como funciona
Toda requisição precisa de uma **API Key** enviada como Bearer Token. A API valida a key, aplica o rate limit do plano correspondente e retorna os dados em JSON.
As respostas de listagem seguem sempre o mesmo envelope:
```json theme={null}
{
"data": [ ... ],
"meta": {
"total": 2,
"por_pagina": 15,
"pagina_atual": 1,
"ultima_pagina": 1
}
}
```
Respostas de item único omitem o `meta` e retornam apenas `"data": { ... }`. Erros retornam um objeto com `"erro"` e `"mensagem"` em português.
## Início rápido
### 1. Obtenha sua API Key
Solicite sua key pelo painel administrativo ou entre em contato. A API roda somente em **produção**; cada cliente utiliza sua própria key.
### 2. Faça sua primeira requisição
```bash theme={null}
curl -H "Authorization: Bearer SUA_API_KEY" \
https://api.dadosfutebol.com.br/v1/campeonatos
```
Substitua `SUA_API_KEY` pela key que você recebeu.
### 3. Resposta esperada
```json theme={null}
{
"data": [
{
"id": 3,
"nome": "Brasileirão Série A",
"temporada": "2026",
"tipo": "pontos-corridos",
"status": "em_andamento"
},
{
"id": 62,
"nome": "Copa do Brasil",
"temporada": "2026",
"tipo": "mata-mata",
"status": "em_andamento"
}
],
"meta": {
"total": 2,
"por_pagina": 15,
"pagina_atual": 1,
"ultima_pagina": 1
}
}
```
## Base URL
| Ambiente | URL base |
| -------- | --------------------------------- |
| Produção | `https://api.dadosfutebol.com.br` |
Todos os endpoints começam com o prefixo `/v1`:
```
GET https://api.dadosfutebol.com.br/v1/campeonatos
GET https://api.dadosfutebol.com.br/v1/campeonatos/3/partidas
```
## Convenções gerais
| Aspecto | Comportamento |
| ------------ | --------------------------------------------------- |
| Formato | JSON (`Content-Type: application/json`) |
| Autenticação | `Authorization: Bearer {api_key}` |
| Datas | ISO 8601 com timezone (`2026-04-19T16:00:00-03:00`) |
| Erros | Sempre em português com campos `erro` e `mensagem` |
| Cache | Listagens: 60s |
***
## Referência de Parâmetros
Todos os parâmetros aceitos pela API, agrupados por tipo.
### Parâmetros de path (obrigatórios)
Informados na URL. Sempre inteiros.
| Parâmetro | Onde aparece | Significado |
| --------------- | ----------------------------------------------------------------------------------------------------------------- | ------------------------------- |
| `:id` | `/v1/campeonatos/:id`, `/v1/partidas/:id/...`, `/v1/jogadores/:id` | Identificador único do recurso |
| `:campeonatoId` | `/v1/campeonatos/:campeonatoId/rodadas`, `.../partidas`, `.../tabela`, `.../artilharia`, `.../fases`, `.../chave` | ID do campeonato pai |
| `:faseId` | `/v1/campeonatos/:id/fases/:faseId`, `.../fases/:faseId/tabela` | ID da fase dentro do campeonato |
| `:timeId` | `/v1/times/:timeId/jogadores` | ID do time |
### Parâmetros de busca (obrigatórios)
| Parâmetro | Endpoints | Tipo | Significado |
| --------- | ---------------------------- | --------------------- | -------------------------------------------------------------------------- |
| `q` | `/v1/times`, `/v1/jogadores` | string (min: 2 chars) | Termo de busca por nome. Retorna 422 se ausente ou menor que 2 caracteres. |
### Filtros (opcionais)
| Parâmetro | Endpoints | Tipo | Valores aceitos | Significado |
| ------------- | ----------------------------------------------- | ------- | ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| `temporada` | `/v1/campeonatos` | string | Ano com 4 dígitos (ex: `2026`) | Filtra campeonatos pelo ano da temporada. Sem filtro retorna todos. |
| `status` | `/v1/campeonatos` | string | `em_andamento`, `encerrado` | Filtra pelo estado atual do campeonato. |
| `tipo` | `/v1/campeonatos`, `/v1/times` | string | `pontos-corridos`, `mata-mata` (campeonatos) / `clube`, `selecao` (times) | Filtra pelo formato de disputa ou tipo de time. |
| `rodada` | `/v1/campeonatos/:id/partidas` | integer | Número da rodada (ex: `5`) | Retorna apenas partidas daquela rodada. |
| `status` | `/v1/campeonatos/:id/partidas` | string | `aguardando`, `ao_vivo`, `encerrado`, `adiado` | Filtra partidas pelo status atual. |
| `time_id` | `/v1/campeonatos/:id/partidas`, `/v1/jogadores` | integer | ID de um time | Retorna jogos onde o time participa (mandante ou visitante), ou jogadores do time. |
| `data_inicio` | `/v1/campeonatos/:id/partidas` | string | Formato `YYYY-MM-DD` | Limite inferior de data das partidas (inclusive). |
| `data_fim` | `/v1/campeonatos/:id/partidas` | string | Formato `YYYY-MM-DD` | Limite superior de data das partidas (inclusive). |
| `posicao` | `/v1/jogadores` | string | `goleiro`, `zagueiro`, `lateral`, `volante`, `meia`, `atacante` | Filtra jogadores pela posição em campo. |
### Paginação (opcionais)
Disponível em `/v1/campeonatos` e `/v1/campeonatos/:id/partidas`.
| Parâmetro | Tipo | Padrão | Limites | Significado |
| ------------ | ------- | ------ | ---------------- | ------------------------------- |
| `pagina` | integer | `1` | min: 1 | Número da página desejada. |
| `por_pagina` | integer | `15` | min: 1, max: 100 | Quantidade de itens por página. |
Endpoints de busca (`/v1/times` e `/v1/jogadores`) retornam no máximo 20 resultados sem paginação. Use termos mais específicos para refinar.
### Valores de enum
#### Status do campeonato
| Valor | Significado |
| ----------- | ---------------------------- |
| `agendado` | Competição ainda não começou |
| `andamento` | Competição em curso |
| `encerrado` | Competição finalizada |
#### Tipo do campeonato
| Valor | Significado |
| ----------------- | -------------------------------------------------- |
| `pontos-corridos` | Todos jogam contra todos (ex: Brasileirão Série A) |
| `mata-mata` | Eliminatórias com chaves (ex: Copa do Brasil) |
#### Status da partida
| Valor | Significado |
| ------------ | ---------------------------------------- |
| `aguardando` | Partida agendada, placar retorna `null` |
| `ao_vivo` | Partida em andamento |
| `encerrado` | Partida finalizada com placar definitivo |
| `adiado` | Partida adiada, sem placar |
#### Posição do jogador
| Valor | Significado |
| ---------- | ------------------------------- |
| `goleiro` | Goleiro |
| `zagueiro` | Zagueiro |
| `lateral` | Lateral (esquerdo ou direito) |
| `volante` | Volante / Médio defensivo |
| `meia` | Meia / Armador |
| `atacante` | Atacante / Centroavante / Ponta |