> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rocky.global/llms.txt
> Use this file to discover all available pages before exploring further.

# Timing integration

# Integración de cronometraje (API)

Esta guía documenta cómo conectar Rocky Global con plataformas de cronometraje de terceros (Chronotrack, MyLaps y futuras integraciones) mediante la API de participantes.

## Principio de diseño

Rocky Global utiliza el **número de dorsal (BIB)** como identificador principal del participante durante el check-in y las exportaciones operativas. El cruce con números de chip de cronometradores externos se resuelve **fuera del flujo de check-in**, típicamente añadiendo una columna adicional en Excel al exportar participantes.

Esto evita duplicar registros y mantiene una sola fuente de verdad para inscripciones y entrega de kit.

## Autenticación

La API usa **Bearer Token** (Laravel Sanctum) con scope `organizer-api` o `supervisor-api`.

```bash theme={null}
curl -H "Accept: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  "https://TU_DOMINIO/api/v1/organizer/participants?event_id=456&per_page=2000"
```

Ver [Activar acceso API](/roles/organizador/api-organizador/activar-acceso) y [API de organizador](/apis/organizer-api).

## Endpoints relevantes para cronometraje

### GET /api/v1/organizer/participants

Obtiene participantes del organizador autenticado. Filtros útiles para cronometraje:

| Parámetro           | Uso                                               |
| ------------------- | ------------------------------------------------- |
| `event_id`          | Limitar a un evento                               |
| `bib`               | Buscar por dorsal                                 |
| `status`            | Filtrar por estado de inscripción                 |
| `per_page`          | Tamaño de página (hasta el máximo configurado)    |
| `pagination=cursor` | Paginación por cursor para eventos grandes (20k+) |

Campos devueltos relevantes (vía `ParticipantResource`):

* `id` — ID interno del participante
* `bib` — Número de dorsal
* `locator` — Localizador de inscripción (no cambia en transferencias)
* `details` — Datos del formulario (nombre, documento, género, categoría, etc.)
* `competition_results` — Resultados de competición (JSON, si ya fueron cargados)
* `observations` / `participation_notes` — Notas operativas

### POST /api/v1/organizer/participants

Actualiza participantes en lote. Campos permitidos para cronometradores:

* `bib` — Ajustar dorsal si el proveedor externo reasignó números
* `competition_results` — Cargar tiempos, posiciones, splits (JSON)
* `observations` / `participation_notes` — Notas
* `details` — Campos adicionales (por ejemplo, columna `chip_id`)

Campos **prohibidos** (se rechazan): `evento_id`, `locator`, `order_id`, `user_id`, `status`.

```bash theme={null}
curl -X POST \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <TOKEN>" \
  -d '{
    "updates": [
      {
        "id": 123,
        "competition_results": {
          "chip_time": "00:45:12",
          "gun_time": "00:45:18",
          "overall_position": 42
        },
        "details": {
          "chip_id": "CT-987654"
        }
      }
    ]
  }' \
  "https://TU_DOMINIO/api/v1/organizer/participants"
```

Para lotes mayores a 1000 registros, la API responde `202 Accepted` y procesa en background.

## Flujo recomendado con Chronotrack

```mermaid theme={null}
sequenceDiagram
    participant RG as Rocky Global
    participant API as API participantes
    participant CT as Chronotrack

    RG->>API: GET participants (event_id, bib, details)
    API-->>CT: Export / sync (dorsal, nombre, categoría)
    Note over CT: Carrera + lecturas de chip
    CT->>API: POST competition_results + chip_id
    API-->>RG: Resultados disponibles en plataforma
```

1. **Antes del evento:** exporta participantes con dorsal asignado vía API o Excel.
2. **En Chronotrack:** importa la lista usando el dorsal como clave principal.
3. **Después de la carrera:** envía tiempos y posiciones de vuelta con `POST /participants`, mapeando `chip_id` en `details` si es necesario.

## Flujo con exportación Excel (sin API)

Si prefieres no integrar por API:

1. Exporta participantes desde **Inscripciones** o **Reportes**.
2. Añade una columna `chip_id` (o similar) para el cronometrador.
3. Tras la carrera, importa resultados manualmente o vía API POST.

## Consideraciones de seguridad

* Los tokens API están restringidos al `organizador_id` del propietario.
* Opcional: lista blanca de IPs en `organizer_api_settings`.
* Rate limit configurable (por defecto 60 req/min).
* Cada consulta queda registrada en los logs de API.

## Soporte para nuevas integraciones

Para integraciones con **MyLaps** u otras plataformas, el mismo contrato de API aplica: dorsal como clave, `competition_results` para tiempos, `details` para metadatos del chip.

Contacta a [soporte@rocky.global](mailto:soporte@rocky.global) si necesitas asistencia con un conector específico o volúmenes superiores a 20.000 participantes.

## Referencias

* [API de organizador](/apis/organizer-api)
* [Asignación de dorsales](/roles/organizador/gestion-participantes/asignacion-dorsales)
* [Check-in del evento](/roles/organizador/gestion-participantes/checkin-evento)