POST `/ipulse/scoreboard`

Retorna o placar de hoje e amanhã para uma competição de futebol, com dados em tempo real via Sportmonks. Em caso de rate limit (429) da Sportmonks, a rota cai automaticamente para a API balldontlie (apenas Copa do Mundo).

Consulte a Visão Geral do IPulse para entender autenticação e ligas disponíveis.

Autenticação

Requer header ifw-ipulse-key com a API key fixa configurada no ambiente.

Header	Valor
`ifw-ipulse-key`	`<api_key>`

Limite de requisições (throttling)

Cada solicitante (partner) pode fazer no máximo 80 requisições por dia civil (reset à meia-noite no fuso America/Sao_Paulo). Ao estourar, a rota responde 429 sem processar o placar.

O contador é por solicitante resolvido: loop → TalentWeb, qualquer outro valor (ou ausente) → Nexai.
O limite é configurável em runtime via feature_settings (contexto Scoreboard, chave DailyRequestLimit); sem essa linha, vale o padrão 80.
Toda resposta inclui os headers abaixo; o 429 inclui também Retry-After.

Header	Descrição
`X-RateLimit-Limit`	Cota diária do solicitante
`X-RateLimit-Remaining`	Requisições restantes no dia
`X-RateLimit-Reset`	Unix timestamp do próximo reset (meia-noite São Paulo)
`Retry-After`	(apenas no `429`) segundos até o reset

Request

Query Parameters

Parâmetro	Tipo	Obrigatório	Descrição
`leagueId`	`int`	—	ID da liga no Sportmonks. Padrão: `648` (Campeonato Brasileiro Série A). Ignorado quando a flag `Active` está ligada no `feature_settings`.
`referenceDate`	`datetime`	—	Data de referência. Padrão: hoje
`partner`	`string`	—	Identifica o solicitante para log e throttling: `loop` ou `nexai`. Padrão: `nexai`

curl -s -X POST "https://servicos.ifollowtech.com.br/ipulse/scoreboard?leagueId=648&partner=loop" \
  -H "ifw-ipulse-key: SUA_API_KEY"

Response

`200 OK`

{
  "ShortMessage": "SCOREBOARD",
  "Response": {
    "competition": {
      "name": "Campeonato Brasileiro Série A",
      "series": "2025",
      "stage": "REGULAR_SEASON",
      "stage_name_pt": "Temporada Regular",
      "round": "Rodada 12",
      "logo": "https://cdn.sportmonks.com/images/soccer/leagues/648.png"
    },
    "result": {
      "scoreboard": {
        "update_required": true,
        "games": [
          {
            "match_id": "19082541",
            "scheduled_at": "2025-05-04T18:00:00-03:00",
            "scheduled_date": "2025-05-04",
            "scheduled_time": "18:00",
            "stage": "REGULAR_SEASON",
            "stage_name_pt": "Temporada Regular",
            "home_team": {
              "id": 2456,
              "name": "Flamengo",
              "name_pt": "Flamengo",
              "acronym": "FLA",
              "logo": "https://cdn.sportmonks.com/images/soccer/teams/8/2456.png"
            },
            "away_team": {
              "id": 2450,
              "name": "Palmeiras",
              "name_pt": "Palmeiras",
              "acronym": "PAL",
              "logo": "https://cdn.sportmonks.com/images/soccer/teams/2/2450.png"
            },
            "home_score": 1,
            "away_score": 0,
            "status": "IN_PROGRESS",
            "minute": 67,
            "progress_percentage": 74
          }
        ]
      }
    },
    "metadata": {
      "source": "sportmonks",
      "region": "BR",
      "last_update": "2025-05-04T18:22:00",
      "ping": {
        "active": true,
        "status": "ATIVO",
        "last_ping_at": "2025-05-04T18:22:00-03:00"
      }
    }
  },
  "Messages": [],
  "HttpStatusCode": 200
}

Fuso horário: todos os horários de partida (scheduled_at, scheduled_time) são retornados no fuso de São Paulo (-03:00). A lista games combina hoje e amanhã, ordenada por status → horário → id.

Descrição dos campos de resposta

`competition`

Campo	Tipo	Descrição
`name`	`string`	Nome da competição (PT-BR quando disponível)
`series`	`string`	Nome da temporada/série
`stage`	`string`	Fase da competição em código (ver tabela de fases abaixo)
`stage_name_pt`	`string`	Nome da fase em português (ex: `"Quartas de Final"`)
`round`	`string`	Rodada atual
`logo`	`string`	URL do logo da competição

Fases da competição (`stage`)

Valor	`stage_name_pt`
`REGULAR_SEASON`	Temporada Regular
`GROUP_STAGE`	Fase de Grupos
`ROUND_OF_32`	Fase de 32
`ROUND_OF_16`	Oitavas de Final
`QUARTER_FINALS`	Quartas de Final
`SEMI_FINALS`	Semifinais
`THIRD_PLACE_FINAL`	Disputa de 3º Lugar
`FINAL`	Final
`PLAY_OFFS`	Playoffs
`QUALIFICATION`	Classificatória
`PRELIMINARY_ROUND`	Rodada Preliminar
`UNKNOWN`	Fase não identificada

`result.scoreboard`

Campo	Tipo	Descrição
`update_required`	`boolean`	`true` se houver partida em andamento — indica que o cliente deve atualizar periodicamente
`games`	`array`	Lista de partidas (hoje + amanhã) ordenadas por status → horário → id

Partida (`games[]`)

Campo	Tipo	Descrição
`match_id`	`string`	ID da partida (Sportmonks ou balldontlie, conforme a fonte)
`scheduled_at`	`string`	Data e hora em São Paulo (`yyyy-MM-ddTHH:mm:ss-03:00`)
`scheduled_date`	`string`	Data no formato `yyyy-MM-dd` (São Paulo)
`scheduled_time`	`string`	Hora no formato `HH:mm` (São Paulo)
`stage`	`string`	Fase da partida em código
`stage_name_pt`	`string`	Nome da fase em português
`home_team.id`	`int`	ID do time/seleção mandante
`home_team.name`	`string`	Nome do mandante (original)
`home_team.name_pt`	`string`	Nome do mandante em português (quando seleção)
`home_team.acronym`	`string`	Sigla do mandante
`home_team.logo`	`string`	URL do escudo do mandante (vazio no fallback balldontlie)
`away_team.*`	—	Mesmo padrão do `home_team`
`home_score`	`int`	Gols do mandante
`away_score`	`int`	Gols do visitante
`status`	`string`	Status da partida (ver tabela abaixo)
`minute`	`int`	Minuto atual da partida (0 se não iniciada; sempre 0 no fallback balldontlie)
`progress_percentage`	`int`	Percentual de progresso de 0 a 100

Status possíveis

Valor	Descrição
`SCHEDULED`	Partida não iniciada
`IN_PROGRESS`	Partida em andamento
`FINISHED`	Partida encerrada
`POSTPONED`	Partida adiada
`CANCELLED`	Partida cancelada
`ABANDONED`	Partida abandonada
`SUSPENDED`	Partida suspensa
`UNKNOWN`	Status não mapeado — tratar como indisponível

`metadata`

Campo	Tipo	Descrição
`source`	`string`	Fonte dos dados: `"sportmonks"` (normal) ou `"balldontlie"` (fallback de 429)
`region`	`string`	Região dos dados (`"BR"`)
`last_update`	`string`	Data/hora da geração da resposta (São Paulo)
`ping.active`	`boolean`	Indicador de disponibilidade
`ping.status`	`string`	Status textual (`"ATIVO"`)
`ping.last_ping_at`	`string`	Timestamp do último ping (`-03:00`)

Fallback automático (Sportmonks 429 → balldontlie)

Quando a Sportmonks retorna 429 (rate limit), a rota cai automaticamente para a API balldontlie e o campo metadata.source passa a ser "balldontlie". Limitações desse modo:

Apenas Copa do Mundo (temporadas 2018/2022/2026). Não substitui dados de outras ligas (ex.: Brasileirão). A temporada usada é o ano da data de referência.
minute sempre 0 e progress_percentage baseado apenas no status (sem minuto ao vivo).
logo dos times vem vazio (a balldontlie não fornece escudos).
O filtro por MatchId da flag (específico de IDs Sportmonks) não se aplica no fallback.

Requer a variável de ambiente BALLDONTLIE_API_KEY configurada no servidor.

`401 Unauthorized`

Header ifw-ipulse-key ausente ou inválido.

`429 Too Many Requests`

Solicitante (partner) atingiu o limite diário. Veja os headers X-RateLimit-* e Retry-After.

{
  "ShortMessage": "RATE_LIMIT_EXCEEDED",
  "Response": null,
  "Messages": [
    {
      "Type": "Error",
      "Code": "429",
      "Message": "Limite diário de 80 requisições atingido para 'Nexai'. Tente novamente após 2026-06-01T00:00:00-03:00."
    }
  ],
  "HttpStatusCode": 429
}

`500 Internal Server Error`

Erro ao buscar o placar (ex.: erro da Sportmonks diferente de 429, ou falha do fallback).

`503 Service Unavailable`

Variável de ambiente IPULSE_API_KEY não configurada no servidor.

Autenticação​

Limite de requisições (throttling)​

Request​

Query Parameters​

Response​

200 OK​

Descrição dos campos de resposta​

competition​

Fases da competição (stage)​

result.scoreboard​

Partida (games[])​

Status possíveis​

metadata​

Fallback automático (Sportmonks 429 → balldontlie)​

401 Unauthorized​

429 Too Many Requests​

500 Internal Server Error​

503 Service Unavailable​