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/1/partidas?time_id=1&status=encerrado"
{
"data": [
{
"id": 1,
"rodada_id": 1,
"rodada_numero": 1,
"rodada_nome": "1ª Rodada",
"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,
"campeonato_id": 1,
"campeonato_nome": "Campeonato Brasileiro Série A",
"rodada_numero": 3,
"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ã"
}
],
"meta": { "total": 1 }
}
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.
A posse de bola não é fornecida pela fonte atual e vem como null. O endpoint responde 404 quando ainda não há estatísticas 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": null,
"finalizacoes_total": 12,
"finalizacoes_no_gol": 5,
"finalizacoes_fora": 5,
"finalizacoes_trave": 1,
"finalizacoes_bloqueadas": 1,
"penaltis": 0,
"escanteios": 6,
"faltas": 14,
"impedimentos": 2,
"cartoes_amarelos": 3,
"cartoes_vermelhos": 0,
"defesas": 4,
"desarmes": 9,
"precisao_passes": 82.3,
"passes_total": 390,
"passes_errados": 93
},
"visitante": { "...": "mesma estrutura" }
}
}
}
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" }
}
}
}
