API e integração do tiro ao prato

Se o clube já tem um sistema próprio — site de inscrições, planilha de sócios, painel de resultados — dá para ligar os dois: a API do tiro ao prato cria a prova, monta passadas e squads, inscreve atletas e devolve o placar em tempo real, sem ninguém redigitar nada.

Como começar

1. No painel da entidade, o owner abre Chaves de API e cria uma chave — leitura, ou leitura e escrita.
2. Guarde a secret: ela aparece uma única vez. Se perder, é só regerar (a chave antiga morre na hora).
3. Envie em cada request o header Authorization: Bearer <access_key>.<secret>.
4. Chame os endpoints abaixo com o prefixo /api/v1/clay.

O que dá para fazer

• Provas — criar, editar, publicar e excluir. A prova nasce em rascunho já no padrão da modalidade: a primeira passada (no Skeet, a sequência oficial de 25), o Squad 1, o desempate da regra e o código público.
• Passadas — montar a grade da folha (postos × pratos por posto, ou a grade exata posto a posto). Sem grade no corpo, entra o preset da modalidade. O total da prova é a soma das passadas ativas.
• Squads — grupos com horário e limite de vagas (padrão no tamanho da modalidade: 5 no compak, 6 no trap, no skeet e no percurso de caça).
• Inscrições — inscrever atletas e alocá-los nos squads. O atleta entra no mesmo cadastro do clube que o IPSC usa.
• Resultados — classificação com desempate, fita prato a prato, advertências e o estado das assinaturas.
• Campeonatos — agrupar provas como etapas da temporada e ler o ranking somado, com o mínimo de etapas e os descartes já aplicados.
• Shoot-off — ler o desempate de campo: quem disputou, a fita de cada um, a colocação e como terminou (no tiro, por WO ou pela idade). Abrir, marcar e concluir são do campo — ver o aviso abaixo.
• Categorias e classes — montar o catálogo do campeonato (Sênior, Veterano, Damas, Júnior) com as classes de cada categoria e as faixas do regulamento. A prova devolve o catálogo que vale nela, com a herança já resolvida.
• Links públicos — inscrição, resultados e hub, cada um dizendo se está no ar e, se não estiver, por quê.

Exemplo: prova completa em quatro chamadas

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

# 1. prova (nasce em rascunho, com a Passada 1 pronta)
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. segunda passada e um 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. inscrição já no 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. placar (só o que está assinado; use ?incluir_nao_aprovados=1 para o parcial)
curl -s $BASE/provas/$prova/resultados -H "$AUTH"

Campeonato: catálogo e ranking da temporada

O campeonato é o dono do catálogo: as etapas herdam dele e o atleta é enquadrado uma vez por temporada. Tudo é opcional — sem categorias e classes ligadas, a inscrição segue com os dois campos de texto livre.

# 1. campeonato com as regras ligadas (já vem com o catálogo padrão)
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. a prova vira etapa e passa a herdar o catálogo
curl -s -X PUT $BASE/provas/$prova/campeonato -H "$AUTH" -H 'Content-Type: application/json' \
  -d "{\"campeonato_uuid\": \"$camp\"}"

# 3. o catálogo que vale NESTA prova (escopo: campeonato, prova ou clube)
curl -s $BASE/provas/$prova/catalogo -H "$AUTH"

# 4. ranking da temporada, com descartes e mínimo já aplicados
curl -s $BASE/campeonatos/$camp/ranking -H "$AUTH"

Referência interativa

Explore e teste os endpoints abaixo (Swagger UI). O JSON da especificação OpenAPI está em openapi.json.