majiayu000 Cartola API - Knowledge Base
Base de conhecimento completa das APIs oficiais do Cartola FC. Fonte: caRtola Wiki - Lista de links para API
Base URLs
A API migrou de domínio ao longo dos anos:
- Atual (2024+):
https://api.cartola.globo.com - Legado:
https://api.cartolafc.globo.com
Ambos podem funcionar. O sistema usa api.cartola.globo.com no cartolaApiService.js.
Participante de Teste (Premium)
| Campo | Valor |
|---|---|
| Nome | Paulinett Miranda |
| Time ID | 13935277 |
| Time | Urubu Play F.C. |
| Status | Assinante Premium (Cartola PRO) |
| Endpoint teste | GET /time/id/13935277 |
Referências Detalhadas
- Endpoints completos: Ver references/api-endpoints.md para lista completa de todos endpoints públicos e autenticados
- Schemas de resposta: Ver references/response-schemas.md para estrutura JSON de cada endpoint
Quick Reference - Endpoints Mais Usados
Públicos (sem autenticação)
| Endpoint | Descrição |
|---|---|
GET /mercado/status |
Status do mercado, rodada atual, fechamento |
GET /atletas/mercado |
Todos atletas disponíveis no mercado |
GET /atletas/pontuados |
Pontuação da rodada atual |
GET /atletas/pontuados/{rodada} |
Pontuação de rodada específica |
GET /time/id/{id} |
Dados do time (escalação atual) |
GET /time/id/{id}/{rodada} |
Dados do time em rodada específica |
GET /time/slug/{slug} |
Time por slug |
GET /times?q={query} |
Buscar times por nome |
GET /liga/{slug} |
Dados de uma liga pública |
GET /ligas?q={query} |
Buscar ligas por nome |
GET /clubes |
Todos os clubes do Brasileirão |
GET /rodadas |
Lista das 38 rodadas |
GET /partidas |
Próximas partidas |
GET /partidas/{rodada} |
Partidas de rodada específica |
GET /esquemas |
Formações táticas disponíveis |
GET /mercado/destaques |
Jogadores mais escalados |
GET /pos-rodada/destaques |
Destaques pós-rodada |
Autenticados (requer X-GLB-Token)
| Endpoint | Descrição |
|---|---|
GET /auth/time |
Time do usuário logado |
GET /auth/time/info |
Info detalhada do time logado |
GET /auth/ligas |
Ligas do usuário logado |
GET /auth/liga/{slug} |
Liga específica (com dados privados) |
POST /auth/time/salvar |
Salvar escalação |
Autenticação
Header: X-GLB-Token: <token>
O token é obtido via login Globo.com (OAuth). Para endpoints /auth/* é obrigatório.
Integração no Projeto
O serviço services/cartolaApiService.js implementa:
- Retry com backoff exponencial (1s, 2s, 4s)
- Cache via NodeCache (TTL 5min padrão)
- Timeout de 15s
- Validação de scout data
- Detecção dinâmica de rodada atual
Métodos Disponíveis
import cartolaApi from '../services/cartolaApiService.js';
await cartolaApi.obterStatusMercado() // /mercado/status
await cartolaApi.obterTimesLiga(ligaId) // /liga/{id}
await cartolaApi.obterDadosTimeRodada(timeId, rodada) // /time/id/{id}/{rodada}
await cartolaApi.buscarTimePorNome(query, limit) // /times?q=
await cartolaApi.buscarTimePorId(timeId) // /time/id/{id}
await cartolaApi.buscarTimePorIdCompleto(timeId) // /time/id/{id} (raw)
await cartolaApi.coletarGolsLiga(ligaId, rodada) // Coleta gols via /atletas/pontuados
await cartolaApi.getRodadaStatus(rodada) // Status derivado do mercado
Mapeamentos Críticos
Posições (posicao_id)
| ID | Posição | Abreviação |
|---|---|---|
| 1 | Goleiro | GOL |
| 2 | Lateral | LAT |
| 3 | Zagueiro | ZAG |
| 4 | Meia | MEI |
| 5 | Atacante | ATA |
| 6 | Técnico | TEC |
Status do Mercado (status_mercado)
| Código | Status |
|---|---|
| 1 | Mercado aberto |
| 2 | Mercado fechado |
| 4 | Manutenção |
| 6 | Fim de temporada |
| 15 | Mercado em atualização |
Scouts Principais
| Sigla | Significado | Pontos |
|---|---|---|
| G | Gol | +8.0 |
| A | Assistência | +5.0 |
| FT | Finalização na trave | +3.5 |
| FD | Finalização defendida | +1.2 |
| FF | Finalização pra fora | +0.8 |
| FS | Falta sofrida | +0.5 |
| PE | Passes errados | -0.3 |
| I | Impedimento | -0.1 |
| FC | Falta cometida | -0.3 |
| GC | Gol contra | -3.0 |
| CV | Cartão vermelho | -3.0 |
| CA | Cartão amarelo | -1.0 |
| SG | Sem gol sofrido (goleiro/zagueiro) | +5.0 |
| DD | Defesa difícil | +3.0 |
| GS | Gol sofrido | -1.0 |
| DS | Desarme | +1.2 |
| PP | Pênalti perdido | -4.0 |
| DP | Defesa de pênalti | +7.0 |
| PC | Passe completo (>30) | +0.3 |