Glicko DB

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

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:

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:

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.

^