Descripción general de la API pública
Descripción general de la API pública
DistantRace ofrece una API REST (/api/v1/) que utilizan la aplicación móvil, las integraciones con socios y las plataformas de marca blanca. Este artículo es un mapa general, no una referencia OpenAPI completa.
Soporte para integraciones
El acceso a la API para desarrollos de terceros suele acordarse con el equipo de soporte de DistantRace. Se aplican autenticación y límites de solicitudes.
URL base #
https://distantrace.com/api/v1/
Autenticación #
| Concesión o token | Cliente habitual | Alcance |
|---|---|---|
| Sesión o token móvil | Aplicación DistantRace, web con sesión iniciada | Lectura y escritura para el usuario |
Token de organización (client_credentials) |
Backend de un portal de marca blanca | Listados públicos, validación y canje de códigos de acceso, imágenes principales |
| OAuth de usuario (código de autorización + actualización) | SPA de marca blanca después de iniciar sesión | Unirse, entrenamientos, perfil y pago |
Las integraciones de marca blanca utilizan dos tipos de credenciales:
| Credencial | Uso |
|---|---|
| Token de organización (bearer de larga duración) | Listados públicos de eventos y desafíos, imágenes principales, validación de códigos de acceso y canje de tokens de correo electrónico |
| Cliente OAuth de usuario (código de autorización) | Inicio de sesión del participante, unirse a eventos, entrenamientos, perfil y pago |
El token de organización se determina a partir del propietario de la aplicación OAuth; cada llamada de una API de marca blanca está limitada implícitamente a un club.
Los endpoints de cuentas incluyen inicio de sesión mediante QR, inicio de sesión social, perfil (/api/v1/account/me/) y registro de dispositivos.
Consulta Configuración de marca blanca y empresarial para conocer el modelo completo del portal de participantes.
Flujos de códigos de acceso de marca blanca #
| Endpoint | Método | Finalidad |
|---|---|---|
event/joincode/{code}/validate/ |
GET | Comprueba si un código está activo para tu organización; devuelve los datos públicos del evento, sin datos personales del participante |
event/joincode/redeem-email-token/ |
POST | Consume el token de un enlace mágico de un correo de invitación; devuelve tokens OAuth y puede inscribir automáticamente en un desafío |
event/joincode/ |
POST | Crea un código de acceso y envía un correo de invitación; solo con token de usuario administrador, no con el token público de organización |
El canje de un enlace mágico utiliza el token de organización y un token de un solo uso en el cuerpo POST. El servidor puede crear un usuario a partir de los datos precompletados del código de acceso, emitir tokens de acceso y actualización e inscribirlo automáticamente cuando el código está vinculado a un desafío.
Imágenes principales (solo marca blanca) #
GET orgs/hero-images/?language=<code> — imágenes activas del carrusel para la organización del token. Requiere que el club tenga activado is_whitelabel. El filtro de idioma opcional devuelve imágenes específicas del idioma junto con alternativas independientes del idioma.
Principales grupos de recursos #
| Prefijo | Recursos |
|---|---|
event/ |
Eventos, códigos de acceso, publicaciones |
gamification/ |
Desafíos, clasificaciones, configuración de resultados, mapas de calor, analíticas de actividades, objetivos y estadísticas diarias |
races/ |
Competiciones, inscritos (deportistas) y resultados |
shop/ |
Carritos, elementos del carrito, productos y niveles prémium |
users/ |
Usuarios, participantes y dispositivos para notificaciones push |
workouts/ |
Actividades, subida y metadatos de deporte o tipo |
orgs/ |
Organizaciones e imágenes principales (marca blanca) |
finances/ |
Canales de pago y utilidades para precios |
Tareas habituales de integración #
| Tarea | Endpoints habituales |
|---|---|
| Mostrar eventos publicados | event/event/ |
| Inscribir a un participante | races/registration/entrant/ |
| Sincronizar actividades | workouts/ o workouts/upload/ |
| Leer resultados | races/result/ |
| Crear pantallas de resultados de desafíos | API de resultados de desafíos |
| Pasos diarios desde el móvil | gamification/dailystat/ |
SSO empresarial #
Endpoints SAML en el host de autenticación de la plataforma:
| Ruta | Finalidad |
|---|---|
/saml2/discovery/ |
Introducir el correo de trabajo y dirigir al IdP correcto según el dominio |
/saml2/login/ |
Iniciar la autenticación SAML, con parámetros de consulta opcionales idp y next |
/saml2/acs/ |
Consumidor de aserciones (callback del IdP) |
/saml2/metadata/ |
Metadatos del proveedor de servicios para configurar el IdP |
Cuando hay varios proveedores de identidad, el descubrimiento hace coincidir el dominio del correo electrónico con un IdP antes de redirigir al inicio de sesión. Si solo hay un IdP, el descubrimiento pasa directamente a /saml2/login/.
Flujos para participantes y personal: Inicio de sesión SAML empresarial y de marca blanca.
Alternativa para exportar datos #
Para crear hojas de cálculo puntuales sin programar, utiliza las exportaciones de la consola de gestión: Documentos del organizador, Exportar datos de resultados y Exportar ingresos anuales.