Rotas e notas de integração
Consulte a Ajuda da interface para instruções orientadas a tarefas e o README em português para instalação e configuração.
Índice
- Estado da API
- Rotas GET públicas
- Visibilidade e ratings dos torneios
- Autenticação e rotas de membros
- Grupos de rotas administrativas
- Orientações para integrações
Estado da API
Os resultados de idempotência concluídos são conservados por pelo menos 90 dias. Os novos usam UTC para a retenção; os anteriores com fuso horário desconhecido são mantidos indefinidamente para evitar expiração prematura.
O campo reviewed_at de um envio é null quando ainda não foi revisado ou quando o fuso de uma revisão anterior é desconhecido; as novas revisões web e API disponibilizam um horário UTC.
A aplicação continua renderizada no servidor e oferece uma API autenticada em /api/v1. As operações v1 são GET /me; consultas de jogadores, rankings, partidas, torneios, participantes, rodadas, emparceiramentos, classificações e relatórios; envios de resultados de membros; moderação administrativa; e comandos de torneios. GET /api/v1/openapi.json fornece o contrato completo. Toda solicitação à API exige um token bearer com o escopo da operação e a permissão atual da função da conta. Crie e gerencie tokens pessoais na página de perfil: administradores escolhem os escopos do token e as demais contas recebem os escopos permitidos pelas funções atuais. As rotas antigas /api/backup, /api/player e /api/tournament não estão implementadas.
As operações são agrupadas em blocos de implantação que os operadores habilitam separadamente com API_ENABLED_SLICES; todos ficam desabilitados por padrão. Os blocos são docs (OpenAPI), reads, submissions, moderation, tournament_setup (criar/configurar), tournament_participants e tournament_rounds (rodadas, resultados e processamento). O documento OpenAPI indica o bloco de cada operação em x-rollout-slice. Um bloco desabilitado retorna 503 com o código api_slice_disabled; um bloco listado em API_STAFF_PILOT_SLICES retorna 503 com api_pilot_restricted para contas que não são da equipe. Configuração, ordem de implantação e reversão estão no README.
Envios de resultados exigem Idempotency-Key; decisões de moderação e comandos condicionais usam If-Match com o ETag atual. Comandos de torneios exigem escopo, permissão e acesso geográfico adequados. PairGo nunca é pontuável e suas partidas aparecem como emparelhamentos, não nas rotas de partidas individuais. Consulte o contrato v1 para requisitos, limites e efeitos de cada operação.
As ações administrativas são envios de formulários HTML. Elas exigem uma sessão autenticada, a função adequada e um token CSRF válido. Algumas ações administrativas assíncronas retornam uma pequena resposta JSON de redirecionamento somente quando a solicitação inclui X-Requested-With: XMLHttpRequest; isso é um comportamento interno do navegador, não um contrato de API versionado.
Rotas GET públicas
Estas páginas podem ser abertas sem uma conta de administrador:
| Rota | Finalidade |
|---|---|
/ |
Página inicial, resumo do ranking, estatísticas e notícias publicadas |
/rankings |
Ranking público paginado |
/players |
Diretório e filtros de jogadores |
/player/view?id=<player_id> |
Perfil e histórico de partidas de um jogador |
/matches |
Lista e filtros de partidas |
/tournaments |
Lista de torneios públicos |
/tournaments/<tournament_id> |
Detalhes, emparelhamentos e classificação de um torneio |
/tournaments/<tournament_id>/matches/<pairing_id> |
Detalhes de uma partida PairGo pública |
/reports |
Relatórios por período e jogador |
/reports/export.csv |
Versão CSV dos filtros selecionados |
/reports/export.pdf |
Versão PDF dos filtros selecionados |
/category |
Informações de rating Glicko e categorias |
/sgf-library |
Biblioteca pública de SGF |
/sgf-library/<filename> |
Metadados de um registro SGF |
/sgf/<filename> |
Download de um registro SGF |
/matches/<match_id>/record |
Visualização do SGF vinculado a uma partida |
/matches/<match_id>/sgf |
Download do SGF vinculado a uma partida |
/news/<article_id> |
Artigo de notícia publicado |
A maioria das páginas aceita o parâmetro opcional lang=es, lang=en ou lang=pt. /rankings aceita country (ISO 3166-1 alpha-3; códigos alpha-2 antigos também são reconhecidos), region=latam e group=u18|women. Se region for omitido, usa-se a região definida pelo administrador, inicialmente América Latina; region=all ou region= inclui todas as regiões. Os filtros se intersectam, portanto um país fora da América Latina exige selecionar todas as regiões quando ela é o padrão. GET /api/v1/rankings usa o mesmo padrão e as mesmas opções de região; seus filtros group repetidos usam OR, enquanto os grupos na web se intersectam. O grupo u18 também inclui jogadores sub-18 com ano de nascimento desconhecido. Os relatórios também aceitam start_date, end_date e player_id; consulte o guia da interface para exemplos.
Visibilidade e ratings dos torneios
O campo API last_active do jogador é a data da última partida individual pública jogada, ou null quando nenhuma é válida. Inclui partidas individuais não pontuáveis; exclui rascunhos, canceladas, PairGo, BYEs, ausências e datas inválidas. GET /api/v1/players?last_active_days=N usa um limite inclusivo a partir da data atual da aplicação, e sort=activity usa a mesma data. Os filtros de atividade dos rankings web usam a mesma elegibilidade. A migração na inicialização preenche as datas existentes; a atualização normal das estatísticas e as mudanças de visibilidade as mantêm atuais sem alterar a elegibilidade do rating.
Comportamento atual:
/tournamentslista torneios ativos e concluídos. Organizadores, gestores e administradores também podem incluir rascunhos comshow_drafts=1; torneios cancelados são excluídos da lista.- Detalhes individuais cancelados continuam acessíveis por link web direto e com
tournaments:readna API autenticada. Páginas web de detalhes PairGo cancelados continuam exclusivas para o pessoal. - As páginas públicas de partidas e os perfis ocultam partidas vinculadas a torneios em rascunho ou cancelados. O histórico de torneios nos perfis de jogadores inclui apenas torneios concluídos.
- O recálculo de ratings inclui partidas independentes e partidas vinculadas a torneios concluídos pontuáveis. Partidas de torneios não pontuáveis, ativos, em rascunho ou cancelados não afetam os ratings.
- PairGo nunca é pontuável. As duplas têm dois jogadores sem restrições de gênero; suas partidas aparecem na lista web e nos dois perfis, mas não alteram estatísticas individuais nem confrontos diretos.
- Alterar o status de um torneio de modo que partidas concluídas sejam incluídas ou removidas marca a data afetada mais antiga, sem recalcular os ratings imediatamente. Use o recálculo completo ou a atualização incremental em
/admin/ratingspara aplicar a alteração.
Essas regras se aplicam às partidas vinculadas por meio de um emparelhamento do torneio; partidas independentes continuam contando para os ratings. Consulte FUTURE_FEATURES.md para outras propostas pendentes.
Autenticação e rotas de membros
| Rota | Método | Acesso |
|---|---|---|
/admin/login |
GET, POST | Entrar |
/admin/register |
GET, POST | Criar uma conta de membro |
/admin/forgot-password |
GET, POST | Solicitar um link de recuperação |
/admin/reset-password/<token> |
GET, POST | Concluir a recuperação |
/admin/report-results |
GET, POST | Enviar resultados do jogador vinculado ou solicitar vínculo com jogador sem conta |
/admin/profile |
GET, POST | Gerenciar o perfil da conta autenticada |
/admin/logout |
GET | Encerrar a sessão atual |
Os envios de membros permanecem pendentes até serem revisados. Antes da aprovação, não alteram partidas públicas, ratings ou relatórios.
Membros sem vínculo enviam action=request_player_link e player_id pelo formulário Enviar resultados protegido com CSRF. As solicitações compartilham a página de moderação e seu filtro de status. POST /admin/player-link-requests/<request_id>/approve e /reject exigem um gestor do país/região do jogador ou administrador global. A aprovação vincula o jogador ainda disponível, registra revisão/auditoria e invalida sessões/tokens do membro em uma transação. Aprovações repetidas ou conflitantes não sobrescrevem vínculos. Só é permitida uma solicitação pendente por membro; a rejeição permite nova solicitação. São rotas web, não recursos da API.
Grupos de rotas administrativas
Todas as rotas abaixo exigem uma conta autenticada e permissões conforme a função:
/admin: painel administrativo/admin/analytics:GET /admin/analytics— painel de métricas agregadas do site dos últimos 30 dias, exclusivo para administradores/admin/import: importações de Excel, CSV e OpenGotha/admin/backups: criar, restaurar e excluir backups gerenciados/admin/players,/admin/players/import,/admin/matches: gestão de jogadores e partidas, incluindo a importação de jogadores por CSV/XLSX/admin/ratings,/admin/categories: configuração de ratings e categorias/admin/tournaments: criação e gestão de torneios, com cópia e exclusão em lote de até 100 torneios selecionados/admin/tournaments/<tournament_id>/...: participantes, emparelhamentos, resultados, rodadas e exportação/admin/tournaments/<tournament_id>/participants/add-batche/admin/tournaments/<tournament_id>/participants/remove-batch: inscrever ou remover atomicamente até 100 participantes selecionados/admin/sgf/...: vinculação e exclusão de SGF;/admin/sgf/delete-batchexclui até 100 arquivos selecionados e limpa as referências de partidas vinculadas e envios pendentes/admin/news: gestão de notícias/admin/users,/admin/audit,/admin/settings: contas, auditoria e configurações
Os três níveis da equipe são Global, Regional e País. country_organizer e regional_organizer têm Operações de torneios, incluindo criação de jogadores em torneios, edição/exclusão, partidas, vinculação SGF e fluxos/importação de torneios. country_manager e regional_manager também têm Gestão de dados: importação de jogadores, notícias e moderação de resultados. Jogadores e moderação são filtrados geograficamente; uma partida exige pelo menos um jogador dentro do âmbito e um torneio um país dentro do âmbito. Notícias são conteúdo compartilhado do site. Funções de país exigem um país (com fallback do jogador vinculado); regionais exigem uma região explícita suportada. Sem âmbito compatível, o acesso geográfico é negado. Administradores têm acesso global.
O menu se organiza por tarefas, não por funções: Jogadores e competição, Importações e ratings, Conteúdo e registros de partidas e Administração do site. As permissões não mudam: todas as operações de backup, /admin/import, ratings/categorias, usuários, auditoria, configurações e exclusão de SGF continuam reservadas a administradores. Contas operator e tournament_director migram para regional_manager e regional_organizer, respectivamente, com âmbito da América Latina e invalidação de sessões/tokens. As consultas à API preservam a visibilidade pública; consultas de torneios em rascunho também exigem uma permissão atual da equipe e um âmbito geográfico correspondente.
As rotas POST alteram o estado da aplicação e devem ser usadas pelos formulários renderizados. Os envios OpenGotha por /admin/import ou /admin/tournaments apresentam a mesma prévia de revisão antes da aprovação explícita; a prévia temporária fica vinculada ao usuário, ao arquivo e ao estado do banco de dados e expira após 15 minutos. Ações de backup, restauração, importação, exclusão e torneios não são expostas como operações GET sem autenticação. Ações em lote exigem as mesmas permissões de função e proteção CSRF que suas equivalentes individuais; ações em lote de participantes de torneios também exigem chaves de idempotência.
Orientações para integrações
Para uma integração externa, use as operações autenticadas documentadas da API para os fluxos disponíveis e as exportações CSV/PDF para os demais relatórios. Não faça scraping de formulários administrativos nem dependa de respostas JSON não documentadas.
As etapas A0-A6 estão concluídas; seus procedimentos e observações estão nas notas operacionais. O roteiro contém apenas propostas e verificações pendentes. Consulte GET /api/v1/openapi.json para parâmetros e esquemas.
O contrato OpenAPI 3.1 aprovado e suas decisões de autenticação, permissões e formato estão disponíveis no contrato da API v1 e no documento OpenAPI legível por máquina. Use um token pessoal com o escopo exato exigido por cada operação; envie tokens somente no cabeçalho Authorization e por HTTPS. Com um prefixo de caminho como /glicko, use as URLs com prefixo retornadas em Location e na entrada servers do documento OpenAPI.
Exemplo de solicitação (PowerShell; mantenha o token em uma variável de ambiente, nunca na URL):
$headers = @{ Authorization = "Bearer $env:GLICKO_API_TOKEN" }
Invoke-RestMethod -Uri "https://example.org/api/v1/rankings?per_page=5" -Headers $headers
Para verificar uma implantação, execute o cliente de teste (usa apenas a biblioteca padrão) com um token piloto. Ele envia apenas sondagens sem efeitos colaterais, exceto com --write-draft-tournament, que cria um rascunho e deve ser usado somente com dados descartáveis:
$env:GLICKO_API_TOKEN = "<token piloto>"
python scripts/api_smoke_test.py --base-url https://example.org --expect-enabled docs,reads --expect-disabled submissions,moderation,tournament_setup,tournament_participants,tournament_rounds
Ele imprime um relatório JSON e termina com 0 quando todas as verificações passam, 1 quando alguma falha e 2 para uso inválido.