# Grupify para desarrolladores

Integra inscripciones, resultados, pagos y estadísticas de tus eventos con la API pública de Grupify. REST, JSON, API keys con scopes y una especificación OpenAPI que puedes cargar en cualquier cliente o agente.

## Qué puedes hacer

- Leer los eventos de tu organización y su configuración (distancias, categorías, precios).
- Listar inscritos con pago confirmado y buscarlos por dorsal, chip o documento.
- Consultar cifras agregadas: inscritos, recaudo y desglose por distancia.
- Listar los pagos de tu organización, una fila por transacción.
- Cargar resultados por dorsal, en JSON o en CSV, desde tu sistema de cronometraje.

## Autenticación

Cada petición lleva una API key de tu organización. La creas desde el panel de la organización en la plataforma (Configuración → API keys) con los scopes que necesite cada integración. Se envía como `Authorization: Bearer cok_live_…` o como `X-API-Key: cok_live_…`. Sin clave responde 401; con clave pero sin el scope, 403 INSUFFICIENT_SCOPE.

Las claves de producción empiezan por `cok_live_`. Trátalas como contraseñas: no las pongas en el front ni en repositorios.

## Arranque en tres llamadas

1. Crea una API key en el panel de tu organización con los scopes `events:read` y `stats:read`.
2. Guárdala en una variable de entorno, por ejemplo `COK`.
3. Lanza las llamadas de abajo. Las listas vienen paginadas con `page` y `page_size`; los errores llegan con un `code` estable.

```bash
# 1. Listar los eventos de tu organización
curl -s "https://api.grupify.app/public/v1/events?page=1&page_size=20" \
  -H "Authorization: Bearer $COK"

# 2. Estadísticas de un evento
curl -s "https://api.grupify.app/public/v1/events/EVENT_ID/stats" \
  -H "X-API-Key: $COK"

# 3. Buscar una inscripción por dorsal
curl -s "https://api.grupify.app/public/v1/events/EVENT_ID/participants/lookup?bib=1024" \
  -H "Authorization: Bearer $COK"
```

## Scopes

| Scope | Qué permite |
| --- | --- |
| `events:read` | Eventos de la organizacion y su configuracion. |
| `participants:read` | Inscritos con pago confirmado: dorsal, categoria, documento. Es PII. |
| `stats:read` | Cifras agregadas por evento: inscritos, recaudo, por distancia. |
| `payments:read` | Pagos de la organizacion, una fila por transaccion. |
| `results:write` | Cargar tiempos por dorsal (JSON o CSV). El unico de escritura. |

## Entorno de pruebas

Hoy no hay un entorno de pruebas público separado. Recomendamos crear una organización de pruebas en la plataforma y una API key con los scopes de solo lectura: ninguno de ellos modifica datos. El único scope de escritura, `results:write`, hace upsert por dorsal, así que un envío repetido no duplica filas.

## Recursos

- [Documentación de la API](https://www.grupify.com/docs/api): Autenticación, scopes, límites, envelope de errores y cada endpoint con ejemplos.
- [Especificación OpenAPI 3.1](https://www.grupify.com/openapi.json): Para generar clientes, importar en Postman o dársela a un agente como definición de herramientas.
- [llms.txt](https://www.grupify.com/llms.txt): Qué es Grupify, cuándo usarlo y cómo llamarlo, en el formato que leen los modelos.
- [Markdown por ruta](https://www.grupify.com/md/es/developers.md): Cada página pública también existe en text/markdown: pídela con `Accept: text/markdown` o en /md/{es,en}/…

Base de la API: `https://api.grupify.app`

---

Versión HTML: https://www.grupify.com/developers · Guía para agentes: https://www.grupify.com/llms.txt · API: https://www.grupify.com/openapi.json · GRUPIFY S.A.S. (NIT 901929426), Bucaramanga, Colombia.