> ## 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.
# Partidas
> Endpoints para consultar partidas, placares e histórico de jogos.
# 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](/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
```bash theme={null}
curl -H "Authorization: Bearer SUA_API_KEY" \
"https://api.dadosfutebol.com.br/v1/campeonatos/3/partidas?time_id=1&status=encerrado"
```
```json theme={null}
{
"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.
```bash theme={null}
curl -H "Authorization: Bearer SUA_API_KEY" \
https://api.dadosfutebol.com.br/v1/partidas/ao-vivo
```
```json theme={null}
{
"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.
```bash theme={null}
curl -H "Authorization: Bearer SUA_API_KEY" \
https://api.dadosfutebol.com.br/v1/partidas/9/eventos
```
```json theme={null}
{
"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.
```bash theme={null}
curl -H "Authorization: Bearer SUA_API_KEY" \
https://api.dadosfutebol.com.br/v1/partidas/1/estatisticas
```
```json theme={null}
{
"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.
```bash theme={null}
curl -H "Authorization: Bearer SUA_API_KEY" \
https://api.dadosfutebol.com.br/v1/partidas/1/escalacao
```
```json theme={null}
{
"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" }
}
}
}
```