Partidas

Os endpoints de partidas permitem listar jogos de um campeonato e consultar placares, com suporte a filtros por rodada, status, time e intervalo de datas.

Endpoints disponíveis

Método	Endpoint	Descrição
`GET`	`/v1/campeonatos/:id/partidas`	Todas as partidas de um campeonato (com filtros)
`GET`	`/v1/partidas/ao-vivo`	Partidas em andamento agora
`GET`	`/v1/partidas/:id/estatisticas`	Estatísticas por lado (mandante/visitante)
`GET`	`/v1/partidas/:id/escalacao`	Escalação: formação, técnico, titulares e reservas

O endpoint de listagem por campeonato também está documentado na seção Campeonatos, pois faz parte da hierarquia campeonato → partida.

Status das partidas

Todas as partidas retornam um campo status com um dos seguintes valores:

Status	Significado
`aguardando`	A partida está agendada, mas ainda não começou. Placar retorna `null`.
`ao_vivo`	A partida está em andamento.
`encerrado`	A partida foi finalizada. Placar definitivo.
`adiado`	A partida foi adiada. Não há placar.

Cache e atualização

Endpoint	TTL do cache
`/v1/campeonatos/:id/partidas`	60 segundos
`/v1/partidas/ao-vivo`	15 segundos
`/v1/partidas/:id/estatisticas`	15s (ao vivo) / 60s
`/v1/partidas/:id/escalacao`	15s (ao vivo) / 60s

Filtros de partidas por campeonato

O endpoint /v1/campeonatos/:id/partidas aceita os seguintes parâmetros:

Parâmetro	Tipo	Descrição	Exemplo
`rodada`	integer	Somente partidas de uma rodada	`?rodada=5`
`status`	string	Somente partidas com aquele status	`?status=encerrado`
`time_id`	integer	Somente jogos em que o time participa (mandante ou visitante)	`?time_id=1`
`data_inicio`	string	Data mínima no formato `YYYY-MM-DD`	`?data_inicio=2026-03-01`
`data_fim`	string	Data máxima no formato `YYYY-MM-DD`	`?data_fim=2026-03-31`
`pagina`	integer	Página desejada (padrão: `1`)	`?pagina=2`
`por_pagina`	integer	Itens por página, de 1 a 100 (padrão: `15`)	`?por_pagina=10`

Exemplo — partidas encerradas do Flamengo no Brasileirão

curl -H "Authorization: Bearer SUA_API_KEY" \
  "https://api.dadosfutebol.com.br/v1/campeonatos/3/partidas?time_id=1&status=encerrado"

{
  "data": [
    {
      "id": 1,
      "rodada_id": 1,
      "rodada_numero": 1,
      "rodada_nome": "1ª Rodada",
      "fase": null,
      "time_mandante": { "id": 1, "nome": "Flamengo", "sigla": "FLA", "escudo_url": null },
      "time_visitante": { "id": 2, "nome": "Palmeiras", "sigla": "PAL", "escudo_url": null },
      "placar_mandante": 2,
      "placar_visitante": 1,
      "disputa_penalti": false,
      "penalti": null,
      "status": "encerrado",
      "slug": "flamengo-palmeiras-1",
      "data_realizacao": "08/03/2026",
      "hora_realizacao": "16:00",
      "data_hora_realizacao": "2026-03-08T16:00:00-03:00",
      "estadio": "Maracanã"
    }
  ],
  "meta": {
    "campeonato_id": 1,
    "total": 3,
    "por_pagina": 15,
    "pagina_atual": 1,
    "ultima_pagina": 1
  }
}

GET /v1/partidas/ao-vivo

Retorna todas as partidas que estão acontecendo no momento em qualquer campeonato. Cache de 15 segundos.

curl -H "Authorization: Bearer SUA_API_KEY" \
  https://api.dadosfutebol.com.br/v1/partidas/ao-vivo

{
  "data": [
    {
      "id": 9,
      "rodada_id": 3,
      "rodada_numero": 3,
      "rodada_nome": "3ª Rodada",
      "fase": null,
      "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",
      "estadio": "Maracanã",
      "campeonato": { "id": 1, "nome": "Brasileirão Série A", "temporada": "2026" }
    },
    {
      "id": 7910,
      "rodada_id": null,
      "rodada_numero": null,
      "rodada_nome": null,
      "fase": { "id": 22, "nome": "Oitavas de Final", "slug": "oitavas-de-final" },
      "time_mandante": { "id": 22, "nome": "Remo", "sigla": "REM", "escudo_url": null },
      "time_visitante": { "id": 10, "nome": "Santos", "sigla": "SAN", "escudo_url": null },
      "placar_mandante": 0,
      "placar_visitante": 0,
      "status": "ao_vivo",
      "estadio": "Mangueirão",
      "campeonato": { "id": 62, "nome": "Copa do Brasil", "temporada": "2026" }
    }
  ],
  "meta": { "total": 2 }
}

Rodada ou fase, nunca as duas. Partidas de pontos corridos vêm com rodada_id/rodada_numero/rodada_nome preenchidos e fase nula. Partidas de mata-mata vêm com os campos de rodada nulos e fase preenchida — o segundo item do exemplo acima. O bloco campeonato é resolvido pelos dois caminhos e nunca falta.

GET /v1/partidas/:id/eventos

Retorna os eventos da partida — gols, gols contra, pênaltis, cartões e substituições — ordenados por minuto, coletados via SofaScore. Cache de 15s (ao vivo) ou 60s.

curl -H "Authorization: Bearer SUA_API_KEY" \
  https://api.dadosfutebol.com.br/v1/partidas/9/eventos

{
  "data": [
    { "tipo": "gol", "jogador": "Pedro", "time_nome": "Flamengo", "minuto": 23 },
    { "tipo": "cartao_amarelo", "jogador": "Villasanti", "time_nome": "Grêmio", "minuto": 41 },
    { "tipo": "substituicao", "jogador": "Everton Cebolinha", "time_nome": "Flamengo", "minuto": 63 }
  ],
  "meta": { "partida_id": 9, "total": 3 }
}

Valores possíveis de tipo: gol, gol_contra, penalti, cartao_amarelo, cartao_vermelho e substituicao. Em substituições, jogador é quem entrou em campo.

GET /v1/partidas/:id/estatisticas

Retorna as estatísticas da partida por lado (mandante e visitante). São preenchidas a partir do início do jogo e atualizadas ao vivo. Cache de 15s (ao vivo) ou 60s.

Campo null significa não informado pela fonte — o que é diferente de zero. O endpoint responde 404 quando ainda não há nenhuma estatística para a partida.

curl -H "Authorization: Bearer SUA_API_KEY" \
  https://api.dadosfutebol.com.br/v1/partidas/1/estatisticas

{
  "data": {
    "partida_id": 1,
    "time_mandante": { "id": 1, "nome": "Flamengo", "sigla": "FLA" },
    "time_visitante": { "id": 2, "nome": "Estudiantes", "sigla": "EST" },
    "status": "ao_vivo",
    "estatisticas": {
      "mandante": {
        "posse_bola": 27,
        "finalizacoes_total": 16,
        "finalizacoes_no_gol": 5,
        "finalizacoes_fora": 7,
        "finalizacoes_trave": 0,
        "finalizacoes_bloqueadas": 4,
        "penaltis": 0,
        "escanteios": 2,
        "faltas": 11,
        "impedimentos": 2,
        "cartoes_amarelos": 1,
        "cartoes_vermelhos": 0,
        "defesas": 4,
        "desarmes": 26,
        "precisao_passes": 76.36,
        "passes_total": 258,
        "passes_errados": 61,

        "gols_esperados": 1.24,
        "nota_media": 7.62,
        "grandes_chances": 2,
        "finalizacoes_dentro_area": 12,
        "cruzamentos_certos": 4,
        "cruzamentos_total": 13,
        "duelos_vencidos_percentual": 61,
        "desarmes_certos": 14,
        "cortes": 33,
        "gols_evitados": 0.92,
        "tiros_de_meta": 6
      },
      "visitante": { "...": "mesma estrutura" }
    }
  }
}

Estatísticas avançadas

Além dos 17 campos básicos acima, o endpoint traz mais 38 campos vindos do SofaScore. Em partidas cuja fonte é a Globo eles saem null.

Bloco	Campos
Visão geral	`gols_esperados` (xG), `grandes_chances`, `tiros_livres`, `nota_media`
Finalizações	`finalizacoes_dentro_area`, `finalizacoes_fora_area`
Ataque	`grandes_chances_convertidas`, `grandes_chances_perdidas`, `passes_em_profundidade`, `toques_area_adversaria`, `faltas_sofridas_ultimo_terco`
Passes	`laterais_cobrados`, `entradas_ultimo_terco`, `passes_ultimo_terco_certos` / `_total`, `bolas_longas_certas` / `_total`, `cruzamentos_certos` / `_total`
Duelos	`duelos_vencidos_percentual`, `posses_perdidas`, `duelos_chao_vencidos` / `_total`, `duelos_aereos_vencidos` / `_total`, `dribles_certos` / `_total`
Defesa	`desarmes_certos`, `interceptacoes`, `recuperacoes_bola`, `cortes`, `erros_para_finalizacao`, `erros_para_gol`
Goleiro	`gols_evitados`, `defesas_dificeis`, `saidas_altas`, `socos_do_goleiro`, `tiros_de_meta`

Pares _certos / _total. Seis métricas vêm como fração na fonte — cruzamentos_certos: 4 e cruzamentos_total: 13 significam “4 de 13 cruzamentos certos”. O percentual não é devolvido: derive de certos / total. O caso especial é desarmes_certos, cujo denominador é o campo desarmes, e não um desarmes_total.

gols_evitados pode ser negativo. É a métrica goals prevented do goleiro: positivo quer dizer que ele evitou mais gols do que o esperado; negativo, que sofreu mais do que devia. Valores como -0.14 são normais — não trate o campo como contador sem sinal.

GET /v1/partidas/:id/escalacao

Retorna a escalação de cada lado: formação, técnico, titulares e reservas. Fica disponível a partir do pré-jogo, assim que a fonte confirma a escalação. Cache de 15s (ao vivo) ou 60s.

O campo confirmada indica se a fonte já confirmou a escalação. Em titulares que saíram, substituido_por traz o nome de quem entrou, capturando as substituições. Responde 404 quando ainda não há escalação para a partida.

curl -H "Authorization: Bearer SUA_API_KEY" \
  https://api.dadosfutebol.com.br/v1/partidas/1/escalacao

{
  "data": {
    "partida_id": 1,
    "time_mandante": { "id": 1, "nome": "Flamengo", "sigla": "FLA" },
    "time_visitante": { "id": 2, "nome": "Estudiantes", "sigla": "EST" },
    "status": "ao_vivo",
    "escalacoes": {
      "mandante": {
        "formacao": "4-3-3",
        "tecnico": "Leonardo Jardim",
        "confirmada": true,
        "titulares": [
          {
            "nome": "Agustín Daniel Rossi",
            "apelido": "Rossi",
            "numero": 1,
            "posicao": "Goleiro",
            "posicao_sigla": "GOL",
            "foto_url": null,
            "substituido_por": null
          }
        ],
        "reservas": [
          {
            "nome": "Andrew da Silva Ventura",
            "apelido": "Andrew",
            "numero": 42,
            "posicao": "Goleiro",
            "posicao_sigla": "GOL",
            "foto_url": null,
            "substituido_por": null
          }
        ]
      },
      "visitante": { "...": "mesma estrutura" }
    }
  }
}

Introdução

Endpoints

Integrações

Partidas

Partidas

Endpoints disponíveis

Status das partidas

Cache e atualização

Filtros de partidas por campeonato

Exemplo — partidas encerradas do Flamengo no Brasileirão

GET /v1/partidas/ao-vivo

GET /v1/partidas/:id/eventos

GET /v1/partidas/:id/estatisticas

Estatísticas avançadas

GET /v1/partidas/:id/escalacao

​Partidas

​Endpoints disponíveis

​Status das partidas

​Cache e atualização

​Filtros de partidas por campeonato

​Exemplo — partidas encerradas do Flamengo no Brasileirão

​GET /v1/partidas/ao-vivo

​GET /v1/partidas/:id/eventos

​GET /v1/partidas/:id/estatisticas

​Estatísticas avançadas

​GET /v1/partidas/:id/escalacao

Partidas

Endpoints disponíveis

Status das partidas

Cache e atualização

Filtros de partidas por campeonato

Exemplo — partidas encerradas do Flamengo no Brasileirão

GET /v1/partidas/ao-vivo

GET /v1/partidas/:id/eventos

GET /v1/partidas/:id/estatisticas

Estatísticas avançadas

GET /v1/partidas/:id/escalacao