Conceitos

Formato das respostas, ids, temporadas, fuso horário, paginação, status e erros.

Formato das respostas

Toda resposta de sucesso usa o mesmo envelope:

Campo	Conteúdo
data	O recurso ou a lista de recursos
paging	Em listas paginadas: next_cursor e limit
meta	Quando o seu plano esconde campos: restricted_fields

Ids

Todos os ids são textos opacos com um prefixo de tipo:

Prefixo	Tipo
cp_	Competição
mt_	Partida
tm_	Time
pl_	Jogador
vn_	Estádio

Os ids são estáveis. Guarde-os como texto.

Temporadas

As temporadas são identificadas pelo rótulo no parâmetro season, por exemplo season=2025/2026. Sem o parâmetro, a API usa a temporada atual. A lista de temporadas de uma competição está em GET /v1/competitions/{competition_id}/seasons.

Datas e fuso horário

Todas as datas seguem o formato ISO 8601 e vêm em UTC. Envie timezone com um fuso IANA, como America/Sao_Paulo, para receber as datas no seu horário. Os filtros date, from e to também são lidos nesse fuso.

GET /v1/matches?date=2026-11-07&timezone=America/Sao_Paulo

Paginação

As listas aceitam limit (de 1 a 100, padrão 50). Quando existem mais itens, paging.next_cursor vem preenchido: envie esse valor em cursor para buscar a próxima página. Cursor null indica a última página.

GET /v1/competitions/cp_4k6Pew8vntAF/matches?limit=20
GET /v1/competitions/cp_4k6Pew8vntAF/matches?limit=20&cursor=bzoyMA

Status da partida

Status	Significado
scheduled	Agendada
live	Em andamento
finished	Encerrada
cancelled	Cancelada

Campos restritos pelo plano

Alguns endpoints do PRO têm campos que só são preenchidos a partir do ULTRA, como xG e rating. Nos planos abaixo, esses campos voltam como null e são listados em meta.restricted_fields:

{
  "data": [{ "player": { "id": "pl_...", "name": "..." }, "goals": 12, "xg": null, "avg_rating": null }],
  "paging": { "next_cursor": null, "limit": 50 },
  "meta": { "restricted_fields": ["xg", "avg_rating", "rated_matches"] }
}

Erros

Os erros sempre têm o formato {"error": {"code", "message"}}:

HTTP	Código	Quando acontece
401	UNAUTHORIZED	Credenciais ausentes ou inválidas
403	PLAN_UPGRADE_REQUIRED	O endpoint ou a opção exige um plano superior
404	NOT_FOUND	Id inexistente, ou previsão e confronto direto não calculados para a partida
422	INVALID_PARAMETER	Parâmetro inválido; a mensagem indica qual
429	RATE_LIMITED	Muitas requisições por minuto
500	INTERNAL_ERROR	Erro inesperado; tente novamente mais tarde

{ "error": { "code": "PLAN_UPGRADE_REQUIRED", "message": "This endpoint requires the PRO plan or higher" } }