---
title: Visão geral da API pública
description: Endpoints da API REST para aplicativos móveis, integrações e plataformas
  whitelabel
order: 5
source_hash: bbd272c97e8f
slug: visao-geral-da-api-publica
---

# 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.

::: warning 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](../running-events/whitelabel-and-enterprise-setup.md) 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](../joining-events/enterprise-saml-and-whitelabel-login.md).

## Alternativa de exportação de dados

Para planilhas únicas sem codificação, use **exportações** do gerente — [Documentos do organizador](organizer-documents.md), [Exportação de dados de resultados](../results/exporting-results-data.md), [Exportação de renda anual](../finance-module/yearly-income-export.md).

## Relacionados

- [Configuração whitelabel e empresarial](../running-events/whitelabel-and-enterprise-setup.md)
- [Como exportar dados do DistantRace](how-to-export-data-from-distantrace.md)
- [Integrações](../integrations/introduction-to-integrations.md)