Documentação da API
Explore a API Balla Stats completa com documentação interativa do Swagger. Teste endpoints, visualize esquemas e autentique diretamente no navegador.
Pré-requisitos
Antes de explorar a documentação da API, você precisa:
- Uma conta Balla Stats
- Compreensão básica de APIs REST
Explore a API Balla Stats completa com documentação interativa do Swagger. Teste endpoints, visualize esquemas e autentique diretamente no navegador.
Experimente os terminais
Executar chamadas de API ao vivo
Ver esquemas
Tipos compatíveis com TypeScript
Autenticação
Suporte a chaves JWT e API
- Acesse documentos da API
- Autenticar no Swagger
- Explorar terminais
- Tente uma chamada de API
- Compreenda os esquemas de resposta
- Padrões comuns de API
Navegue até /api-docs em seu navegador ou clique em API Docs na barra lateral. A UI do Swagger carrega a referência completa da API com todos os endpoints disponíveis.
Clique no botão "Autorizar" na parte superior da página. Insira seu token de portador - um JWT de login ou uma chave de API. Isso autentica todas as solicitações subsequentes feitas por meio da IU do Swagger.
Os endpoints são organizados por categoria para facilitar a navegação. Expanda qualquer seção para ver as operações disponíveis:
Clique em "Experimente" em qualquer endpoint para torná-lo interativo. Preencha os parâmetros necessários e clique em "Executar". O corpo da resposta, os cabeçalhos e o código de status são exibidos abaixo.
Expanda a seção Schema abaixo de qualquer terminal para ver a estrutura de resposta completa. Esses tipos são compatíveis com as definições TypeScript no pacote @balla-stats/types, facilitando a construção de integrações com segurança de tipo.
Recursos do esquema
- Tipos de campo: String, número, booleano, array, objeto com definições de tipo exatas
- Campos obrigatórios: Marcados claramente para distinguir propriedades opcionais de obrigatórias
- Enums: Valores exatos permitidos para campos de status, funções e tipos
- Objetos aninhados: Expansível para mostrar a estrutura completa do relacionamento
A API Balla Stats segue padrões consistentes em todos os endpoints:
Paginação
Use os parâmetros de consulta page e limit. As respostas incluem contagem total e metadados da página atual.
Filtragem
Filtre os resultados com parâmetros de consulta como status, teamId, seasonId e intervalos de datas.
Respostas de erro
Formato consistente com os campos message e statusCode. Erros de validação incluem detalhes em nível de campo.
Formatos de data
Todas as datas usam o formato ISO 8601 (por exemplo, 2026-02-16T10:30:00.000Z). Os carimbos de data e hora estão sempre em UTC.
Teste antes de codificar
Use o Swagger para testar antes de escrever o código de integração. Verifique se os endpoints retornam os dados esperados.
Verifique todos os campos
Verifique os esquemas de resposta para todos os campos disponíveis. As respostas geralmente incluem mais dados do que você imagina.
Aplicam-se limites de taxa
Os limites de taxa também se aplicam a solicitações Swagger. Use chaves de API para limites mais altos ao testar extensivamente.
Erro 401 no Swagger
- Clique no botão Autorizar e insira seu token primeiro
- Certifique-se de incluir o token completo sem espaços extras
- Os tokens JWT expiram - faça login novamente se a sua sessão expirar
Respostas vazias
- Verifique se os parâmetros de consulta estão corretos (por exemplo, ID de grupo válido)
- Verifique se você tem acesso ao recurso solicitado
- Certifique-se de que o recurso existe - tente listar todos os itens primeiro