> ## 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.

# Campeonatos

> Endpoints para consultar campeonatos, rodadas, partidas e tabela de classificação.

# 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étodo | Endpoint                                   | Descrição                                       |
| ------ | ------------------------------------------ | ----------------------------------------------- |
| `GET`  | `/v1/campeonatos`                          | Lista todos os campeonatos cadastrados          |
| `GET`  | `/v1/campeonatos/:id`                      | Detalhes de um campeonato específico            |
| `GET`  | `/v1/campeonatos/:id/rodadas`              | Rodadas do campeonato com todas as partidas     |
| `GET`  | `/v1/campeonatos/:id/fases`                | Lista as fases de um campeonato mata-mata       |
| `GET`  | `/v1/campeonatos/:id/fases/:faseId`        | Detalhes de uma fase com chaves e partidas      |
| `GET`  | `/v1/campeonatos/:id/partidas`             | Todas as partidas do campeonato, com filtros    |
| `GET`  | `/v1/campeonatos/:id/tabela`               | Tabela de classificação completa                |
| `GET`  | `/v1/campeonatos/:id/fases/:faseId/tabela` | Tabela de classificação de uma fase             |
| `GET`  | `/v1/campeonatos/:id/chave`                | Chave (bracket) do campeonato mata-mata         |
| `GET`  | `/v1/campeonatos/:id/artilharia`           | Artilheiros do campeonato                       |
| `GET`  | `/v1/cobertura`                            | Cobertura real de dados de todos os campeonatos |
| `GET`  | `/v1/campeonatos/:id/cobertura`            | Cobertura de um campeonato específico           |

***

## Campeonatos disponíveis e seus IDs

O `id` é o que você usa em todos os endpoints desta página — em `/v1/campeonatos/:id/tabela`, por exemplo. Ele é estável: não muda entre temporadas nem entre deploys.

<Info>
  Esta lista é um retrato da temporada 2026, em ordem alfabética. Para obter os
  IDs sempre atualizados em tempo de execução — e para saber quais competições
  estão em andamento agora — use `GET /v1/campeonatos` em vez de fixar os valores
  no seu código.
</Info>

| ID   | Campeonato                   | Tipo            | Free |
| ---- | ---------------------------- | --------------- | ---- |
| `3`  | Brasileirão Série A          | pontos-corridos | ✅    |
| `4`  | Brasileirão Série B          | pontos-corridos | ✅    |
| `72` | Brasileirão Série B Sub-20   | mata-mata       | —    |
| `60` | Brasileirão Série C          | pontos-corridos | ✅    |
| `61` | Brasileirão Série D          | pontos-corridos | ✅    |
| `70` | Brasileirão Sub-20           | mata-mata       | —    |
| `80` | Campeonato Alemão            | pontos-corridos | —    |
| `88` | Campeonato Brasileiro Sub-17 | mata-mata       | —    |
| `83` | Campeonato Francês           | pontos-corridos | —    |
| `79` | Campeonato Italiano          | pontos-corridos | —    |
| `84` | Campeonato Saudita           | pontos-corridos | —    |
| `82` | Copa da Alemanha             | mata-mata       | —    |
| `85` | Copa da França               | mata-mata       | —    |
| `76` | Copa da Inglaterra           | mata-mata       | —    |
| `81` | Copa da Itália               | mata-mata       | —    |
| `77` | Copa da Liga Inglesa         | mata-mata       | —    |
| `62` | Copa do Brasil               | mata-mata       | ✅    |
| `71` | Copa do Brasil Sub-17        | mata-mata       | —    |
| `63` | Copa do Mundo 2026           | mata-mata       | —    |
| `67` | Copa do Nordeste             | mata-mata       | —    |
| `78` | Copa do Rei                  | mata-mata       | —    |
| `69` | Copa Sul-Sudeste             | mata-mata       | —    |
| `68` | Copa Verde                   | mata-mata       | —    |
| `74` | La Liga                      | pontos-corridos | —    |
| `65` | Libertadores                 | mata-mata       | —    |
| `87` | Liga Conferência             | mata-mata       | —    |
| `75` | Liga dos Campeões            | mata-mata       | —    |
| `86` | Liga Europa                  | mata-mata       | —    |
| `73` | Premier League               | pontos-corridos | —    |
| `66` | Sul-Americana                | mata-mata       | —    |
| `59` | Supercopa do Brasil          | mata-mata       | —    |

<Note>
  A coluna **Free** indica os campeonatos acessíveis no plano gratuito. Nos
  planos Pro e Enterprise todos os campeonatos da lista estão disponíveis.

  No plano Free, `GET /v1/campeonatos` já devolve a lista filtrada, e chamar um
  campeonato fora dela retorna **403**.
</Note>

***

## GET /v1/campeonatos

Lista todos os campeonatos cadastrados na base. Use os filtros abaixo para refinar a busca. Este endpoint retorna todos os registros que correspondem aos filtros — sem paginação.

### Parâmetros de query

| Parâmetro   | Tipo   | Descrição                        | Exemplo                 |
| ----------- | ------ | -------------------------------- | ----------------------- |
| `temporada` | string | Ano da competição (4 dígitos)    | `?temporada=2026`       |
| `status`    | string | `em_andamento` ou `encerrado`    | `?status=em_andamento`  |
| `tipo`      | string | `pontos-corridos` ou `mata-mata` | `?tipo=pontos-corridos` |

<Warning>
  O valor do filtro `status` é `em_andamento`, com underscore — não `andamento`.
  Filtrar por `andamento` retorna lista vazia, sem erro.
</Warning>

### Exemplo — campeonatos em andamento na temporada 2026

```bash theme={null}
curl -H "Authorization: Bearer SUA_API_KEY" \
  "https://api.dadosfutebol.com.br/v1/campeonatos?status=em_andamento&temporada=2026"
```

```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
  }
}
```

***

## GET /v1/campeonatos/:id

Retorna os dados de um campeonato pelo seu ID.

```bash theme={null}
curl -H "Authorization: Bearer SUA_API_KEY" \
  https://api.dadosfutebol.com.br/v1/campeonatos/3
```

```json theme={null}
{
  "data": {
    "id": 3,
    "nome": "Brasileirão Série A",
    "temporada": "2026",
    "tipo": "pontos-corridos",
    "status": "em_andamento"
  }
}
```

| Código | Motivo                                       |
| ------ | -------------------------------------------- |
| `404`  | Campeonato não encontrado com o ID informado |

***

## GET /v1/campeonatos/:id/rodadas

Lista todas as rodadas de um campeonato, ordenadas por número. Cada rodada já inclui suas partidas completas com placares e status.

```bash theme={null}
curl -H "Authorization: Bearer SUA_API_KEY" \
  https://api.dadosfutebol.com.br/v1/campeonatos/3/rodadas
```

```json theme={null}
{
  "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,
      "partidas": [
        {
          "id": 1,
          "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-x-palmeiras",
          "data_realizacao": "15/03/2026",
          "hora_realizacao": "16:00",
          "data_hora_realizacao": "2026-03-15T16:00:00-03:00",
          "estadio": "Maracanã"
        }
      ]
    },
    {
      "id": 2,
      "numero": 2,
      "nome": "2ª Rodada",
      "slug": "2a-rodada",
      "status": "andamento",
      "data": "2026-03-22",
      "proxima_rodada": { "nome": "3ª Rodada", "slug": "3a-rodada", "numero": 3, "status": "agendada" },
      "rodada_anterior": { "nome": "1ª Rodada", "slug": "1a-rodada", "numero": 1, "status": "encerrada" },
      "partidas": [
        {
          "id": 9,
          "time_mandante": { "id": 3, "nome": "Grêmio", "sigla": "GRE", "escudo_url": null },
          "time_visitante": { "id": 4, "nome": "Internacional", "sigla": "INT", "escudo_url": null },
          "placar_mandante": null,
          "placar_visitante": null,
          "disputa_penalti": false,
          "penalti": null,
          "status": "aguardando",
          "slug": "gremio-x-internacional",
          "data_realizacao": "22/03/2026",
          "hora_realizacao": "18:30",
          "data_hora_realizacao": "2026-03-22T18:30:00-03:00",
          "estadio": "Arena do Grêmio"
        }
      ]
    }
  ],
  "meta": { "campeonato_id": 3, "total": 38 }
}
```

<Info>
  Partidas com `status: "aguardando"` ainda não começaram — os campos de placar retornam `null`.
</Info>

***

## GET /v1/campeonatos/:id/partidas

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

### Parâmetros de query

| Parâmetro     | Tipo    | Descrição                                        | Exemplo                   |
| ------------- | ------- | ------------------------------------------------ | ------------------------- |
| `rodada`      | integer | Filtra partidas de uma rodada específica         | `?rodada=5`               |
| `status`      | string  | `aguardando`, `ao_vivo`, `encerrado` ou `adiado` | `?status=encerrado`       |
| `time_id`     | integer | Retorna apenas jogos em que o time aparece       | `?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 — jogos do Flamengo no Brasileirão em março

```bash theme={null}
curl -H "Authorization: Bearer SUA_API_KEY" \
  "https://api.dadosfutebol.com.br/v1/campeonatos/3/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

| Campo         | Tipo    | Descrição                                |
| ------------- | ------- | ---------------------------------------- |
| `posicao`     | integer | Colocação atual na tabela                |
| `time`        | object  | ID, nome, sigla e URL do escudo do clube |
| `pontos`      | integer | Total de pontos acumulados               |
| `jogos`       | integer | Número de jogos disputados               |
| `vitorias`    | integer | Número de vitórias                       |
| `empates`     | integer | Número de empates                        |
| `derrotas`    | integer | Número de derrotas                       |
| `gols_pro`    | integer | Gols marcados                            |
| `gols_contra` | integer | Gols sofridos                            |
| `saldo`       | integer | Saldo de gols (`gols_pro - gols_contra`) |

```bash theme={null}
curl -H "Authorization: Bearer SUA_API_KEY" \
  https://api.dadosfutebol.com.br/v1/campeonatos/3/tabela
```

```json theme={null}
{
  "data": {
    "campeonato_id": 3,
    "campeonato_nome": "Brasileirão 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.

```bash theme={null}
curl -H "Authorization: Bearer SUA_API_KEY" \
  https://api.dadosfutebol.com.br/v1/campeonatos/3/artilharia
```

```json theme={null}
{
  "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": 3,
    "campeonato_nome": "Brasileirão Série A",
    "total": 2
  }
}
```

***

## GET /v1/cobertura

Retorna, para cada campeonato da temporada, o **estado real de cobertura** de cada tipo de dado — calculado a partir do que já existe no banco, não do formato da competição. Serve para saber, de antemão, o que a API entrega para cada competição.

Cada tipo de dado assume um de três estados:

| Estado     | Significado                                                          |
| ---------- | -------------------------------------------------------------------- |
| `coberto`  | Servido pela API para toda a competição                              |
| `parcial`  | Disponível só em parte (ex.: classificação apenas na fase de grupos) |
| `em-breve` | Ainda não disponível para esta competição                            |

### Parâmetros de query

| Parâmetro   | Tipo   | Descrição                             | Exemplo           |
| ----------- | ------ | ------------------------------------- | ----------------- |
| `temporada` | string | Ano da competição (padrão: ano atual) | `?temporada=2026` |

```bash theme={null}
curl -H "Authorization: Bearer SUA_API_KEY" \
  https://api.dadosfutebol.com.br/v1/cobertura
```

```json theme={null}
{
  "data": [
    {
      "campeonato_id": 3,
      "slug": "brasileirao-serie-a",
      "nome": "Brasileirão Série A",
      "temporada": "2026",
      "tipo": "pontos-corridos",
      "regiao": "nacional",
      "logo_url": "https://assets.dadosfutebol.com.br/campeonato/brasileirao-serie-a.png",
      "cobertura": {
        "classificacao": "coberto",
        "rodadas": "coberto",
        "partidas": "coberto",
        "ao_vivo": "coberto",
        "escalacoes": "coberto",
        "estatisticas": "coberto"
      }
    }
  ],
  "meta": { "total": 30 }
}
```

### Cada campo aponta para o endpoint que serve o dado

| Campo           | Endpoint                        |
| --------------- | ------------------------------- |
| `classificacao` | `/v1/campeonatos/:id/tabela`    |
| `rodadas`       | `/v1/campeonatos/:id/rodadas`   |
| `partidas`      | `/v1/campeonatos/:id/partidas`  |
| `ao_vivo`       | `/v1/partidas/ao-vivo`          |
| `escalacoes`    | `/v1/partidas/:id/escalacao`    |
| `estatisticas`  | `/v1/partidas/:id/estatisticas` |

<Info>
  A cobertura reflete a **capacidade** da API, não o estado atual da temporada. Em mata-mata puro (ex.: Copa do Brasil), as partidas vêm pela **chave** (`/v1/campeonatos/:id/chave`), então `rodadas` e `classificacao` podem aparecer como `em-breve` mesmo havendo jogos.
</Info>

***

## GET /v1/campeonatos/:id/cobertura

A mesma informação de cobertura, para um único campeonato.

```bash theme={null}
curl -H "Authorization: Bearer SUA_API_KEY" \
  https://api.dadosfutebol.com.br/v1/campeonatos/3/cobertura
```

```json theme={null}
{
  "data": {
    "campeonato_id": 3,
    "slug": "brasileirao-serie-a",
    "nome": "Brasileirão Série A",
    "temporada": "2026",
    "tipo": "pontos-corridos",
    "regiao": "nacional",
    "logo_url": "https://assets.dadosfutebol.com.br/campeonato/brasileirao-serie-a.png",
    "cobertura": {
      "classificacao": "coberto",
      "rodadas": "coberto",
      "partidas": "coberto",
      "ao_vivo": "coberto",
      "escalacoes": "coberto",
      "estatisticas": "coberto"
    }
  }
}
```

Retorna `404` se o campeonato não existir.

***

## GET /v1/campeonatos/:id/fases

Lista todas as fases de um campeonato mata-mata (ex: Copa do Brasil).

```bash theme={null}
curl -H "Authorization: Bearer SUA_API_KEY" \
  https://api.dadosfutebol.com.br/v1/campeonatos/2/fases
```

<Info>
  Campeonatos do tipo `pontos-corridos` retornam lista vazia de fases. Use rodadas em vez disso.
</Info>

***

## GET /v1/campeonatos/:id/fases/:faseId/tabela

Retorna a tabela de classificação de uma fase específica de um campeonato. Útil para fases de grupos ou fases com pontos corridos dentro de um campeonato mata-mata.

### Campos da classificação

Os campos retornados são os mesmos do endpoint `/v1/campeonatos/:id/tabela`, acrescidos de `fase_id` e `fase_nome`.

```bash theme={null}
curl -H "Authorization: Bearer SUA_API_KEY" \
  https://api.dadosfutebol.com.br/v1/campeonatos/2/fases/1/tabela
```

```json theme={null}
{
  "data": {
    "campeonato_id": 2,
    "campeonato_nome": "Copa do Brasil",
    "fase_id": 1,
    "fase_nome": "Primeira Fase",
    "temporada": "2026",
    "classificacao": [
      {
        "posicao": 1,
        "time": { "id": 1, "nome": "Flamengo", "sigla": "FLA", "escudo_url": null },
        "pontos": 6,
        "jogos": 2,
        "vitorias": 2,
        "empates": 0,
        "derrotas": 0,
        "gols_pro": 4,
        "gols_contra": 1,
        "saldo": 3
      }
    ]
  }
}
```

| Código | Motivo                                                   |
| ------ | -------------------------------------------------------- |
| `404`  | Campeonato ou fase não encontrados com os IDs informados |

***

## GET /v1/campeonatos/:id/chave

Retorna a chave (bracket) completa de um campeonato mata-mata, com todas as fases e confrontos organizados em formato de chaveamento eliminatório. Disponível apenas para campeonatos do tipo `mata-mata`.

```bash theme={null}
curl -H "Authorization: Bearer SUA_API_KEY" \
  https://api.dadosfutebol.com.br/v1/campeonatos/2/chave
```

```json theme={null}
{
  "data": {
    "campeonato_id": 2,
    "campeonato_nome": "Copa do Brasil",
    "temporada": "2026",
    "fases": [
      {
        "id": 1,
        "nome": "Oitavas de Final",
        "slug": "oitavas-de-final",
        "tipo": "mata-mata",
        "chaves": [
          {
            "id": 1,
            "nome": "Chave 1",
            "slug": "chave-1",
            "partida_ida": {
              "id": 10,
              "time_mandante": { "id": 1, "nome": "Flamengo", "sigla": "FLA", "escudo_url": null },
              "time_visitante": { "id": 5, "nome": "Athletico-PR", "sigla": "CAP", "escudo_url": null },
              "placar_mandante": 2,
              "placar_visitante": 0,
              "status": "encerrado",
              "data_realizacao": "15/05/2026",
              "hora_realizacao": "21:30",
              "estadio": "Maracanã"
            },
            "partida_volta": {
              "id": 11,
              "time_mandante": { "id": 5, "nome": "Athletico-PR", "sigla": "CAP", "escudo_url": null },
              "time_visitante": { "id": 1, "nome": "Flamengo", "sigla": "FLA", "escudo_url": null },
              "placar_mandante": 1,
              "placar_visitante": 1,
              "status": "encerrado",
              "data_realizacao": "22/05/2026",
              "hora_realizacao": "21:30",
              "estadio": "Arena da Baixada"
            }
          }
        ]
      }
    ]
  }
}
```

| Código | Motivo                                       |
| ------ | -------------------------------------------- |
| `404`  | Campeonato não encontrado com o ID informado |

<Info>
  Campeonatos do tipo `pontos-corridos` não possuem chave. Use o endpoint `/v1/campeonatos/:id/tabela` em vez disso.
</Info>

***

## 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` | Sistema de pontos corridos (ex: Brasileirão) |
| `mata-mata`       | Sistema eliminatório (ex: Copa do Brasil)    |