API e integración del tiro al plato

Si el club ya tiene su propio sistema — sitio de inscripciones, planilla de socios, panel de resultados — se pueden conectar: la API del tiro al plato crea la prueba, arma pasadas y squads, inscribe atletas y devuelve el marcador en tiempo real, sin que nadie vuelva a teclear nada.

Cómo empezar

1. En el panel de la entidad, el owner abre Claves de API y crea una clave — lectura, o lectura y escritura.
2. Guarde la secret: se muestra una sola vez. Si la pierde, basta con regenerar la clave (la secret anterior muere en el acto).
3. Envía en cada request el header Authorization: Bearer <access_key>.<secret>.
4. Llame a los endpoints de abajo con el prefijo /api/v1/clay.

Qué se puede hacer

• Pruebas — crear, editar, publicar y eliminar. La prueba nace en borrador ya con el estándar de la modalidad: la primera pasada (en Skeet, la secuencia oficial de 25), el Squad 1, el desempate del reglamento y el código público.
• Pasadas — armar la cuadrícula de la planilla (puestos × platos por puesto, o la cuadrícula exacta puesto a puesto). Sin cuadrícula en el cuerpo, entra el preset de la modalidad. El total de la prueba es la suma de las pasadas activas.
• Squads — grupos con horario y límite de cupos (por defecto según la modalidad: 5 en compak, 6 en trap, skeet y sporting).
• Registro — inscribir atletas y ubicarlos en los squads. El atleta entra en el mismo registro del club que usa IPSC.
• Resultados — clasificación con desempate, la tira plato a plato, amonestaciones y el estado de las dos firmas.
• Campeonatos — agrupar pruebas como fechas de la temporada y leer el ranking sumado, con el mínimo de fechas y los descartes ya aplicados.
• Shoot-off — leer el desempate de cancha: quién disputó, la tira de cada uno, el puesto y cómo terminó (en el tiro, por WO o por la edad). Abrir, marcar y concluir son de la cancha — ver el aviso abajo.
• Categorías y clases — armar el catálogo del campeonato (Sénior, Veterano, Damas, Júnior) con las clases de cada categoría y los rangos del reglamento. La prueba devuelve el catálogo vigente en él, con la herencia ya resuelta.
• Enlaces públicos — inscripción, resultados y hub, cada uno indicando si está en el aire y, si no lo está, por qué.

Ejemplo: una prueba completa en cuatro llamadas

BASE=https://SEU_HOST/api/v1/clay
AUTH="Authorization: Bearer $ACCESS.$SECRET"

# 1. prueba (nace en borrador, con la Pasada 1 lista)
prova=$(curl -s -X POST $BASE/provas -H "$AUTH" -H 'Content-Type: application/json' \
  -d '{"nome": "Etapa COMPAK", "modalidade": "compak", "data_prova": "2026-10-10"}' \
  | jq -r .prova.uuid)

# 2. una segunda pasada y un squad
curl -s -X POST $BASE/provas/$prova/passadas -H "$AUTH" -H 'Content-Type: application/json' \
  -d '{"qtd_postos": 5, "pratos_por_posto": 5}'
squad=$(curl -s -X POST $BASE/provas/$prova/squads -H "$AUTH" -H 'Content-Type: application/json' \
  -d '{"limite": 5, "horario_inicio": "09:30"}' | jq -r .squad.uuid)

# 3. inscripción ya en el squad
curl -s -X POST $BASE/provas/$prova/inscricoes -H "$AUTH" -H 'Content-Type: application/json' \
  -d "{\"nome\": \"Maria Souza\", \"email\": \"[email protected]\", \"squad_uuid\": \"$squad\"}"

# 4. marcador (solo lo firmado; use ?incluir_nao_aprovados=1 para el parcial)
curl -s $BASE/provas/$prova/resultados -H "$AUTH"

Campeonato: catálogo y ranking de la temporada

El campeonato es el dueño del catálogo: las fechas heredan de él y el atleta se encuadra una vez por temporada. Todo es opcional: sin categorías y clases activadas, la inscripción sigue con los dos campos de texto libre.

# 1. campeonato con las reglas activadas (ya trae el catálogo estándar)
camp=$(curl -s -X POST $BASE/campeonatos -H "$AUTH" -H 'Content-Type: application/json' \
  -d '{"nome": "Campeonato 2026", "ano": 2026, "usa_categorias": true,
       "usa_classes": true, "minimo_etapas": 3, "descartes": 1}' | jq -r .campeonato.uuid)

# 2. la prueba pasa a ser fecha y hereda el catálogo
curl -s -X PUT $BASE/provas/$prova/campeonato -H "$AUTH" -H 'Content-Type: application/json' \
  -d "{\"campeonato_uuid\": \"$camp\"}"

# 3. el catálogo vigente en Esta prueba (alcance: campeonato, prueba o club)
curl -s $BASE/provas/$prova/catalogo -H "$AUTH"

# 4. ranking de la temporada, con descartes y mínimo ya aplicados
curl -s $BASE/campeonatos/$camp/ranking -H "$AUTH"

Referencia interactiva

Explora y prueba los endpoints abajo (Swagger UI). El JSON de la especificación OpenAPI está en openapi.json.