Skip to main content

​
Campeonatos

O grupo de endpoints de campeonatos cobre toda a estrutura hierárquica de uma competição: o campeonato em si, suas rodadas, as partidas de cada rodada e a tabela de classificação atualizada.

​
Endpoints disponíveis

MétodoEndpointDescrição
GET/v1/campeonatosLista todos os campeonatos cadastrados
GET/v1/campeonatos/:idDetalhes de um campeonato específico
GET/v1/campeonatos/:id/rodadasLista todas as rodadas do campeonato
GET/v1/campeonatos/:id/rodadas/:numeroPartidas de uma rodada específica
GET/v1/campeonatos/:id/fasesLista as fases de um campeonato mata-mata
GET/v1/campeonatos/:id/fases/:faseIdDetalhes de uma fase com chaves e partidas
GET/v1/campeonatos/:id/partidasTodas as partidas do campeonato, com filtros
GET/v1/campeonatos/:id/tabelaTabela de classificação completa
GET/v1/campeonatos/:id/artilhariaArtilheiros do campeonato

​
GET /v1/campeonatos

Lista todos os campeonatos cadastrados na base. Por padrão retorna todos os registros paginados; use os filtros abaixo para refinar a busca.

​
Parâmetros de query

ParâmetroTipoDescriçãoExemplo
temporadastringAno da competição (4 dígitos)?temporada=2026
statusstringandamento, encerrado ou agendado?status=andamento
tipostringpontos-corridos ou mata-mata?tipo=pontos-corridos
paginaintegerPágina desejada (padrão: 1)?pagina=2
por_paginaintegerItens por página, de 1 a 100 (padrão: 15)?por_pagina=10

​
Exemplo — campeonatos em andamento na temporada 2026

curl -H "Authorization: Bearer test-api-key-free-sandbox" \
  "https://api.dadosfutebol.com.br/v1/campeonatos?status=andamento&temporada=2026"

{
  "data": [
    {
      "id": 1,
      "nome": "Campeonato Brasileiro Série A",
      "temporada": "2026",
      "tipo": "pontos-corridos",
      "status": "andamento"
    },
    {
      "id": 2,
      "nome": "Copa do Brasil",
      "temporada": "2026",
      "tipo": "mata-mata",
      "status": "andamento"
    }
  ],
  "meta": {
    "total": 2,
    "por_pagina": 15,
    "pagina_atual": 1,
    "ultima_pagina": 1
  }
}

​
GET /v1/campeonatos/:id

Retorna os dados de um campeonato pelo seu ID. 
curl -H "Authorization: Bearer test-api-key-free-sandbox" \
  https://api.dadosfutebol.com.br/v1/campeonatos/1

{
  "data": {
    "id": 1,
    "nome": "Campeonato Brasileiro Série A",
    "temporada": "2026",
    "tipo": "pontos-corridos",
    "status": "andamento"
  }
}
CódigoMotivo
404Campeonato não encontrado com o ID informado

​
GET /v1/campeonatos/:id/rodadas

Lista todas as rodadas de um campeonato, ordenadas por número. 
curl -H "Authorization: Bearer test-api-key-free-sandbox" \
  https://api.dadosfutebol.com.br/v1/campeonatos/1/rodadas

{
  "data": [
    {
      "id": 1,
      "numero": 1,
      "nome": "1ª Rodada",
      "slug": "1a-rodada",
      "status": "encerrada",
      "data": "2026-03-15",
      "proxima_rodada": { "nome": "2ª Rodada", "slug": "2a-rodada", "numero": 2, "status": "encerrada" },
      "rodada_anterior": null
    },
    {
      "id": 2,
      "numero": 2,
      "nome": "2ª Rodada",
      "slug": "2a-rodada",
      "status": "encerrada",
      "data": "2026-03-22",
      "proxima_rodada": { "nome": "3ª Rodada", "slug": "3a-rodada", "numero": 3, "status": "andamento" },
      "rodada_anterior": { "nome": "1ª Rodada", "slug": "1a-rodada", "numero": 1, "status": "encerrada" }
    }
  ],
  "meta": { "campeonato_id": 1, "total": 38 }
}

​
GET /v1/campeonatos/:id/rodadas/:numero

Retorna os dados de uma rodada específica junto com todas as suas partidas. O parâmetro :numero é o número da rodada (ex: 3), não o ID interno. 
curl -H "Authorization: Bearer test-api-key-free-sandbox" \
  https://api.dadosfutebol.com.br/v1/campeonatos/1/rodadas/3

{
  "data": {
    "id": 3,
    "campeonato_id": 1,
    "numero": 3,
    "nome": "3ª Rodada",
    "slug": "3a-rodada",
    "status": "andamento",
    "data": "2026-04-19",
    "proxima_rodada": { "nome": "4ª Rodada", "slug": "4a-rodada", "numero": 4, "status": "agendada" },
    "rodada_anterior": { "nome": "2ª Rodada", "slug": "2a-rodada", "numero": 2, "status": "encerrada" },
    "partidas": [
      {
        "id": 9,
        "time_mandante": { "id": 1, "nome": "Flamengo", "sigla": "FLA", "escudo_url": null },
        "time_visitante": { "id": 7, "nome": "Grêmio", "sigla": "GRE", "escudo_url": null },
        "placar_mandante": 1,
        "placar_visitante": 0,
        "status": "ao_vivo",
        "data_realizacao": "19/04/2026",
        "hora_realizacao": "16:00",
        "data_hora_realizacao": "2026-04-19T16:00:00-03:00",
        "estadio": "Maracanã"
      }
    ]
  }
}
Partidas com status: "aguardando" ainda não começaram — os campos de placar retornam null.

​
GET /v1/campeonatos/:id/partidas

Lista todas as partidas de um campeonato com suporte a múltiplos filtros combinados.

​
Parâmetros de query

ParâmetroTipoDescriçãoExemplo
rodadaintegerFiltra partidas de uma rodada específica?rodada=5
statusstringaguardando, ao_vivo, encerrado ou adiado?status=encerrado
time_idintegerRetorna apenas jogos em que o time aparece?time_id=1
data_iniciostringData mínima no formato YYYY-MM-DD?data_inicio=2026-03-01
data_fimstringData máxima no formato YYYY-MM-DD?data_fim=2026-03-31
paginaintegerPágina desejada (padrão: 1)?pagina=2
por_paginaintegerItens por página, de 1 a 100 (padrão: 15)?por_pagina=10

​
Exemplo — jogos do Flamengo no Brasileirão em março

curl -H "Authorization: Bearer test-api-key-free-sandbox" \
  "https://api.dadosfutebol.com.br/v1/campeonatos/1/partidas?time_id=1&data_inicio=2026-03-01&data_fim=2026-03-31"

​
GET /v1/campeonatos/:id/tabela

Retorna a classificação completa do campeonato. Disponível apenas para campeonatos do tipo pontos-corridos.

​
Campos da classificação

CampoTipoDescrição
posicaointegerColocação atual na tabela
timeobjectID, nome, sigla e URL do escudo do clube
pontosintegerTotal de pontos acumulados
jogosintegerNúmero de jogos disputados
vitoriasintegerNúmero de vitórias
empatesintegerNúmero de empates
derrotasintegerNúmero de derrotas
gols_prointegerGols marcados
gols_contraintegerGols sofridos
saldointegerSaldo de gols (gols_pro - gols_contra)
curl -H "Authorization: Bearer test-api-key-free-sandbox" \
  https://api.dadosfutebol.com.br/v1/campeonatos/1/tabela

{
  "data": {
    "campeonato_id": 1,
    "campeonato_nome": "Campeonato Brasileiro Série A",
    "temporada": "2026",
    "classificacao": [
      {
        "posicao": 1,
        "time": { "id": 1, "nome": "Flamengo", "sigla": "FLA", "escudo_url": null },
        "pontos": 7,
        "jogos": 3,
        "vitorias": 2,
        "empates": 1,
        "derrotas": 0,
        "gols_pro": 5,
        "gols_contra": 2,
        "saldo": 3
      }
    ]
  }
}

​
GET /v1/campeonatos/:id/artilharia

Retorna os jogadores com mais gols no campeonato, na ordem do ranking oficial. 
curl -H "Authorization: Bearer test-api-key-free-sandbox" \
  https://api.dadosfutebol.com.br/v1/campeonatos/1/artilharia

{
  "data": [
    {
      "id": 1,
      "nome": "Pedro Guilherme",
      "nome_popular": "Pedro",
      "posicao": "atacante",
      "gols": 15,
      "time": { "id": 1, "nome": "Flamengo", "sigla": "FLA", "escudo_url": null }
    },
    {
      "id": 5,
      "nome": "Endrick Felipe",
      "nome_popular": "Endrick",
      "posicao": "atacante",
      "gols": 12,
      "time": { "id": 2, "nome": "Palmeiras", "sigla": "PAL", "escudo_url": null }
    }
  ],
  "meta": {
    "campeonato_id": 1,
    "campeonato_nome": "Campeonato Brasileiro Série A",
    "total": 2
  }
}

​
GET /v1/campeonatos/:id/fases

Lista todas as fases de um campeonato mata-mata (ex: Copa do Brasil). 
curl -H "Authorization: Bearer test-api-key-free-sandbox" \
  https://api.dadosfutebol.com.br/v1/campeonatos/2/fases
Campeonatos do tipo pontos-corridos retornam lista vazia de fases. Use rodadas em vez disso.

​
Valores de enum

​
status do campeonato

ValorSignificado
agendadoCompetição ainda não começou
andamentoCompetição em curso
encerradoCompetição finalizada

​
tipo do campeonato

ValorSignificado
pontos-corridosSistema de pontos corridos (ex: Brasileirão)
mata-mataSistema eliminatório (ex: Copa do Brasil)