Parkour Design ofrece actualmente un servicio de recursos coordinado y de solo lectura para resúmenes de eventos y de planos de recorrido. La geometría completa de los proyectos, los archivos, la escritura y la sincronización requieren un contrato de socio aparte.
Estado del contrato: los endpoints de abajo describen el comportamiento desplegado actualmente para los clientes aprobados. Todavía no son una API general versionada. No desarrolles contra ellos antes de que Parkour Design confirme el acceso, los scopes, los límites y el contrato de lanzamiento.
URL base y autenticación
Usa el emisor elegido para el entorno OAuth como URL base de la API:
| Entorno | URL base |
|---|---|
| Producción | https://app.parkour.design |
| Pruebas | https://parkour-test.web.app |
Envía el token de acceso de Parkour Design desde un servicio de servidor:
Authorization: Bearer <access_token>
Accept: application/json
El token de acceso debe ser válido para el emisor configurado y la audiencia parkour-api, tener token_use igual a access_token y contener actualmente openid.
La API no permite actualmente el acceso desde el navegador desde otro origen. No expongas el token de acceso ni el de actualización al JavaScript del frontend.
Listar eventos
GET /api/events
Ejemplo de solicitud:
curl "${ISSUER}/api/events" \
--header "Authorization: Bearer ${ACCESS_TOKEN}" \
--header "Accept: application/json"
Ejemplo de respuesta:
{
"items": [
{
"id": "abcdefghijklmnopqrstuv",
"name": "Example Event",
"startDate": "2026-07-24T00:00:00Z",
"endDate": "2026-07-26T00:00:00Z",
"updatedAt": "2026-07-26T18:42:10Z",
"designCount": 4
}
]
}
Tipo de respuesta actual:
type EventSummary = {
id: string;
name: string;
startDate: string | null;
endDate: string | null;
updatedAt: string | null;
designCount: number;
};
type EventsResponse = {
items: EventSummary[];
};
Los eventos se forman a partir de los proyectos no eliminados del usuario autenticado. Los proyectos sin identificador de evento se omiten.
Trata id como un valor opaco. Cópialo sin cambios en la solicitud de resúmenes de proyectos. No deduzcas su formato ni lo generes en el sistema del socio.
Listar los resúmenes de proyectos de un evento
GET /api/events/{eventId}/designs
Ejemplo de solicitud:
curl "${ISSUER}/api/events/${EVENT_ID}/designs" \
--header "Authorization: Bearer ${ACCESS_TOKEN}" \
--header "Accept: application/json"
Ejemplo de respuesta:
{
"event": {
"id": "abcdefghijklmnopqrstuv",
"name": "Example Event",
"startDate": "2026-07-24T00:00:00Z",
"endDate": "2026-07-26T00:00:00Z",
"updatedAt": "2026-07-26T18:42:10Z",
"designCount": 4
},
"items": [
{
"id": "design-record-id",
"localId": "design-local-id",
"eventId": "abcdefghijklmnopqrstuv",
"title": "Grand Prix",
"eventName": "Example Event",
"eventDate": "2026-07-26T00:00:00Z",
"updatedAt": "2026-07-26T18:42:10Z",
"authorName": "Course Designer",
"shortDescr": "Competition description"
}
]
}
Tipo de respuesta actual:
type DesignSummary = {
id: string;
localId: string | null;
eventId: string;
title: string;
eventName: string;
eventDate: string | null;
updatedAt: string | null;
authorName: string | null;
shortDescr: string;
};
type EventDesignsResponse = {
event: EventSummary;
items: DesignSummary[];
};
Las fechas, cuando existen, son cadenas ISO 8601 en UTC. Los clientes deben admitir null en las fechas opcionales y en localId.
Propiedad y visibilidad
El sub del token portador identifica al propietario de los recursos de Parkour Design. Las respuestas solo contienen proyectos no eliminados de ese usuario.
El servicio actual no ofrece:
- acceso para toda una organización o un equipo;
- acceso a proyectos compartidos o públicos de otro usuario;
- filtrado de recursos específico de un cliente;
- proyectos eliminados;
- datos de suscripción, de perfil ni de pago.
Un evento inexistente y un evento de otro usuario devuelven ambos 404. No uses esta respuesta para deducir si existe un recurso de otro usuario.
Límites actuales y orden
Los endpoints actuales no aceptan parámetros de filtrado, ordenación, paginación, cursores ni sincronización incremental.
/api/eventsdevuelve la lista de eventos en una sola respuesta./api/events/{eventId}/designsdevuelve como máximo 500 resúmenes.- La respuesta no indica actualmente si se ha truncado ni ofrece un cursor para continuar.
- El orden corresponde al comportamiento actual de la implementación y todavía no es una garantía versionada.
Antes de aprobar una integración en producción, Parkour Design y el socio deben confirmar que el volumen de datos esperado cabe en estos límites. Un socio que necesite paginación completa o actualizaciones incrementales no debe compensarlo extrayendo datos de forma masiva ni adivinando identificadores: eso requiere un contrato revisado.
Respuestas de error
Los errores usan un cuerpo JSON compacto:
{"error": "not_found"}
| Estado | Error | Significado |
|---|---|---|
401 | invalid_token | Token portador ausente, mal formado, caducado, no válido o con scopes actualmente insuficientes |
404 | not_found | Ruta no válida o evento no disponible para este usuario |
405 | method_not_allowed | Método distinto de GET |
Los fallos inesperados del servicio todavía no tienen un esquema de error versionado propio. Los clientes deben considerar reintentables las demás respuestas 5xx solo en operaciones GET idempotentes, con espera exponencial limitada y una variación aleatoria.
Datos que esta API no expone
El resumen de un proyecto no es un plano de recorrido completo. La API de recursos actual no expone:
- la geometría ni el trazado del recorrido;
- los obstáculos, los grupos, la disposición de la pista ni los objetos de dibujo;
- los PDF generados, las vistas previas, las imágenes ni las URL de descarga;
- operaciones de creación, modificación, eliminación ni subida;
- la búsqueda de un proyecto concreto por su identificador;
- webhooks ni un flujo de cambios;
- tokens de acceso, sesiones, pruebas, actividades ni destinos guardados de Eqify.
No presentes una respuesta de resumen como un plano de recorrido imprimible o editable.