Documentacao v1

Integre dados de futebol da MasterFut API.

Use endpoints REST autenticados por API key para consultar esportes, paises, ligas, temporadas, times, partidas, classificacoes e resumo estatistico.

Base URL

http://masterfut.site/api/v1

Autenticacao

Todas as requisicoes em `/api/v1` exigem uma API key gerada no painel do usuario. A chave aparece apenas uma vez no momento da criacao.

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.

Gerar API key

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.