⚽ Super Brasa Fut API
Super Brasa Fut é uma API RESTful de alta performance para dados esportivos de futebol brasileiro, sul-americano e mundial. Fornece placares ao vivo, eventos de partidas, estatísticas detalhadas, tabelas de classificação, elencos reais completos (539 atletas cadastrados), estádios oficiais mapeados com capacidade de público, escudos de alta resolução, mercado, comparação de jogadores, cotações de apostas (odds), chaveamento de copas com playoffs, streaming em tempo real via Server-Sent Events (SSE), motor de simulação de partidas, sistema de Webhooks e motor de ingestão contínua e sincronização em segundo plano com o Flashscore oficial (centenas de ligas e partidas globais).
🏆 Campeonatos Cadastrados (23 Competições)
A API cobre 23 das maiores competições do planeta:
🇧🇷 Futebol Brasileiro
- Brasileirão Série A 2026 (
bra-serie-a-2026)
- Brasileirão Série B 2026 (
bra-serie-b-2026)
- Copa do Brasil 2026 (
bra-copa-do-brasil-2026)
- Brasileirão Sub-17 2026 (
bra-sub-17-2026)
🌐 Torneios Globais & Internacionais (FIFA / Seleções)
- Copa do Mundo FIFA 2026 (
fifa-world-cup-2026)
- Mundial de Clubes FIFA 2026 (
fifa-club-world-cup-2026)
- Copa Intercontinental da FIFA 2026 (
fifa-intercontinental-cup-2026)
- Mundial Sub-20 Feminino FIFA 2026 (
fifa-wwc-u20-2026)
- Eliminatórias Copa do Mundo - América do Sul 2026 (
conmebol-wc-qualifiers-2026)
- UEFA Nations League 2026/27 (
uefa-nations-league-2026)
- Copa Ouro CONCACAF 2026 (
concacaf-gold-cup-2026)
🌎 Competições Continentais de Clubes
- Copa Libertadores 2026 (
conmebol-libertadores-2026)
- Copa Sul-Americana 2026 (
conmebol-sudamericana-2026)
- UEFA Champions League 2026/27 (
uefa-champions-league-2026)
- UEFA Women's Champions League 2026 (
uefa-wcl-2026)
- AFC Champions League Elite 2026/27 (
afc-champions-league-2026 - Ásia)
- Liga dos Campeões da CAF 2026/27 (
caf-champions-league-2026 - África)
🌍 Ligas Nacionais Internacionais
- Premier League 2026/27 (
eng-premier-league-2026 - Inglaterra)
- LaLiga 2026/27 (
esp-laliga-2026 - Espanha)
- Serie A Italiana 2026/27 (
ita-serie-a-2026 - Itália)
- Bundesliga 2026/27 (
ger-bundesliga-2026 - Alemanha)
- Primeira A Colômbia 2026 (
col-primera-a-2026 - Colômbia)
- Copa Chile 2026 (
chi-copa-chile-2026 - Chile)
👥 Elencos, Estádios e Escudos Oficiais
- 539 Atletas Reais: Elencos completos (16 a 20 atletas) para todos os 20 clubes do Brasileirão Série A, Série B (Santos, Sport, Novorizontino, Operário, CRB, Avaí, Athletic Club), Seleções Principais (Brasil, Argentina, França, Alemanha) e gigantes internacionais (Real Madrid, Barcelona, Man City, Arsenal, Al-Hilal), com números de camisa, posições, idades, valores de mercado e estatísticas de temporada.
- 65 Estádios Mapeados: 100% das equipes e partidas possuem estádios oficiais cadastrados com nome oficial, cidade e capacidade exata de público (ex: Maracanã, MorumBIS, Neo Química Arena, Allianz Parque, Mineirão, Beira-Rio, Rei Pelé, Ressacada, Santiago Bernabéu, etc.).
- Escudos Oficiais (Logos): 100% dos clubes com
logoUrl em alta resolução sincronizado em tabelas de classificação, chaves de mata-mata, partidas e no objeto do clube em cada jogador.
- Sincronização Flashscore: Integração de partidas em tempo real alinhadas com o Flashscore oficial (
https://www.flashscore.com.br/), incluindo links diretos das partidas, eventos, placares e status temporal preciso.
🚀 Como Iniciar o Projeto
Pré-requisitos
- Node.js v18+ (recomendado Node.js 20 ou 22)
- npm
Instalação e Execução
# 1. Instalar dependências
npm install
# 2. Validar e sincronizar sementes de dados
npm run seed
# 3. Iniciar em modo de desenvolvimento (com hot-reload)
npm run dev
# 4. Rodar a suíte completa de testes (162 testes 100% aprovados)
npm test
# 5. Verificação de tipos (inclui os testes) e cobertura
npm run typecheck
npm run test:coverage
# 6. Compilar o projeto TypeScript para produção
npm run build
# 7. Executar build de produção
npm start
📡 Documentação Interativa
Com o servidor rodando, acesse a documentação OpenAPI / Swagger:
🔑 Autenticação e Planos de Acesso (X-API-Key)
A API suporta requisições anônimas ou autenticadas via cabeçalho HTTP X-API-Key:
| Plano | Variável da chave | Limite de Taxa | Benefícios |
|---|
| Público / Free | (sem header ou API_KEY_FREE) | RATE_LIMIT_FREE (60 req/min) | Acesso completo a todas as consultas |
| Pro | API_KEY_PRO | RATE_LIMIT_PRO (300 req/min) | Maior vazão, Webhooks e suporte a odds |
| Enterprise | API_KEY_ENTERPRISE | RATE_LIMIT_ENTERPRISE (1000 req/min) | Limite corporativo para alta concorrência |
As chaves e os limites por minuto vêm de variáveis de ambiente (veja .env.example). O repositório traz valores apenas para desenvolvimento; em produção defina chaves próprias e fortes.
Em produção (NODE_ENV=production), os planos Pro e Enterprise só são aceitos se API_KEY_PRO / API_KEY_ENTERPRISE estiverem definidas no ambiente. Sem elas, os valores default do repositório são desativados (o acesso público/free continua funcionando) e um aviso é registrado no boot. Isso impede que as chaves de exemplo concedam escrita (webhooks, simulação, reset).
Os endpoints de escrita (simulação de partidas, reset e Webhooks) exigem uma chave Pro ou Enterprise.
Cabeçalhos de segurança
O Helmet aplica a política padrão (incluindo Content-Security-Policy) em todas as respostas da API. Apenas as rotas /docs e /api-docs (Swagger UI, que injeta assets inline) recebem o Helmet sem CSP.
Verifique o status da sua chave via:
GET /api/v1/auth/verify
Header: x-api-key: $API_KEY_PRO
⚡ Streaming em Tempo Real (SSE)
Para conectar seu frontend ou bot a um feed ao vivo com zero latência:
GET /api/v1/matches/live/stream
Accept: text/event-stream
Exemplo em JavaScript:
const eventSource = new EventSource('http://localhost:3000/api/v1/matches/live/stream');
eventSource.addEventListener('matches', (event) => {
const liveMatches = JSON.parse(event.data);
console.log('Partidas ao vivo atualizadas:', liveMatches);
});
🎮 Motor de Simulação ao Vivo
Para testes de interface, streaming e desenvolvimento sem depender de partidas reais no momento:
- Avançar tempo do jogo (5 min + stats):
POST /api/v1/matches/:id/simulate-tick
- Disparar evento dinâmico (Gol, Cartão, Substituição):
POST /api/v1/matches/:id/simulate-event
Content-Type: application/json
{
"type": "GOAL",
"team": "home",
"player": "Estêvão",
"minute": 78
}
- Restaurar estado original das partidas:
POST /api/v1/matches/reset
🔔 Sistema de Webhooks
Cadastre endpoints para receber notificações imediatas quando sair um gol ou ocorrer evento relevante.
O recurso exige uma chave Pro ou Enterprise (x-api-key).
- Criar Assinatura:
POST /api/v1/webhooks
x-api-key: $API_KEY_PRO
Content-Type: application/json
{
"url": "https://meu-servidor.com/webhook/gols",
"events": ["GOAL", "MATCH_EVENT"],
"secret": "meu-token-secreto"
}
- Listar Assinaturas:
GET /api/v1/webhooks
- Remover Assinatura:
DELETE /api/v1/webhooks/:id
- Histórico de Entregas:
GET /api/v1/webhooks/deliveries (ou por webhook: GET /api/v1/webhooks/:id/deliveries)
- Reenvio Manual (Redeliver):
POST /api/v1/webhooks/deliveries/:id/redeliver
O corpo do POST é validado com Zod: url é obrigatória, events aceita apenas GOAL, MATCH_EVENT, MATCH_STATUS_CHANGE e ALL, e secret (quando enviado) precisa ter ao menos 8 caracteres. Requisições inválidas recebem 422 VALIDATION_ERROR com o campo problemático em error.details.
Multi-tenant: cada assinatura pertence à X-API-Key que a criou. GET, GET /:id, DELETE e o histórico de entregas (/deliveries) só enxergam webhooks da própria chave — acessar assinatura de outra chave retorna 404 (sem vazar existência). O secret de assinatura nunca é devolvido em respostas; o campo secretSet indica se o webhook possui segredo para verificação de assinatura.
Eventos emitidos hoje: GOAL e MATCH_EVENT (via POST /matches/:id/simulate-event) e MATCH_STATUS_CHANGE (quando o avanço do relógio muda o status da partida, ex.: LIVE → HALFTIME / FINISHED).
🔁 Resiliência e Retentativas (Exponential Backoff)
Quando o endpoint receptor responde com erro de servidor (5xx, 429) ou sofre timeout/queda de rede, a API realiza até 3 tentativas automáticas (WEBHOOK_MAX_RETRIES) com backoff exponencial (WEBHOOK_RETRY_DELAY_MS), registrando status, latência e tentativas no histórico de auditoria.
🔐 Segurança
- A URL é validada contra SSRF: apenas
http(s) para hosts públicos (bloqueia localhost, IPs privados/reservados e metadata de nuvem); o DNS é revalidado antes de cada disparo. Para testar webhooks com um receptor local, defina WEBHOOK_ALLOW_PRIVATE_HOSTS=true (apenas dev/teste; nunca em produção).
- Cada entrega envia
X-SuperBrasa-Event, X-SuperBrasa-Timestamp, X-SuperBrasa-Delivery e, quando há secret, X-SuperBrasa-Signature com HMAC-SHA256 de timestamp.body (compare com verifyWebhookSignature).
🔄 Motor de Sincronização Flashscore (Scraper & Background Worker)
A API integra um motor nativo autônomo de raspagem e sincronização contínua com o Flashscore oficial (https://www.flashscore.com.br/), capaz de processar centenas de partidas e ligas mundiais sem depender de APIs terceiras pagas:
💾 Persistência de Estado
Por padrão a API roda 100% em memória a partir dos seeds JSON. Para manter webhooks e partidas simuladas entre reinícios (e cold starts em serverless), configure um Redis serverless (Upstash) — a hidratação ocorre no boot:
UPSTASH_REDIS_REST_URL=...
UPSTASH_REDIS_REST_TOKEN=...
Sem essas variáveis, um store em memória é usado automaticamente. O fuso dos filtros de data (date=today) é configurável via TIME_ZONE (padrão America/Sao_Paulo).
🚨 Monitoramento e Alertas
Endpoints de saúde
| Endpoint | Semântica |
|---|
GET /api/v1/health | Liveness — sempre 200 enquanto o processo responde (não depende da persistência) |
GET /api/v1/health/ready | Readiness — 200 {status:"ready"} quando a persistência responde; 503 {status:"degraded"} quando o Upstash falha/timeout |
Monitor externo (recomendado)
Aponte um serviço de uptime (ex.: UptimeRobot) para o readiness. Qualquer resposta não-2xx (o 503) marca o monitor como down e dispara o alerta:
- Tipo: HTTP(s) · Intervalo: 5 min
- URL:
https://<sua-api>/api/v1/health/ready
- Alert contact: e-mail/Slack do time
Keyword monitoring ("status":"ready") exige plano pago e não é necessário — o 503 já sinaliza a queda.
Configuração atual em produção: monitor UptimeRobot (Super Brasa Fut API - /health/ready, intervalo 5 min, alerta por e-mail) apontando para https://api-super-brasa-fut.vercel.app/api/v1/health/ready.
Alertas in-app (opcional)
A própria API pode notificar a mudança de estado (útil quando algo chama o readiness: um monitor, um Cron etc.):
ALERT_WEBHOOK_URL=https://hooks.slack.com/services/... # Slack, Discord, PagerDuty ou genérico
ALERT_COOLDOWN_MS=300000 # evita spam de alertas repetidos (padrão: 5 min)
ALERT_CHECK_INTERVAL_MS=0 # self-check periódico (0 = off; aplica-se a servidor self-hosted)
Fluxo: primeira falha → degraded; quando voltar a responder → recovered. O cooldown evita repetir o alerta a cada verificação enquanto o serviço segue fora. O payload é compatível com Slack (text) e Discord (content) e inclui status, backend, latencyMs e error.
📊 Métricas Prometheus
A API exporta telemetria em tempo real no formato padrão Prometheus em:
GET /metrics ou GET /api/v1/metrics
Métricas incluídas:
- Node.js runtime: consumo de heap, memória residente, CPU, garbage collection e event loop lag (
super_brasa_*).
super_brasa_http_requests_total: volume de requisições por method, route e status_code.super_brasa_http_request_duration_seconds: histograma de latência HTTP.super_brasa_active_sse_connections: gauge de conexões SSE ativas no streaming de partidas ao vivo.super_brasa_webhook_deliveries_total: contador de entregas de webhooks por evento e status (success, failed, retrying).
📚 Principais Endpoints da API
| Método | Endpoint | Descrição |
|---|
GET | / ou /api/v1 | Metadados da API, versão e índice de rotas disponíveis |
GET | /metrics ou /api/v1/metrics | Métricas Prometheus de telemetria e latência |
GET | /api/v1/health | Diagnóstico de integridade e versão |
GET | /api/v1/health/ready | Readiness probe (persistência): 200 pronto / 503 degradado |
GET | /api/v1/auth/verify | Valida a X-API-Key e devolve o plano, o limite e os recursos habilitados |
GET | /api/v1/search?q=flamengo | Busca global (clubes, ligas, atletas, jogos) |
GET | /api/v1/leagues | Lista de campeonatos com filtros |
GET | /api/v1/leagues/:id | Detalhes de um campeonato |
GET | /api/v1/leagues/:id/standings | Tabela de classificação completa (?format=csv suportado) |
GET | /api/v1/leagues/:id/bracket | Árvore de chaveamento e mata-mata (Copas, playoffs) |
GET | /api/v1/leagues/:id/matches | Jogos daquela liga |
GET | /api/v1/leagues/:id/teams |
🛡️ Licença
Este projeto é distribuído sob a licença MIT.
