Documentacao v1

Documentacao da camada de dados do FutAI.

A MasterFut API entrega os dados esportivos usados pelo FutAI. Os endpoints REST sao autenticados por API key e consultam esportes, paises, ligas, temporadas, times, partidas, classificacoes e resumo estatistico.

Base URL

http://masterfut.site/api/v1

Fluxo FutAI

O app FutAI deve usar os endpoints JSON em `/api/app` para criar conta, fazer login e obter uma API key. Depois disso, a mesma chave autentica as chamadas em `/api/v1`.

POST /api/app/register

Cria o usuario e retorna uma API key em texto puro uma unica vez.

{
  "name": "Cliente FutAI",
  "email": "cliente@email.com",
  "password": "senha-segura",
  "password_confirmation": "senha-segura",
  "api_key_name": "FutAI Desktop"
}

POST /api/app/login

Valida email/senha e pode emitir uma nova chave para o dispositivo. Se o limite de 3 chaves estiver cheio, envie `revoke_oldest: true` para substituir a chave ativa mais antiga.

GET /api/app/me

Retorna usuario, chave atual e limites. Requer `Authorization: Bearer sua_chave`.

GET/POST/DELETE /api/app/api-keys

Lista, cria e revoga chaves do usuario autenticado. O token completo so aparece na criacao.

Autenticacao

Todas as requisicoes em `/api/v1` exigem uma API key vinculada ao usuario. Para o usuario final, cadastro, login e acesso acontecem dentro do app FutAI; a API fica como camada de dados e controle de consumo.

Header recomendado

Authorization: Bearer sua_chave

Header alternativo

X-API-Key: sua_chave

No plano free, cada usuario pode manter ate 3 API keys ativas e realizar ate 10 requisicoes por minuto. O limite e aplicado por usuario, somando todas as chaves ativas.

Quickstart

A API responde em JSON. Inclua sua chave em todas as chamadas.

curl "http://masterfut.site/api/v1/metadata" \
  -H "Authorization: Bearer sua_chave"

fetch('http://masterfut.site/api/v1/matches?status=finished', {
  headers: { Authorization: 'Bearer sua_chave' }
})
  .then(response => response.json())
  .then(data => console.log(data.data));

Paginacao e formato

Listagens retornam uma estrutura paginada com `data`, `links` e `meta`. Use o parametro `page` para navegar.

GET http://masterfut.site/api/v1/teams?page=2
Authorization: Bearer sua_chave

data

Itens retornados.

links

URLs de navegacao.

Endpoints

GET /metadata

Informacoes gerais da API, totais e frescor dos dados.

GET /sports

Lista de esportes disponiveis.

GET /countries

Lista de paises cadastrados.

GET /leagues

Lista de ligas e competicoes. Filtros: sport, country, active, updated_since.

GET /seasons

Temporadas disponiveis. Filtro: updated_since.

GET /teams

Times cadastrados. Filtros: sport, country, league_id, updated_since.

GET /matches

Partidas. Filtros: league_id, season_id, team_id, status, date_from, date_to, updated_since.

GET /matches/{id}

Detalhe de uma partida especifica.

GET /standings

Classificacoes por liga e temporada. Filtros: league_id, season_id, updated_since.

GET /stats/summary

Resumo numerico da base disponivel.

Exemplos de uso

Buscar ligas ativas

GET http://masterfut.site/api/v1/leagues?active=1
Authorization: Bearer sua_chave

Buscar partidas finalizadas de uma liga em um periodo

GET http://masterfut.site/api/v1/matches?league_id=1&status=finished&date_from=2026-01-01&date_to=2026-12-31
Authorization: Bearer sua_chave

Buscar partidas de um time

GET http://masterfut.site/api/v1/matches?team_id=10
Authorization: Bearer sua_chave

Buscar classificacao de uma temporada

GET http://masterfut.site/api/v1/standings?league_id=1&season_id=1
Authorization: Bearer sua_chave

Atualizacoes incrementais

Use `updated_since` para buscar registros alterados depois de uma data.

GET http://masterfut.site/api/v1/teams?updated_since=2026-06-01
Authorization: Bearer sua_chave

Codigos e boas praticas

200

Requisicao processada com sucesso.

401

API key ausente, invalida ou revogada.

429

Limite de requisicoes por minuto atingido.

404

Registro ou rota nao encontrada.

422

Parametro invalido.

500

Erro inesperado. Tente novamente ou contate suporte.

Recomendacao: armazene respostas em cache quando possivel, use filtros para reduzir payloads e prefira consultas paginadas para telas grandes.