Soccer Match Calendar Sync

Sincroniza partidas de futebol da API pública do SportScore com o Google Calendar ou gera um arquivo .ics. O sincronizador aceita a agenda de um time ou descobre as partidas de uma competição por sua classificação, chaveamento e agendas dos participantes.

Comportamento da sincronização

• Partidas reagendadas movem o evento existente quando há uma única correspondência segura.
• Partidas adiadas sem nova data permanecem no horário anterior com o prefixo ADIADO.
• Partidas canceladas permanecem visíveis com o prefixo CANCELADO.
• A ausência de uma partida na resposta não é interpretada como cancelamento.
• Os eventos guardam metadados privados do SportScore para evitar duplicações futuras.
• Horários são lidos com o fuso informado pelo provedor e publicados em America/Fortaleza.

Adicione ao seu calendário

Estes são calendários comunitários e não oficiais, atualizados automaticamente com dados do SportScore. Datas e horários podem mudar; confirme informações críticas nos organizadores oficiais.

Calendário	Google Calendar	Apple Calendar, Outlook e outros
Champions League	Adicionar	Endereço iCal
Copa América	Adicionar	Endereço iCal
Eurocopa	Adicionar	Endereço iCal
Copa da Liga Inglesa	Adicionar	Endereço iCal
Ceará	Adicionar	Endereço iCal
Brasil masculino	Adicionar	Endereço iCal
Copa do Mundo masculina	Adicionar	Endereço iCal
Copa do Mundo feminina	Adicionar	Endereço iCal
Brasil feminino	Adicionar	Endereço iCal

No Google Calendar, use Adicionar e confirme a assinatura. Em outros aplicativos, copie o Endereço iCal e escolha a opção de assinar um calendário por URL. Não baixe e importe o arquivo: a importação cria uma cópia que não recebe atualizações futuras. O aplicativo pode demorar algumas horas para buscar uma alteração publicada pelo Google.

Ativação pelo administrador

Antes de divulgar os links, o proprietário deve abrir cada calendário no Google Calendar pelo computador e acessar Configurações e compartilhamento → Autorizações de acesso aos eventos → Disponibilizar ao público. Selecione a opção que mostra todos os detalhes dos eventos.

Divulgue somente o endereço Público no formato iCal. O endereço secreto nunca deve ser publicado, versionado no repositório nem enviado a terceiros. Depois da ativação, abra o endereço iCal em uma janela anônima e confirme que ele responde sem login. Em 12 de agosto de 2026, os nove endereços públicos ainda respondiam 404; conclua esta ativação antes de divulgar ou mesclar os links.

Configuração do Google Calendar

1. Habilite a Google Calendar API em um projeto Google Cloud.
2. Crie uma conta de serviço e baixe sua chave JSON como credentials.json.
3. Compartilhe cada calendário com o e-mail da conta de serviço, permitindo alterar eventos.
4. No GitHub, salve o conteúdo da chave no secret GOOGLE_CREDENTIALS_JSON.

Instalação e uso

uv sync --locked

# Agenda de um time
uv run python match_sync.py gcalendar \
  --target-type team \
  --slug ceara \
  --calendar-id "seu-calendario@group.calendar.google.com"

# Partidas de uma competição
uv run python match_sync.py gcalendar \
  --target-type competition \
  --slug fifa-world-cup \
  --calendar-id "seu-calendario@group.calendar.google.com"

# Arquivo ICS
uv run python match_sync.py ics \
  --target-type team \
  --slug brazil-women \
  --output calendar.ics

Alvos configurados no GitHub Actions

Calendário	Tipo	Slug SportScore
Champions League	competição	uefa-champions-league
Copa América	competição	conmebol-copa-america
Eurocopa	competição	uefa-european-championship
Copa da Liga Inglesa	competição	english-football-league-cup
Ceará	time	ceara
Brasil masculino	time	brazil
Copa do Mundo masculina	competição	fifa-world-cup
Copa do Mundo feminina	competição	fifa-womens-world-cup
Brasil feminino	time	brazil-women

Cada calendário usa uma variável em Settings > Secrets and variables > Actions > Variables:

• GOOGLE_CALENDAR_ID_CHAMPIONS_LEAGUE
• GOOGLE_CALENDAR_ID_COPA_AMERICA
• GOOGLE_CALENDAR_ID_EUROCOPA
• GOOGLE_CALENDAR_ID_ENGLISH_LEAGUE_CUP
• GOOGLE_CALENDAR_ID_CEARA
• GOOGLE_CALENDAR_ID_BRAZIL
• GOOGLE_CALENDAR_ID_WORLD_CUP
• GOOGLE_CALENDAR_ID_WOMENS_WORLD_CUP
• GOOGLE_CALENDAR_ID_BRAZIL_WOMEN

As nove variáveis estão configuradas. O SportScore já reconhece a Copa do Mundo Feminina, mas só publicará jogos de 2027 quando a programação estiver disponível no provedor.

Automação

O workflow executa às 08:00 e 20:00 UTC (05:00 e 17:00 em Fortaleza). Também pode ser executado manualmente pela aba Actions. Workflows agendados podem iniciar alguns minutos depois do horário durante períodos de alta demanda do GitHub. Até dois calendários são processados simultaneamente para reduzir a carga na API pública.

Para validar o acesso ao SportScore no próprio runner sem credenciais nem alterações no Google Calendar, execute o workflow manualmente com dry_run habilitado. Os nove alvos são consultados e geram arquivos ICS temporários; erros do provedor continuam fazendo o job falhar.

O cliente usa curl_cffi com transporte e cabeçalhos compatíveis com Chrome. Desde 9 de setembro de 2026, o Cloudflare do SportScore responde às requisições do cliente requests nos runners do GitHub com 403 e CF-Mitigated: challenge; trocar somente o User-Agent não resolve. O transporte foi validado no mesmo ambiente. Falhas de conexão, 429 e erros temporários do servidor mantêm tentativas limitadas com backoff e respeito ao Retry-After. Se um desafio persistir, o erro inclui o identificador CF-Ray para diagnóstico e a sincronização falha antes de alterar eventos.

Testes

uv run python -m unittest -v

CI/CD

O repositório é um único worker/CLI Python 3.11. O check obrigatório CI / required valida o lockfile, formatação, lint, tipos, sintaxe, testes e segurança dos workflows em pull requests, pushes para main e execuções manuais. Ele não recebe segredos nem altera calendários.

O workflow agendado existente é a entrega operacional: usa credenciais de produção para atualizar os calendários duas vezes ao dia. Build, publicação de pacote, banco de dados, browser, mobile e monorepo não se aplicam. Testes contra SportScore e Google Calendar reais ficam fora do check porque dependem de serviços externos ou de produção; a suíte obrigatória usa mocks e contratos determinísticos. As razões, limites e condição de revisão estão registradas em docs/decisions/0001-ci-cd.md.

Créditos

Os dados de partidas, competições, times, horários e status utilizados por este projeto são fornecidos pelo SportScore. A disponibilidade e a atualização dessas informações dependem do provedor.

Licença

MIT.