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

# Times e Jogadores

> Endpoints para buscar clubes, consultar elencos e pesquisar jogadores por nome ou posição.

# Times e Jogadores

Os endpoints de times e jogadores funcionam como **busca**, não como listagem. É obrigatório informar ao menos 2 caracteres no parâmetro `?q=` para obter resultados — sem ele a API retorna `422`. Isso evita a extração em massa do banco de dados.

## Endpoints disponíveis

| Método | Endpoint                  | Descrição                         |
| ------ | ------------------------- | --------------------------------- |
| `GET`  | `/v1/times`               | Busca times por nome ou sigla     |
| `GET`  | `/v1/times/:id/jogadores` | Elenco de um time específico      |
| `GET`  | `/v1/jogadores`           | Busca jogadores por nome          |
| `GET`  | `/v1/jogadores/:id`       | Detalhes de um jogador específico |

***

## GET /v1/times

Busca clubes por nome ou sigla. **O parâmetro `?q=` é obrigatório** com ao menos 2 caracteres. Retorna no máximo 20 resultados, sem paginação.

<Warning>
  Requisições sem `?q=` ou com menos de 2 caracteres retornam `422 Unprocessable Entity`.
</Warning>

### Parâmetros de query

| Parâmetro | Tipo   | Obrigatório | Descrição                                                 | Exemplo       |
| --------- | ------ | ----------- | --------------------------------------------------------- | ------------- |
| `q`       | string | **Sim**     | Busca por nome ou sigla, mínimo 2 chars, case-insensitive | `?q=Fla`      |
| `tipo`    | string | Não         | Filtra por tipo: `clube` ou `selecao`                     | `?tipo=clube` |

### Exemplo — busca por "fl"

```bash theme={null}
curl -H "Authorization: Bearer SEU_TOKEN" \
  "https://api.dadosfutebol.com.br/v1/times?q=fl"
```

```json theme={null}
{
  "data": [
    {
      "id": 1,
      "nome": "Flamengo",
      "tipo": "clube",
      "sigla": "FLA",
      "escudo_url": "https://assets.dadosfutebol.com.br/escudos/flamengo.png"
    },
    {
      "id": 173,
      "nome": "Floresta-CE",
      "tipo": "clube",
      "sigla": "FLO",
      "escudo_url": "https://assets.dadosfutebol.com.br/escudos/floresta-ce.png"
    },
    {
      "id": 4,
      "nome": "Fluminense",
      "tipo": "clube",
      "sigla": "FLU",
      "escudo_url": "https://assets.dadosfutebol.com.br/escudos/fluminense.png"
    },
    {
      "id": 316,
      "nome": "Fluminense do Itaum",
      "tipo": "clube",
      "sigla": "FDI",
      "escudo_url": "https://assets.dadosfutebol.com.br/escudos/fluminense-do-itaum.png"
    },
    {
      "id": 770,
      "nome": "Fluminense-PI",
      "tipo": "clube",
      "sigla": "FLU",
      "escudo_url": null
    }
  ],
  "meta": {
    "total": 5
  }
}
```

<Note>
  `escudo_url` sempre aponta para imagens hospedadas em `assets.dadosfutebol.com.br` (ou para o proxy de bandeiras da API, no caso de seleções). Quando ainda não temos a imagem do time, vem `null` — nunca uma URL de terceiro.
</Note>

### Exemplo — erro sem parâmetro de busca

```json theme={null}
{
  "erro": "Parâmetro obrigatório",
  "mensagem": "Informe ao menos 2 caracteres no parâmetro ?q= para buscar times."
}
```

### Erros possíveis

| Código | Motivo                                     |
| ------ | ------------------------------------------ |
| `422`  | `?q=` ausente ou com menos de 2 caracteres |
| `401`  | API Key inválida ou ausente                |

***

## GET /v1/times/:id/jogadores

Retorna o elenco completo de um time específico, ordenado por posição e nome.

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

```json theme={null}
{
  "data": [
    {
      "id": 1,
      "nome_popular": "Pedro",
      "nome": "Pedro Guilherme",
      "idade": 27,
      "posicao": "atacante",
      "numero_camisa": 9,
      "gols": 15
    },
    {
      "id": 2,
      "nome_popular": "Everton Ribeiro",
      "nome": "Everton Ribeiro",
      "idade": 35,
      "posicao": "meia",
      "numero_camisa": 7,
      "gols": 4
    }
  ],
  "meta": {
    "total": 25,
    "time": { "id": 1, "nome": "Flamengo", "sigla": "FLA", "escudo_url": null }
  }
}
```

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

***

## GET /v1/jogadores

Busca jogadores por nome. **O parâmetro `?q=` é obrigatório** com ao menos 2 caracteres. Retorna no máximo 20 resultados, sem paginação.

<Warning>
  Requisições sem `?q=` ou com menos de 2 caracteres retornam `422 Unprocessable Entity`.
</Warning>

### Parâmetros de query

| Parâmetro | Tipo    | Obrigatório | Descrição                                          | Exemplo             |
| --------- | ------- | ----------- | -------------------------------------------------- | ------------------- |
| `q`       | string  | **Sim**     | Busca parcial pelo nome do jogador, mínimo 2 chars | `?q=Pedro`          |
| `time_id` | integer | Não         | Restringe a busca a um time específico             | `?time_id=1`        |
| `posicao` | string  | Não         | Filtra por posição (veja valores abaixo)           | `?posicao=atacante` |

### Valores de posição

| Valor      | Descrição                           |
| ---------- | ----------------------------------- |
| `goleiro`  | Goleiro                             |
| `zagueiro` | Zagueiro                            |
| `lateral`  | Lateral (esquerdo ou direito)       |
| `volante`  | Volante / Médio defensivo           |
| `meia`     | Meia (armador, meia-atacante, etc.) |
| `atacante` | Atacante / Centroavante / Ponta     |

### Exemplo — busca por "felipe"

```bash theme={null}
curl -H "Authorization: Bearer SEU_TOKEN" \
  "https://api.dadosfutebol.com.br/v1/jogadores?q=felipe"
```

```json theme={null}
{
  "data": [
    {
      "id": 163,
      "nome_popular": null,
      "nome": "Everton Felipe",
      "idade": null,
      "posicao": "Atacante",
      "numero_camisa": null,
      "gols": 0,
      "time": {
        "id": 382,
        "nome": "Pombal EC",
        "sigla": "PE",
        "escudo_url": "https://assets.dadosfutebol.com.br/escudos/pombal-ec.png"
      }
    },
    {
      "id": 638,
      "nome_popular": null,
      "nome": "Felipe Hulk",
      "idade": null,
      "posicao": "Atacante",
      "numero_camisa": null,
      "gols": 0,
      "time": {
        "id": 175,
        "nome": "Maranguape",
        "sigla": "MAR",
        "escudo_url": "https://assets.dadosfutebol.com.br/escudos/maranguape.png"
      }
    }
  ],
  "meta": {
    "total": 10
  }
}
```

### Erros possíveis

| Código | Motivo                                     |
| ------ | ------------------------------------------ |
| `422`  | `?q=` ausente ou com menos de 2 caracteres |
| `401`  | API Key inválida ou ausente                |

***

## GET /v1/jogadores/:id

Retorna os dados completos de um jogador específico pelo seu ID.

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

```json theme={null}
{
  "data": {
    "id": 638,
    "nome_popular": null,
    "nome": "Felipe Hulk",
    "idade": null,
    "posicao": "Atacante",
    "numero_camisa": null,
    "gols": 0,
    "time": {
      "id": 175,
      "nome": "Maranguape",
      "sigla": "MAR",
      "escudo_url": "https://assets.dadosfutebol.com.br/escudos/maranguape.png"
    }
  }
}
```

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

***

## Campos da resposta de jogador

| Campo           | Tipo    | Descrição                                                                  |
| --------------- | ------- | -------------------------------------------------------------------------- |
| `id`            | integer | Identificador único do jogador                                             |
| `nome_popular`  | string  | Apelido ou nome de guerra (pode ser `null`)                                |
| `nome`          | string  | Nome completo do jogador                                                   |
| `idade`         | integer | Idade em anos (ou `null` se não cadastrada)                                |
| `posicao`       | string  | Posição: `goleiro`, `zagueiro`, `lateral`, `volante`, `meia` ou `atacante` |
| `numero_camisa` | integer | Número da camisa no time atual (ou `null`)                                 |
| `gols`          | integer | Total de gols marcados na temporada                                        |
| `time`          | object  | Dados do clube: `id`, `nome`, `sigla`, `escudo_url`                        |