# API e integração do tiro ao prato

> Orbit help — markdown twin of `/clay/docs/api` for LLM agents (llmstxt.org). Human UI: /clay/docs/api

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.

  **Isto aqui é para quem programa.** Se você organiza a prova e
  não vai escrever código, mande esta página para quem cuida do sistema do clube —
  o resto do guia é o que interessa para o dia da prova.

## 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`.

  **
  É a mesma chave da API do IPSC. Um clube que já integra as provas de precisão não precisa de credencial nova para o tiro ao prato.

  **
  **O resultado não entra por aqui.** A fita de pratos nasce
  assinada no campo: o juiz marca prato a prato e assina, o atleta confere e confirma
  com o PIN. Um resultado enviado por API não teria essas assinaturas — e é justamente
  isso que garante que o placar publicado é o que foi anotado na folha. A API
  **lê** os scores; quem os produz é o juiz.

  **
  **O desempate também não.** O shoot-off acontece com o
  campo parado, o juiz marca na pedana e a secretaria fecha — e a fita dele é
  assinada como qualquer outra. Por isso a API mostra o desempate, mas não abre,
  não marca e não conclui: é operação da prova, não integração.

## 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ê.

  **O módulo precisa estar habilitado** para a sua entidade.
  Sem isso, toda rota responde 404 — a chave é válida, o que não existe é o módulo
  para esse clube. Quem liga é o próprio clube, em **Dados do clube →
  Usar o tiro ao prato neste clube**. Se a opção não aparecer lá, a
  modalidade não está disponível nesta instalação: aí sim é caso de suporte.

## 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\": \"maria@exemplo.com\", \"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"
```

  **A faixa da classe é semiaberta:** `valor_min`
  entra e `valor_max` fica de fora. É o que faz "AA de 87 a 94" e
  "Premium 94 acima" não se sobreporem. O campo `faixa` vem pronto
  para exibir — "26–35" em pratos, "≥87 e <94" em percentual.

## Referência interativa

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

    Este guia cobre as provas de tiro ao prato (COMPAK, Skeet, Trap e Percurso de Caça).

---

HTML: /clay/docs/api
Index: /llms.txt · Docs index: /docs/llms.txt