Visão geral da API pública
Visão geral da API pública
DistantRace disponibiliza uma API REST (/api/v1/) utilizada pelo aplicativo móvel, integrações de parceiros e plataformas whitelabel. Este é um mapa de alto nível — não uma referência completa do OpenAPI.
Suporte para integração
O acesso à API para desenvolvimento de terceiros é geralmente organizado com o suporte da DistantRace. Aplicam-se autenticação e limites de taxa.
URL Base #
https://distantrace.com/api/v1/
Autenticação #
| Concessão / token | Chamador típico | Escopo |
|---|---|---|
| Session / mobile token | Aplicativo DistantRace, web logado | Leitura/escrita com escopo de usuário |
Org token (client_credentials) |
Backend do portal whitelabel | Listagens públicas, validação/resgate de código de adesão, imagens hero |
| User OAuth (código de autorização + atualização) | SPA whitelabel após login | Adesão, treinos, perfil, checkout |
Integrações whitelabel usam dois tipos de credenciais:
| Credencial | Uso |
|---|---|
| Org token (bearer de longa duração) | Listagens públicas de eventos/desafios, imagens hero, validação de código de adesão, resgate de token de e-mail |
| User OAuth client (código de autorização) | Login de participante, adesão a eventos, treinos, perfil, checkout |
O token da organização é resolvido a partir do proprietário da aplicação OAuth — cada chamada de API whitelabel é implicitamente vinculada a um clube.
Os endpoints de conta incluem login QR, login social, perfil (/api/v1/account/me/) e registro de dispositivo.
Veja Configuração whitelabel e empresarial para o modelo completo de portal de participantes.
Fluxos de código de adesão whitelabel #
| Endpoint | Método | Propósito |
|---|---|---|
event/joincode/{code}/validate/ |
GET | Verifica se um código está ativo para sua organização; retorna carga útil de evento público (sem PII de participante) |
event/joincode/redeem-email-token/ |
POST | Consome um token de link mágico de um e-mail de convite; retorna tokens OAuth e pode inscrever automaticamente em um desafio |
event/joincode/ |
POST | Cria um código de adesão e envia e-mail de convite (somente token de usuário administrador — não o token público da organização) |
O resgate de link mágico usa o token da organização mais um token de uso único no corpo do POST. O servidor pode criar um usuário a partir dos dados de pré-preenchimento do código de adesão, emitir tokens de acesso/atualização e chamar inscrição automática quando o código está vinculado a um desafio.
Imagens hero (somente whitelabel) #
GET orgs/hero-images/?language=<code> — imagens de carrossel ativas para a organização do token. Requer is_whitelabel no clube. O filtro de idioma opcional retorna imagens específicas para o local mais imagens de reserva neutras em relação ao idioma.
Principais grupos de recursos #
| Prefixo | Recursos |
|---|---|
event/ |
Eventos, códigos de adesão, postagens |
gamification/ |
Desafios, desafiantes, desafios de equipe, metas, estatísticas diárias |
races/ |
Competições, participantes (corredores), resultados |
shop/ |
Carrinhos, itens do carrinho, produtos, níveis premium |
users/ |
Usuários, participantes, dispositivos push |
workouts/ |
Atividades, upload, metadados de esporte/tipo |
orgs/ |
Organizações, imagens hero (whitelabel) |
finances/ |
Canais de pagamento, auxiliares de precificação |
Tarefas comuns de integração #
| Tarefa | Endpoints típicos |
|---|---|
| Listar eventos publicados | event/event/ |
| Registrar participante | races/registration/entrant/ |
| Sincronizar atividades | workouts/ ou workouts/upload/ |
| Ler resultados | races/result/ |
| Passos diários móveis | gamification/dailystat/ |
SSO Empresarial #
Endpoints SAML (host de autenticação da plataforma):
| Caminho | Propósito |
|---|---|
/saml2/discovery/ |
Insira o e-mail de trabalho → roteia para o IdP correto por domínio |
/saml2/login/ |
Inicia autenticação SAML (parâmetros de consulta opcionais idp e next) |
/saml2/acs/ |
Consumidor de asserção (callback do IdP) |
/saml2/metadata/ |
Metadados do provedor de serviço para configuração do IdP |
Quando existem vários provedores de identidade, a descoberta corresponde ao domínio do e-mail a um IdP antes de redirecionar para o login. Com um único IdP, a descoberta vai direto para /saml2/login/.
Fluxos de participantes e equipe: Login SAML empresarial e whitelabel.
Alternativa de exportação de dados #
Para planilhas únicas sem codificação, use exportações do gerente — Documentos do organizador, Exportação de dados de resultados, Exportação de renda anual.