API do desenvolvedor
Documentação da API de classificação de xadrez
A API Chess Rating fornece acesso programático ao mesmo mecanismo de cálculo Elo que alimenta as calculadoras neste site. Os desenvolvedores que criam ferramentas de gerenciamento de clubes, painéis de relatórios de torneios, plataformas de treinamento ou produtos editoriais podem integrar cálculos de classificação diretamente em seus fluxos de trabalho sem reimplementar a lógica da fórmula. Esta documentação abrange endpoints disponíveis, formatos de solicitação e resposta, requisitos de autenticação e a abordagem de controle de versão que mantém as integrações estáveis. Você pode continuar com Widgets de classificação de xadrez incorporáveis para uma orientação relacionada.
Terminais de cálculo disponíveis
A API oferece suporte a três fluxos de trabalho de cálculo principais: alteração de classificação de jogo único (dadas duas classificações, um resultado e um fator K), processamento em lote (vários registros de jogo em uma solicitação) e estimativa de classificação inicial (dada a classificação média do oponente, pontuação e contagem de jogos). Cada endpoint retorna o mesmo resultado detalhado mostrado nas páginas da calculadora, incluindo pontuação esperada, delta de classificação e nova classificação projetada. Para detalhes de implementação e validação, revise a metodologia.
Os pontos finais do modo torneio aceitam uma série ordenada de classificações e resultados dos oponentes, retornando detalhamentos por rodada e totais cumulativos. Todas as respostas incluem metadados sobre qual perfil de regras foi aplicado para que os consumidores posteriores possam verificar as suposições de cálculo.
Autenticação e Limites de Taxa
O acesso à API requer uma chave de API passada como token de portador no cabeçalho de autorização. As chaves estão disponíveis nos níveis gratuito e premium. O nível gratuito permite até 100 solicitações por dia, com um máximo de 10 jogos por solicitação em lote. As chaves premium desbloqueiam maior rendimento, suporte prioritário e acesso a endpoints de processamento de torneios em massa.
Os limites de taxa são aplicados por chave, não por endereço IP. Exceder o limite retorna um status 429 com um cabeçalho Retry-After indicando quando a próxima janela de solicitação será aberta. Todos os limites são documentados nos cabeçalhos de resposta de cada solicitação bem-sucedida.
Perfis de regras e controle de versão
Cada resposta da API inclui um campo regras_profile indicando qual conjunto de suposições foi usado para o cálculo (por exemplo, fide_2024, us_chess_current, generic_elo). Quando os regulamentos da federação mudam, a API adiciona uma nova versão do perfil em vez de modificar as existentes. Isso significa que os sistemas downstream podem fixar uma versão de perfil específica e atualizar de acordo com sua própria programação.
Mudanças importantes são comunicadas com pelo menos 30 dias de antecedência por meio do changelog da API e da lista de discussão do desenvolvedor. Adições ininterruptas (novos campos opcionais, novos perfis) são implantadas continuamente sem interromper as integrações existentes.
Formato de resposta e tratamento de erros
- Todas as respostas retornam JSON com Content-Type: application/json. Cálculos bem-sucedidos retornam 200 com a carga útil do resultado completo.
- Erros de validação (campos ausentes, classificações fora do intervalo, fator K inválido) retornam 422 com uma matriz de erros legível por humanos.
- As falhas de autenticação retornam 401. Chaves expiradas ou revogadas retornam 403 com um URL de reativação.
- Os erros do servidor retornam 500 com um ID de solicitação para escalonamento de suporte. Todas as respostas de erro seguem a mesma estrutura { error, message, request_id }.
Melhores práticas de integração
Armazene em cache cálculos repetidos localmente sempre que possível para minimizar chamadas de API. Para fluxos de trabalho de torneio, use o endpoint em lote em vez de fazer solicitações sequenciais de um único jogo. Sempre inclua o parâmetro regras_profile explicitamente, em vez de depender do padrão do servidor, para que sua integração permaneça determinística mesmo quando a API adicionar novos perfis.
Para software de clube e painéis de treinamento, considere armazenar os resultados calculados e a versão de regras_profile para que você possa auditar ou recalcular mais tarde se as regras da federação mudarem. Isto é especialmente importante para fluxos de trabalho de relatórios oficiais onde a precisão histórica é importante.