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 |