{
 "openapi": "3.0.3",
 "info": {
  "title": "Orbit — API pública",
  "version": "1.0.0",
  "description": "API REST para integradores gerenciarem tudo da entidade: configuração e requisitos de inscrição, atletas da entidade, provas, divisões/modalidades, main matches, áreas, stages, squads, vínculos de RO, inscrições, URLs públicas e resultados completos.\n\nTudo é escopado à entidade da chave e endereçado por **uuid** — nenhuma rota aceita ou devolve id interno do banco (CPF/RG/federação são campos opcionais, nunca o vínculo). Atleta da entidade nunca é apagado: o DELETE apenas desativa.\n\n## Autenticação\nCrie chaves em **Entidade → Chaves de API** (somente owner). Cada request envia:\n\n```\nAuthorization: Bearer <access_key>.<secret>\n```\n\nA secret é exibida **uma única vez** na criação/regeneração. Escopo `leitura` permite apenas GET; `leitura_escrita` libera escrita.\n\n## Rate limit\nLimite por chave (padrão 120 req/min) com headers `X-RateLimit-Limit`, `X-RateLimit-Remaining` e `X-RateLimit-Reset`; excedido retorna **429** com `Retry-After`.\n\n## Erros\nSempre JSON: `{\"error\": {\"code\": \"...\", \"message\": \"...\"}}` com HTTP 400/401/403/404/409/422/429. O código `confirmation_required` (409) indica ação destrutiva que precisa de confirmação explícita."
 },
 "servers": [
  {
   "url": "/api/v1"
  }
 ],
 "security": [
  {
   "bearerAuth": []
  }
 ],
 "tags": [
  {
   "name": "Entidade",
   "description": "Configuração da entidade e **requisitos de inscrição** — a fonte de verdade de quais campos são obrigatórios/únicos (e-mail, CPF, RG, CR/validade e campos adicionais). O owner define isso na tela da entidade; consulte aqui antes de criar atletas/inscrições."
  },
  {
   "name": "Atletas da entidade",
   "description": "Cadastro estável de atletas da entidade (membros), base das inscrições. Vínculo sempre por uuid; CPF/RG/federação são campos opcionais. **Quais campos são obrigatórios ou únicos é definido pela própria entidade** (e-mail, CPF, RG, CR/validade e campos adicionais) — consulte GET /entidade antes de cadastrar; o owner configura isso na tela da entidade (Atletas → Configurar campos)."
  },
  {
   "name": "Provas",
   "description": "CRUD de provas com os padrões do assistente (Main Match padrão, código público, RO implícito dos gestores)."
  },
  {
   "name": "Divisões e modalidades",
   "description": "Prova vinculada a campeonato não altera divisões livremente (409)."
  },
  {
   "name": "Main Matches"
  },
  {
   "name": "Áreas"
  },
  {
   "name": "Stages"
  },
  {
   "name": "Squads"
  },
  {
   "name": "ROs",
   "description": "Vínculos de Range Officer com a prova e seus stages."
  },
  {
   "name": "Inscrições",
   "description": "Regras de negócio da interface, inclusive com scores já lançados."
  },
  {
   "name": "Resultados",
   "description": "JSON completo da prova (formato m.scoring.services)."
  }
 ],
 "components": {
  "securitySchemes": {
   "bearerAuth": {
    "type": "http",
    "scheme": "bearer",
    "bearerFormat": "access_key.secret"
   }
  },
  "schemas": {
   "Erro": {
    "type": "object",
    "properties": {
     "error": {
      "type": "object",
      "properties": {
       "code": {
        "type": "string"
       },
       "message": {
        "type": "string"
       }
      }
     }
    }
   },
   "Prova": {
    "type": "object",
    "properties": {
     "uuid": {
      "type": "string",
      "format": "uuid"
     },
     "nome": {
      "type": "string"
     },
     "status": {
      "type": "string",
      "enum": [
       "rascunho",
       "aberta",
       "andamento",
       "encerrada"
      ]
     },
     "data_inicio": {
      "type": "string",
      "format": "date"
     },
     "data_fim": {
      "type": "string",
      "format": "date"
     },
     "local": {
      "type": "string",
      "nullable": true
     },
     "descricao": {
      "type": "string",
      "nullable": true
     },
     "codigo_publico": {
      "type": "string"
     },
     "campeonato_uuid": {
      "type": "string",
      "nullable": true
     },
     "resultados_publicos": {
      "type": "boolean"
     },
     "hub_publico": {
      "type": "boolean"
     },
     "inscricao_publica": {
      "type": "boolean"
     },
     "inscricao_limite_em": {
      "type": "string",
      "format": "date-time",
      "nullable": true
     },
     "inscricao_multi_divisao": {
      "type": "boolean"
     },
     "pin_pelo_portal": {
      "type": "boolean",
      "description": "Permite ao atleta criar ou trocar o PIN pelo portal. Desligada por padrão; o PIN do campo não depende dela."
     },
     "inscricao_squad_modo": {
      "type": "string",
      "enum": [
       "mesmo_squad",
       "por_match"
      ]
     },
     "check_equipamento_modo": {
      "type": "string",
      "description": "Modo do check de equipamento da prova (ex.: sem_check)"
     },
     "criada_em": {
      "type": "string",
      "format": "date-time",
      "nullable": true
     },
     "atualizada_em": {
      "type": "string",
      "format": "date-time",
      "nullable": true
     },
     "external_id": {
      "type": "string",
      "maxLength": 64,
      "nullable": true,
      "description": "Id desta prova no **sistema do integrador** (opcional, exclusivo da API — nenhuma tela do Orbit mostra ou edita). Único por entidade, então funciona como chave de idempotência: reenviar o mesmo POST devolve 409 em vez de duplicar. Envie `null` para desvincular. Use `?external_id=` na listagem para reencontrar o registro sem guardar o nosso uuid."
     }
    }
   },
   "Divisao": {
    "type": "object",
    "properties": {
     "uuid": {
      "type": "string"
     },
     "nome": {
      "type": "string"
     },
     "modalidade": {
      "type": "string"
     },
     "modalidade_uuid": {
      "type": "string",
      "nullable": true
     },
     "descricao": {
      "type": "string",
      "nullable": true
     },
     "fator": {
      "type": "string",
      "enum": [
       "menor",
       "maior"
      ]
     },
     "has_factor": {
      "type": "boolean"
     }
    }
   },
   "Modalidade": {
    "type": "object",
    "properties": {
     "uuid": {
      "type": "string"
     },
     "nome": {
      "type": "string"
     },
     "codigo": {
      "type": "string"
     },
     "descricao": {
      "type": "string",
      "nullable": true
     },
     "custom_da_prova": {
      "type": "boolean"
     }
    }
   },
   "MainMatch": {
    "type": "object",
    "properties": {
     "uuid": {
      "type": "string"
     },
     "nome": {
      "type": "string"
     },
     "ordem": {
      "type": "integer"
     },
     "data_match": {
      "type": "string",
      "format": "date",
      "nullable": true
     },
     "ativo": {
      "type": "boolean"
     },
     "observacao": {
      "type": "string",
      "nullable": true
     }
    }
   },
   "Area": {
    "type": "object",
    "properties": {
     "uuid": {
      "type": "string"
     },
     "nome": {
      "type": "string"
     },
     "ordem": {
      "type": "integer"
     }
    }
   },
   "Stage": {
    "type": "object",
    "properties": {
     "uuid": {
      "type": "string"
     },
     "nome": {
      "type": "string"
     },
     "numero": {
      "type": "integer"
     },
     "area_uuid": {
      "type": "string"
     },
     "tipo_pontuacao": {
      "type": "string"
     },
     "rounds_minimos": {
      "type": "integer",
      "nullable": true
     },
     "pontos_maximos": {
      "type": "integer",
      "nullable": true
     },
     "qtd_alvos_papel": {
      "type": "integer"
     },
     "disparos_por_alvo_papel": {
      "type": "integer"
     },
     "qtd_alvos_metal": {
      "type": "integer"
     },
     "qtd_alvos_noshoot": {
      "type": "integer"
     },
     "tem_alvo_bonus": {
      "type": "boolean"
     },
     "qtd_alvos_bonus": {
      "type": "integer",
      "nullable": true
     },
     "ativa": {
      "type": "boolean"
     }
    }
   },
   "Squad": {
    "type": "object",
    "properties": {
     "uuid": {
      "type": "string"
     },
     "nome": {
      "type": "string"
     },
     "numero": {
      "type": "integer"
     },
     "limite": {
      "type": "integer"
     },
     "main_match_uuid": {
      "type": "string",
      "nullable": true
     },
     "area_uuid": {
      "type": "string",
      "nullable": true
     },
     "ativo": {
      "type": "boolean"
     },
     "observacao": {
      "type": "string",
      "nullable": true
     },
     "inscritos": {
      "type": "integer"
     }
    }
   },
   "ROVinculo": {
    "type": "object",
    "properties": {
     "uuid": {
      "type": "string"
     },
     "arbitro": {
      "type": "object",
      "properties": {
       "uuid": {
        "type": "string"
       },
       "nome": {
        "type": "string"
       },
       "username": {
        "type": "string"
       }
      }
     },
     "ativo": {
      "type": "boolean"
     },
     "pode_check_equipamento": {
      "type": "boolean"
     },
     "pode_crono": {
      "type": "boolean"
     },
     "stages": {
      "type": "array",
      "items": {
       "type": "object",
       "properties": {
        "stage_uuid": {
         "type": "string"
        },
        "stage_numero": {
         "type": "integer"
        },
        "stage_nome": {
         "type": "string"
        }
       }
      }
     }
    }
   },
   "Inscricao": {
    "type": "object",
    "properties": {
     "uuid": {
      "type": "string"
     },
     "nome": {
      "type": "string"
     },
     "email": {
      "type": "string"
     },
     "cpf": {
      "type": "string",
      "nullable": true
     },
     "divisao": {
      "type": "string"
     },
     "divisao_uuid": {
      "type": "string"
     },
     "fator": {
      "type": "string",
      "enum": [
       "menor",
       "maior"
      ]
     },
     "squad_uuid": {
      "type": "string",
      "nullable": true
     },
     "status_inscricao": {
      "type": "string",
      "enum": [
       "pendente",
       "confirmada",
       "cancelada"
      ]
     },
     "status_participacao": {
      "type": "string"
     },
     "status_pgto": {
      "type": "string"
     },
     "perfil_uuid": {
      "type": "string",
      "nullable": true,
      "description": "uuid do atleta (identidade estável)"
     },
     "membro_entidade_uuid": {
      "type": "string",
      "nullable": true,
      "description": "uuid do atleta na entidade"
     },
     "apelido": {
      "type": "string",
      "nullable": true
     },
     "telefone": {
      "type": "string",
      "nullable": true
     },
     "data_nascimento": {
      "type": "string",
      "format": "date",
      "nullable": true
     },
     "clube_filiado": {
      "type": "string",
      "nullable": true
     },
     "classe": {
      "type": "string",
      "nullable": true
     },
     "categoria": {
      "type": "string",
      "nullable": true
     },
     "estado": {
      "type": "string",
      "nullable": true
     },
     "pais": {
      "type": "string",
      "nullable": true
     },
     "sexo": {
      "type": "string",
      "nullable": true
     },
     "endereco": {
      "type": "string",
      "nullable": true,
      "description": "Endereço da inscrição — snapshot próprio, independente do cadastro do atleta."
     },
     "numero": {
      "type": "string",
      "nullable": true
     },
     "complemento": {
      "type": "string",
      "nullable": true
     },
     "bairro": {
      "type": "string",
      "nullable": true
     },
     "cidade": {
      "type": "string",
      "nullable": true
     },
     "uf": {
      "type": "string",
      "nullable": true,
      "maxLength": 2
     },
     "cep": {
      "type": "string",
      "nullable": true
     },
     "presenca": {
      "type": "string",
      "description": "Presença na prova (ex.: nao_informado)"
     },
     "ordem_tiro": {
      "type": "integer",
      "nullable": true
     },
     "criada_em": {
      "type": "string",
      "format": "date-time",
      "nullable": true
     },
     "atualizada_em": {
      "type": "string",
      "format": "date-time",
      "nullable": true
     },
     "external_id": {
      "type": "string",
      "maxLength": 64,
      "nullable": true,
      "description": "Id desta inscrição no **sistema do integrador** (opcional, exclusivo da API). Único por prova — chave de idempotência. Em POST com mais de uma divisão o campo é recusado (422): cada divisão vira uma inscrição e não há como dizer a qual delas o id pertence."
     }
    }
   },
   "EntidadeConfig": {
    "type": "object",
    "properties": {
     "entidade": {
      "type": "object",
      "properties": {
       "uuid": {
        "type": "string"
       },
       "nome": {
        "type": "string"
       },
       "pais": {
        "type": "string"
       },
       "uf": {
        "type": "string",
        "nullable": true
       },
       "gmt_offset": {
        "type": "integer"
       },
       "permite_campeonatos": {
        "type": "boolean"
       }
      }
     },
     "requisitos_inscricao": {
      "type": "object",
      "properties": {
       "email_obrigatorio": {
        "type": "boolean"
       },
       "campos_documentais": {
        "type": "object",
        "description": "cpf, rg, cr, validade_cr — cada um com exibir/obrigatorio/unico",
        "additionalProperties": {
         "type": "object",
         "properties": {
          "exibir": {
           "type": "boolean"
          },
          "obrigatorio": {
           "type": "boolean"
          },
          "unico": {
           "type": "boolean"
          }
         }
        }
       }
      }
     },
     "campos_adicionais": {
      "type": "array",
      "items": {
       "type": "object",
       "properties": {
        "uuid": {
         "type": "string"
        },
        "codigo": {
         "type": "string"
        },
        "rotulo": {
         "type": "string"
        },
        "tipo": {
         "type": "string"
        },
        "obrigatorio": {
         "type": "boolean"
        },
        "unico": {
         "type": "boolean"
        },
        "opcoes": {
         "type": "array",
         "items": {
          "type": "string"
         }
        },
        "ordem": {
         "type": "integer"
        }
       }
      }
     },
     "catalogos": {
      "type": "object",
      "properties": {
       "classes": {
        "type": "array",
        "items": {
         "type": "object",
         "properties": {
          "uuid": {
           "type": "string"
          },
          "codigo": {
           "type": "string",
           "nullable": true
          },
          "nome": {
           "type": "string"
          },
          "ordem": {
           "type": "integer",
           "nullable": true
          }
         }
        }
       },
       "categorias_gestao": {
        "type": "array",
        "items": {
         "type": "object",
         "properties": {
          "uuid": {
           "type": "string"
          },
          "codigo": {
           "type": "string",
           "nullable": true
          },
          "nome": {
           "type": "string"
          },
          "ordem": {
           "type": "integer",
           "nullable": true
          }
         }
        }
       },
       "tags": {
        "type": "array",
        "items": {
         "type": "object",
         "properties": {
          "uuid": {
           "type": "string"
          },
          "codigo": {
           "type": "string",
           "nullable": true
          },
          "nome": {
           "type": "string"
          },
          "tipo": {
           "type": "string",
           "nullable": true
          },
          "sexo": {
           "type": "string",
           "nullable": true
          },
          "idade_min": {
           "type": "integer",
           "nullable": true
          },
          "idade_max": {
           "type": "integer",
           "nullable": true
          }
         }
        }
       }
      }
     },
     "chave": {
      "type": "object",
      "properties": {
       "escopo": {
        "type": "string"
       },
       "pode_escrever": {
        "type": "boolean"
       }
      }
     }
    }
   },
   "AtletaEntidade": {
    "type": "object",
    "properties": {
     "uuid": {
      "type": "string",
      "description": "Vínculo canônico do atleta na entidade"
     },
     "perfil_uuid": {
      "type": "string",
      "nullable": true,
      "description": "Identidade estável do atleta (correlaciona entre provas/entidades)"
     },
     "nome": {
      "type": "string"
     },
     "email": {
      "type": "string"
     },
     "cpf": {
      "type": "string",
      "nullable": true
     },
     "rg": {
      "type": "string",
      "nullable": true
     },
     "cr": {
      "type": "string",
      "nullable": true
     },
     "validade_cr": {
      "type": "string",
      "format": "date",
      "nullable": true
     },
     "federacao_id": {
      "type": "string",
      "nullable": true
     },
     "data_nascimento": {
      "type": "string",
      "format": "date",
      "nullable": true
     },
     "telefone": {
      "type": "string",
      "nullable": true
     },
     "apelido": {
      "type": "string",
      "nullable": true
     },
     "estado": {
      "type": "string",
      "nullable": true
     },
     "pais": {
      "type": "string",
      "nullable": true
     },
     "sexo": {
      "type": "string",
      "nullable": true
     },
     "ativo": {
      "type": "boolean"
     },
     "campos_entidade": {
      "type": "object",
      "description": "Valores dos campos adicionais da entidade, por código (ver campos_adicionais em GET /entidade); {} se vazio",
      "additionalProperties": true
     },
     "criado_em": {
      "type": "string",
      "format": "date-time",
      "nullable": true
     },
     "atualizado_em": {
      "type": "string",
      "format": "date-time",
      "nullable": true
     }
    }
   },
   "UrlPublica": {
    "type": "object",
    "properties": {
     "url": {
      "type": "string",
      "nullable": true
     },
     "ativa": {
      "type": "boolean"
     },
     "motivo": {
      "type": "string",
      "nullable": true,
      "description": "Por que está inativa (null se ativa)"
     },
     "limite_em": {
      "type": "string",
      "format": "date-time",
      "nullable": true,
      "description": "Somente no bloco inscricao: prazo de inscrição (null sem prazo)"
     }
    }
   },
   "ProvaResumo": {
    "type": "object",
    "description": "Item da listagem GET /provas (resumo). O objeto completo vem no detalhe GET /provas/{prova_uuid}.",
    "properties": {
     "uuid": {
      "type": "string",
      "format": "uuid"
     },
     "nome": {
      "type": "string"
     },
     "status": {
      "type": "string",
      "enum": [
       "rascunho",
       "aberta",
       "andamento",
       "encerrada"
      ]
     },
     "data_inicio": {
      "type": "string",
      "format": "date"
     },
     "data_fim": {
      "type": "string",
      "format": "date"
     },
     "local": {
      "type": "string",
      "nullable": true
     },
     "codigo_publico": {
      "type": "string"
     },
     "external_id": {
      "type": "string",
      "maxLength": 64,
      "nullable": true,
      "description": "Id desta prova no **sistema do integrador** (opcional, exclusivo da API — nenhuma tela do Orbit mostra ou edita). Único por entidade, então funciona como chave de idempotência: reenviar o mesmo POST devolve 409 em vez de duplicar. Envie `null` para desvincular. Use `?external_id=` na listagem para reencontrar o registro sem guardar o nosso uuid."
     }
    }
   },
   "AtletaEntidadeResumo": {
    "type": "object",
    "description": "Item da listagem GET /atletas (resumo). O objeto completo vem no detalhe GET /atletas/{atleta_uuid}.",
    "properties": {
     "uuid": {
      "type": "string",
      "description": "Vínculo canônico do atleta na entidade"
     },
     "perfil_uuid": {
      "type": "string",
      "nullable": true,
      "description": "Identidade estável do atleta (correlaciona entre provas/entidades)"
     },
     "nome": {
      "type": "string"
     },
     "email": {
      "type": "string"
     },
     "cpf": {
      "type": "string",
      "nullable": true
     },
     "ativo": {
      "type": "boolean"
     }
    }
   },
   "InscricaoResumo": {
    "type": "object",
    "description": "Item da listagem GET /inscricoes (resumo). O objeto completo (com status_pgto e demais campos) vem no detalhe.",
    "properties": {
     "uuid": {
      "type": "string"
     },
     "nome": {
      "type": "string"
     },
     "email": {
      "type": "string"
     },
     "cpf": {
      "type": "string",
      "nullable": true
     },
     "divisao": {
      "type": "string"
     },
     "divisao_uuid": {
      "type": "string"
     },
     "fator": {
      "type": "string",
      "enum": [
       "menor",
       "maior"
      ]
     },
     "squad_uuid": {
      "type": "string",
      "nullable": true
     },
     "status_inscricao": {
      "type": "string",
      "enum": [
       "pendente",
       "confirmada",
       "cancelada"
      ]
     },
     "status_participacao": {
      "type": "string"
     },
     "perfil_uuid": {
      "type": "string",
      "nullable": true,
      "description": "uuid do atleta (identidade estável)"
     },
     "membro_entidade_uuid": {
      "type": "string",
      "nullable": true,
      "description": "uuid do atleta na entidade"
     },
     "external_id": {
      "type": "string",
      "maxLength": 64,
      "nullable": true,
      "description": "Id desta inscrição no **sistema do integrador** (opcional, exclusivo da API). Único por prova — chave de idempotência. Em POST com mais de uma divisão o campo é recusado (422): cada divisão vira uma inscrição e não há como dizer a qual delas o id pertence."
     }
    }
   }
  }
 },
 "paths": {
  "/entidade": {
   "get": {
    "tags": [
     "Entidade"
    ],
    "summary": "Configuração da entidade da chave",
    "description": "Dados da entidade e **requisitos de inscrição definidos pelo owner**: e-mail obrigatório; CPF/RG/CR/validade com exibir/obrigatório/único; campos adicionais (custom) com obrigatório/único; e catálogos (classes IPSC, categorias de gestão, tags). É a fonte de verdade dos obrigatórios — consulte antes de criar atletas/inscrições.",
    "responses": {
     "200": {
      "description": "Configuração",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/EntidadeConfig"
        },
        "example": {
         "entidade": {
          "uuid": "a3b2c1d0-dddd-4a2b-9c11-8e2f0a9b1cee",
          "nome": "Clube Exemplo",
          "pais": "Brasil",
          "uf": "SP",
          "gmt_offset": -3,
          "permite_campeonatos": true
         },
         "requisitos_inscricao": {
          "email_obrigatorio": true,
          "campos_documentais": {
           "cpf": {
            "exibir": true,
            "obrigatorio": true,
            "unico": true
           },
           "rg": {
            "exibir": true,
            "obrigatorio": false,
            "unico": false
           },
           "cr": {
            "exibir": true,
            "obrigatorio": false,
            "unico": false
           },
           "validade_cr": {
            "exibir": true,
            "obrigatorio": false,
            "unico": false
           }
          }
         },
         "campos_adicionais": [
          {
           "uuid": "b1c0d9e8-1111-4a2b-9c11-8e2f0a9b1dff",
           "codigo": "camiseta_tamanho",
           "rotulo": "Tamanho da camiseta",
           "tipo": "select",
           "obrigatorio": true,
           "unico": false,
           "opcoes": [
            "P",
            "M",
            "G",
            "GG"
           ],
           "ordem": 1
          }
         ],
         "catalogos": {
          "classes": [
           {
            "uuid": "c2d1e0f9-2222-4a2b-9c11-8e2f0a9b1e00",
            "nome": "A",
            "codigo": "A",
            "ordem": 1
           }
          ],
          "categorias_gestao": [
           {
            "uuid": "d3e2f1a0-3333-4a2b-9c11-8e2f0a9b1e11",
            "nome": "Iniciante",
            "codigo": null,
            "ordem": 1
           }
          ],
          "tags": [
           {
            "uuid": "e4f3a2b1-4444-4a2b-9c11-8e2f0a9b1e22",
            "codigo": null,
            "nome": "VIP",
            "tipo": null,
            "sexo": null,
            "idade_min": null,
            "idade_max": null
           }
          ]
         },
         "chave": {
          "escopo": "leitura_escrita",
          "pode_escrever": true
         }
        }
       }
      }
     },
     "401": {
      "description": "Credenciais ausentes ou inválidas.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        }
       }
      }
     },
     "429": {
      "description": "Limite de requisições excedido (header Retry-After).",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        }
       }
      }
     }
    }
   }
  },
  "/atletas": {
   "get": {
    "tags": [
     "Atletas da entidade"
    ],
    "summary": "Listar atletas da entidade",
    "parameters": [
     {
      "name": "q",
      "in": "query",
      "schema": {
       "type": "string"
      },
      "description": "Busca por nome, e-mail ou CPF"
     },
     {
      "name": "ativo",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "0",
        "1"
       ]
      }
     },
     {
      "name": "page",
      "in": "query",
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "per_page",
      "in": "query",
      "schema": {
       "type": "integer",
       "maximum": 200
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Lista paginada",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "atletas": {
           "type": "array",
           "items": {
            "$ref": "#/components/schemas/AtletaEntidadeResumo"
           }
          },
          "page": {
           "type": "integer"
          },
          "per_page": {
           "type": "integer"
          },
          "total": {
           "type": "integer"
          }
         }
        },
        "example": {
         "atletas": [
          {
           "uuid": "e1f0a9b8-bbbb-4a2b-9c11-8e2f0a9b1ccc",
           "perfil_uuid": "f2a1b0c9-cccc-4a2b-9c11-8e2f0a9b1cdd",
           "nome": "Maria Atiradora",
           "email": "maria@example.com",
           "cpf": "12345678900",
           "ativo": true
          }
         ],
         "page": 1,
         "per_page": 50,
         "total": 1
        }
       }
      }
     },
     "401": {
      "description": "Credenciais ausentes ou inválidas.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        }
       }
      }
     },
     "429": {
      "description": "Limite de requisições excedido (header Retry-After).",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        }
       }
      }
     }
    }
   },
   "post": {
    "tags": [
     "Atletas da entidade"
    ],
    "summary": "Cadastrar atleta da entidade",
    "description": "Cadastra o atleta da entidade (membro estável). **Os campos obrigatórios e únicos são definidos pela entidade** — consulte GET /entidade (`requisitos_inscricao`: e-mail obrigatório? CPF/RG/CR obrigatórios/únicos? `campos_adicionais` obrigatórios?). Enviar um campo obrigatório vazio ou violar unicidade retorna 422. Se a identidade (e-mail) já for um membro ativo, retorna 409 com o uuid — use PATCH.",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "nome"
        ],
        "properties": {
         "nome": {
          "type": "string"
         },
         "email": {
          "type": "string",
          "format": "email"
         },
         "cpf": {
          "type": "string"
         },
         "rg": {
          "type": "string"
         },
         "cr": {
          "type": "string"
         },
         "validade_cr": {
          "type": "string",
          "format": "date"
         },
         "federacao_id": {
          "type": "string"
         },
         "data_nascimento": {
          "type": "string",
          "format": "date"
         },
         "telefone": {
          "type": "string"
         },
         "apelido": {
          "type": "string"
         },
         "estado": {
          "type": "string"
         },
         "pais": {
          "type": "string"
         },
         "sexo": {
          "type": "string"
         }
        }
       },
       "example": {
        "nome": "Maria Atiradora",
        "email": "maria@example.com",
        "cpf": "12345678900",
        "telefone": "+5511999999999",
        "data_nascimento": "1990-05-20"
       }
      }
     }
    },
    "responses": {
     "201": {
      "description": "Criado",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "atleta": {
           "$ref": "#/components/schemas/AtletaEntidade"
          }
         }
        },
        "example": {
         "atleta": {
          "uuid": "e1f0a9b8-bbbb-4a2b-9c11-8e2f0a9b1ccc",
          "perfil_uuid": "f2a1b0c9-cccc-4a2b-9c11-8e2f0a9b1cdd",
          "nome": "Maria Atiradora",
          "email": "maria@example.com",
          "cpf": "12345678900",
          "rg": "123456789",
          "cr": "987654",
          "validade_cr": "2027-01-01",
          "federacao_id": "FED-001",
          "data_nascimento": "1990-05-20",
          "telefone": "+5511999999999",
          "apelido": "Mari",
          "estado": "SP",
          "pais": "Brasil",
          "sexo": "F",
          "ativo": true,
          "campos_entidade": {
           "camiseta_tamanho": "M"
          },
          "criado_em": "2026-08-01T12:00:00",
          "atualizado_em": "2026-08-01T12:00:00"
         }
        }
       }
      }
     },
     "401": {
      "description": "Credenciais ausentes ou inválidas.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        }
       }
      }
     },
     "409": {
      "description": "Erro",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        },
        "example": {
         "error": {
          "code": "conflict",
          "message": "Conflito com o estado atual do recurso."
         }
        }
       }
      }
     },
     "422": {
      "description": "Erro",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        },
        "example": {
         "error": {
          "code": "validation_error",
          "message": "Dados inválidos."
         }
        }
       }
      }
     },
     "429": {
      "description": "Limite de requisições excedido (header Retry-After).",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        }
       }
      }
     }
    }
   }
  },
  "/atletas/{atleta_uuid}": {
   "get": {
    "tags": [
     "Atletas da entidade"
    ],
    "summary": "Detalhe do atleta da entidade",
    "parameters": [
     {
      "name": "atleta_uuid",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Atleta",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "atleta": {
           "$ref": "#/components/schemas/AtletaEntidade"
          }
         }
        },
        "example": {
         "atleta": {
          "uuid": "e1f0a9b8-bbbb-4a2b-9c11-8e2f0a9b1ccc",
          "perfil_uuid": "f2a1b0c9-cccc-4a2b-9c11-8e2f0a9b1cdd",
          "nome": "Maria Atiradora",
          "email": "maria@example.com",
          "cpf": "12345678900",
          "rg": "123456789",
          "cr": "987654",
          "validade_cr": "2027-01-01",
          "federacao_id": "FED-001",
          "data_nascimento": "1990-05-20",
          "telefone": "+5511999999999",
          "apelido": "Mari",
          "estado": "SP",
          "pais": "Brasil",
          "sexo": "F",
          "ativo": true,
          "campos_entidade": {
           "camiseta_tamanho": "M"
          },
          "criado_em": "2026-08-01T12:00:00",
          "atualizado_em": "2026-08-01T12:00:00"
         }
        }
       }
      }
     },
     "401": {
      "description": "Credenciais ausentes ou inválidas.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        }
       }
      }
     },
     "404": {
      "description": "Erro",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        },
        "example": {
         "error": {
          "code": "not_found",
          "message": "Recurso não encontrado."
         }
        }
       }
      }
     },
     "429": {
      "description": "Limite de requisições excedido (header Retry-After).",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        }
       }
      }
     }
    }
   },
   "patch": {
    "tags": [
     "Atletas da entidade"
    ],
    "summary": "Atualizar atleta da entidade",
    "parameters": [
     {
      "name": "atleta_uuid",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      }
     }
    ],
    "description": "Vínculo é o uuid; e-mail/identidade não mudam por aqui. CPF/RG/CR revalidados quanto a obrigatoriedade/unicidade.",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "nome": {
          "type": "string"
         },
         "cpf": {
          "type": "string"
         },
         "rg": {
          "type": "string"
         },
         "cr": {
          "type": "string"
         },
         "validade_cr": {
          "type": "string",
          "format": "date"
         },
         "federacao_id": {
          "type": "string"
         },
         "data_nascimento": {
          "type": "string",
          "format": "date"
         },
         "telefone": {
          "type": "string"
         },
         "apelido": {
          "type": "string"
         },
         "estado": {
          "type": "string"
         },
         "pais": {
          "type": "string"
         },
         "sexo": {
          "type": "string"
         },
         "ativo": {
          "type": "boolean"
         }
        }
       },
       "example": {
        "telefone": "+5511988887777",
        "cr": "987654"
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Atualizado",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "atleta": {
           "$ref": "#/components/schemas/AtletaEntidade"
          }
         }
        },
        "example": {
         "atleta": {
          "uuid": "e1f0a9b8-bbbb-4a2b-9c11-8e2f0a9b1ccc",
          "perfil_uuid": "f2a1b0c9-cccc-4a2b-9c11-8e2f0a9b1cdd",
          "nome": "Maria Atiradora",
          "email": "maria@example.com",
          "cpf": "12345678900",
          "rg": "123456789",
          "cr": "987654",
          "validade_cr": "2027-01-01",
          "federacao_id": "FED-001",
          "data_nascimento": "1990-05-20",
          "telefone": "+5511999999999",
          "apelido": "Mari",
          "estado": "SP",
          "pais": "Brasil",
          "sexo": "F",
          "ativo": true,
          "campos_entidade": {
           "camiseta_tamanho": "M"
          },
          "criado_em": "2026-08-01T12:00:00",
          "atualizado_em": "2026-08-01T12:00:00"
         }
        }
       }
      }
     },
     "401": {
      "description": "Credenciais ausentes ou inválidas.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        }
       }
      }
     },
     "404": {
      "description": "Erro",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        },
        "example": {
         "error": {
          "code": "not_found",
          "message": "Recurso não encontrado."
         }
        }
       }
      }
     },
     "422": {
      "description": "Erro",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        },
        "example": {
         "error": {
          "code": "validation_error",
          "message": "Dados inválidos."
         }
        }
       }
      }
     },
     "429": {
      "description": "Limite de requisições excedido (header Retry-After).",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        }
       }
      }
     }
    }
   },
   "delete": {
    "tags": [
     "Atletas da entidade"
    ],
    "summary": "Desativar atleta da entidade",
    "parameters": [
     {
      "name": "atleta_uuid",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      }
     }
    ],
    "description": "Atleta da entidade nunca é apagado: este DELETE apenas **desativa** o membro (ativo=false), preservando o histórico e o vínculo das inscrições. Reative com PATCH {\"ativo\": true}.",
    "responses": {
     "200": {
      "description": "Desativado (não apagado)",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "ok": {
           "type": "boolean"
          },
          "atleta": {
           "type": "string",
           "description": "Nome do atleta desativado"
          },
          "ativo": {
           "type": "boolean"
          },
          "desativado": {
           "type": "boolean",
           "description": "false se o membro já estava inativo"
          }
         }
        },
        "example": {
         "ok": true,
         "atleta": "Maria Atiradora",
         "ativo": false,
         "desativado": true
        }
       }
      }
     },
     "401": {
      "description": "Credenciais ausentes ou inválidas.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        }
       }
      }
     },
     "404": {
      "description": "Erro",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        },
        "example": {
         "error": {
          "code": "not_found",
          "message": "Recurso não encontrado."
         }
        }
       }
      }
     },
     "429": {
      "description": "Limite de requisições excedido (header Retry-After).",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        }
       }
      }
     }
    }
   }
  },
  "/provas": {
   "get": {
    "tags": [
     "Provas"
    ],
    "summary": "Listar provas da entidade",
    "parameters": [
     {
      "name": "status",
      "in": "query",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "page",
      "in": "query",
      "schema": {
       "type": "integer",
       "default": 1
      }
     },
     {
      "name": "per_page",
      "in": "query",
      "schema": {
       "type": "integer",
       "default": 25,
       "maximum": 100
      }
     },
     {
      "name": "external_id",
      "in": "query",
      "schema": {
       "type": "string",
       "maxLength": 64
      },
      "description": "Filtra pela sua própria referência (id no sistema do integrador)."
     }
    ],
    "responses": {
     "200": {
      "description": "Lista paginada",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "provas": {
           "type": "array",
           "items": {
            "$ref": "#/components/schemas/ProvaResumo"
           }
          },
          "page": {
           "type": "integer"
          },
          "per_page": {
           "type": "integer"
          },
          "total": {
           "type": "integer"
          }
         }
        },
        "example": {
         "provas": [
          {
           "uuid": "3fa4c9d2-1234-4a2b-9c11-8e2f0a9b1c22",
           "nome": "Copa Exemplo 2026",
           "status": "aberta",
           "data_inicio": "2026-10-10",
           "data_fim": "2026-10-11",
           "local": "Clube de Tiro Exemplo",
           "codigo_publico": "COPA2026"
          }
         ],
         "page": 1,
         "per_page": 25,
         "total": 1
        }
       }
      }
     },
     "401": {
      "description": "Credenciais ausentes ou inválidas.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        }
       }
      }
     },
     "429": {
      "description": "Limite de requisições excedido (header Retry-After).",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        }
       }
      }
     }
    }
   },
   "post": {
    "tags": [
     "Provas"
    ],
    "summary": "Criar prova (padrões do assistente)",
    "description": "Cria com Main Match padrão, código público e vínculo de RO implícito dos gestores (owner/manager). `divisoes_padrao` importa as divisões IPSC padrão (lista de códigos de modalidade — handgun, rifle, shotgun, mini_rifle, pcc — ou `true` para todas). `campeonato_uuid` vincula ao campeonato (herda o padrão de divisões dele).",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "nome",
         "data_inicio",
         "data_fim"
        ],
        "properties": {
         "nome": {
          "type": "string"
         },
         "data_inicio": {
          "type": "string",
          "format": "date"
         },
         "data_fim": {
          "type": "string",
          "format": "date"
         },
         "descricao": {
          "type": "string"
         },
         "local": {
          "type": "string"
         },
         "status": {
          "type": "string",
          "enum": [
           "rascunho",
           "aberta",
           "andamento",
           "encerrada"
          ]
         },
         "inscricao_limite_em": {
          "type": "string",
          "format": "date-time"
         },
         "inscricao_squad_modo": {
          "type": "string",
          "enum": [
           "mesmo_squad",
           "por_match"
          ]
         },
         "resultados_publicos": {
          "type": "boolean"
         },
         "hub_publico": {
          "type": "boolean"
         },
         "inscricao_publica": {
          "type": "boolean"
         },
         "campeonato_uuid": {
          "type": "string"
         },
         "divisoes_padrao": {
          "oneOf": [
           {
            "type": "boolean"
           },
           {
            "type": "array",
            "items": {
             "type": "string"
            }
           }
          ]
         },
         "external_id": {
          "type": "string",
          "maxLength": 64,
          "nullable": true,
          "description": "Id desta prova no **sistema do integrador** (opcional, exclusivo da API — nenhuma tela do Orbit mostra ou edita). Único por entidade, então funciona como chave de idempotência: reenviar o mesmo POST devolve 409 em vez de duplicar. Envie `null` para desvincular. Use `?external_id=` na listagem para reencontrar o registro sem guardar o nosso uuid."
         }
        }
       },
       "example": {
        "nome": "Copa Exemplo 2026",
        "data_inicio": "2026-10-10",
        "data_fim": "2026-10-11",
        "local": "Clube de Tiro Exemplo",
        "divisoes_padrao": [
         "handgun"
        ]
       }
      }
     }
    },
    "responses": {
     "201": {
      "description": "Criada",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "prova": {
           "$ref": "#/components/schemas/Prova"
          }
         }
        },
        "example": {
         "prova": {
          "uuid": "3fa4c9d2-1234-4a2b-9c11-8e2f0a9b1c22",
          "nome": "Copa Exemplo 2026",
          "status": "aberta",
          "data_inicio": "2026-10-10",
          "data_fim": "2026-10-11",
          "local": "Clube de Tiro Exemplo",
          "descricao": "Prova IPSC nível 1",
          "codigo_publico": "COPA2026",
          "campeonato_uuid": null,
          "resultados_publicos": true,
          "hub_publico": true,
          "inscricao_publica": true,
          "inscricao_limite_em": "2026-10-05T23:59:00",
          "inscricao_multi_divisao": false,
          "inscricao_squad_modo": "mesmo_squad",
          "check_equipamento_modo": "sem_check",
          "criada_em": "2026-08-01T12:00:00",
          "atualizada_em": "2026-08-01T12:00:00"
         }
        }
       }
      }
     },
     "401": {
      "description": "Credenciais ausentes ou inválidas.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        }
       }
      }
     },
     "409": {
      "description": "Erro",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        },
        "example": {
         "error": {
          "code": "conflict",
          "message": "Conflito com o estado atual do recurso."
         }
        }
       }
      }
     },
     "422": {
      "description": "Erro",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        },
        "example": {
         "error": {
          "code": "validation_error",
          "message": "Dados inválidos."
         }
        }
       }
      }
     },
     "429": {
      "description": "Limite de requisições excedido (header Retry-After).",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        }
       }
      }
     }
    }
   }
  },
  "/provas/{prova_uuid}": {
   "get": {
    "tags": [
     "Provas"
    ],
    "summary": "Detalhe da prova",
    "parameters": [
     {
      "name": "prova_uuid",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      },
      "description": "UUID da prova"
     }
    ],
    "responses": {
     "200": {
      "description": "Prova",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "prova": {
           "$ref": "#/components/schemas/Prova"
          }
         }
        },
        "example": {
         "prova": {
          "uuid": "3fa4c9d2-1234-4a2b-9c11-8e2f0a9b1c22",
          "nome": "Copa Exemplo 2026",
          "status": "aberta",
          "data_inicio": "2026-10-10",
          "data_fim": "2026-10-11",
          "local": "Clube de Tiro Exemplo",
          "descricao": "Prova IPSC nível 1",
          "codigo_publico": "COPA2026",
          "campeonato_uuid": null,
          "resultados_publicos": true,
          "hub_publico": true,
          "inscricao_publica": true,
          "inscricao_limite_em": "2026-10-05T23:59:00",
          "inscricao_multi_divisao": false,
          "inscricao_squad_modo": "mesmo_squad",
          "check_equipamento_modo": "sem_check",
          "criada_em": "2026-08-01T12:00:00",
          "atualizada_em": "2026-08-01T12:00:00"
         }
        }
       }
      }
     },
     "401": {
      "description": "Credenciais ausentes ou inválidas.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        }
       }
      }
     },
     "404": {
      "description": "Erro",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        },
        "example": {
         "error": {
          "code": "not_found",
          "message": "Recurso não encontrado."
         }
        }
       }
      }
     },
     "429": {
      "description": "Limite de requisições excedido (header Retry-After).",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        }
       }
      }
     }
    }
   },
   "patch": {
    "tags": [
     "Provas"
    ],
    "summary": "Atualizar prova",
    "parameters": [
     {
      "name": "prova_uuid",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      },
      "description": "UUID da prova"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "description": "Somente os campos enviados são alterados. uuid, codigo_publico e campeonato_uuid não são editáveis por aqui.",
        "properties": {
         "nome": {
          "type": "string"
         },
         "data_inicio": {
          "type": "string",
          "format": "date"
         },
         "data_fim": {
          "type": "string",
          "format": "date"
         },
         "descricao": {
          "type": "string"
         },
         "local": {
          "type": "string"
         },
         "status": {
          "type": "string",
          "enum": [
           "rascunho",
           "aberta",
           "andamento",
           "encerrada"
          ]
         },
         "resultados_publicos": {
          "type": "boolean"
         },
         "hub_publico": {
          "type": "boolean"
         },
         "inscricao_publica": {
          "type": "boolean"
         },
         "inscricao_multi_divisao": {
          "type": "boolean"
         },
         "pin_pelo_portal": {
          "type": "boolean",
          "description": "Permite ao atleta criar ou trocar o PIN pelo portal. Desligada por padrão; o PIN do campo não depende dela."
         },
         "inscricao_limite_em": {
          "type": "string",
          "format": "date-time"
         },
         "inscricao_squad_modo": {
          "type": "string",
          "enum": [
           "mesmo_squad",
           "por_match"
          ]
         }
        }
       },
       "example": {
        "nome": "Copa Exemplo 2026 — Final",
        "status": "andamento"
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Atualizada",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "prova": {
           "$ref": "#/components/schemas/Prova"
          }
         }
        },
        "example": {
         "prova": {
          "uuid": "3fa4c9d2-1234-4a2b-9c11-8e2f0a9b1c22",
          "nome": "Copa Exemplo 2026",
          "status": "aberta",
          "data_inicio": "2026-10-10",
          "data_fim": "2026-10-11",
          "local": "Clube de Tiro Exemplo",
          "descricao": "Prova IPSC nível 1",
          "codigo_publico": "COPA2026",
          "campeonato_uuid": null,
          "resultados_publicos": true,
          "hub_publico": true,
          "inscricao_publica": true,
          "inscricao_limite_em": "2026-10-05T23:59:00",
          "inscricao_multi_divisao": false,
          "inscricao_squad_modo": "mesmo_squad",
          "check_equipamento_modo": "sem_check",
          "criada_em": "2026-08-01T12:00:00",
          "atualizada_em": "2026-08-01T12:00:00"
         }
        }
       }
      }
     },
     "401": {
      "description": "Credenciais ausentes ou inválidas.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        }
       }
      }
     },
     "404": {
      "description": "Erro",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        },
        "example": {
         "error": {
          "code": "not_found",
          "message": "Recurso não encontrado."
         }
        }
       }
      }
     },
     "409": {
      "description": "Erro",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        },
        "example": {
         "error": {
          "code": "conflict",
          "message": "Conflito com o estado atual do recurso."
         }
        }
       }
      }
     },
     "422": {
      "description": "Erro",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        },
        "example": {
         "error": {
          "code": "validation_error",
          "message": "Dados inválidos."
         }
        }
       }
      }
     },
     "429": {
      "description": "Limite de requisições excedido (header Retry-After).",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        }
       }
      }
     }
    }
   },
   "delete": {
    "tags": [
     "Provas"
    ],
    "summary": "Excluir prova (zona de perigo)",
    "description": "Soft-delete em cascata. Exige `?confirmacao=<nome exato da prova>`.",
    "parameters": [
     {
      "name": "prova_uuid",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      },
      "description": "UUID da prova"
     },
     {
      "name": "confirmacao",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Excluída",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "ok": {
           "type": "boolean"
          },
          "excluida": {
           "type": "string",
           "description": "Nome da prova excluída"
          }
         }
        },
        "example": {
         "ok": true,
         "excluida": "Copa Exemplo 2026"
        }
       }
      }
     },
     "401": {
      "description": "Credenciais ausentes ou inválidas.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        }
       }
      }
     },
     "404": {
      "description": "Erro",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        },
        "example": {
         "error": {
          "code": "not_found",
          "message": "Recurso não encontrado."
         }
        }
       }
      }
     },
     "409": {
      "description": "Erro",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        },
        "example": {
         "error": {
          "code": "conflict",
          "message": "Conflito com o estado atual do recurso."
         }
        }
       }
      }
     },
     "429": {
      "description": "Limite de requisições excedido (header Retry-After).",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        }
       }
      }
     }
    }
   }
  },
  "/provas/{prova_uuid}/modalidades": {
   "get": {
    "tags": [
     "Divisões e modalidades"
    ],
    "summary": "Listar modalidades (catálogo IPSC + custom da prova)",
    "parameters": [
     {
      "name": "prova_uuid",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      },
      "description": "UUID da prova"
     }
    ],
    "responses": {
     "200": {
      "description": "Lista",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "modalidades": {
           "type": "array",
           "items": {
            "$ref": "#/components/schemas/Modalidade"
           }
          }
         }
        },
        "example": {
         "modalidades": [
          {
           "uuid": "c3d2e1f0-3333-4a2b-9c11-8e2f0a9b1c44",
           "nome": "Long Range",
           "codigo": "long_range",
           "descricao": "Modalidade custom da prova",
           "custom_da_prova": true
          }
         ]
        }
       }
      }
     },
     "401": {
      "description": "Credenciais ausentes ou inválidas.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        }
       }
      }
     },
     "404": {
      "description": "Erro",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        },
        "example": {
         "error": {
          "code": "not_found",
          "message": "Recurso não encontrado."
         }
        }
       }
      }
     },
     "429": {
      "description": "Limite de requisições excedido (header Retry-After).",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        }
       }
      }
     }
    }
   },
   "post": {
    "tags": [
     "Divisões e modalidades"
    ],
    "summary": "Criar modalidade custom da prova",
    "parameters": [
     {
      "name": "prova_uuid",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      },
      "description": "UUID da prova"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "nome"
        ],
        "properties": {
         "nome": {
          "type": "string"
         },
         "descricao": {
          "type": "string"
         }
        }
       },
       "example": {
        "nome": "Long Range",
        "descricao": "Modalidade custom da prova"
       }
      }
     }
    },
    "responses": {
     "201": {
      "description": "Criada",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "modalidade": {
           "$ref": "#/components/schemas/Modalidade"
          }
         }
        },
        "example": {
         "modalidade": {
          "uuid": "c3d2e1f0-3333-4a2b-9c11-8e2f0a9b1c44",
          "nome": "Long Range",
          "codigo": "long_range",
          "descricao": "Modalidade custom da prova",
          "custom_da_prova": true
         }
        }
       }
      }
     },
     "401": {
      "description": "Credenciais ausentes ou inválidas.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        }
       }
      }
     },
     "409": {
      "description": "Erro",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        },
        "example": {
         "error": {
          "code": "conflict",
          "message": "Conflito com o estado atual do recurso."
         }
        }
       }
      }
     },
     "422": {
      "description": "Erro",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        },
        "example": {
         "error": {
          "code": "validation_error",
          "message": "Dados inválidos."
         }
        }
       }
      }
     },
     "429": {
      "description": "Limite de requisições excedido (header Retry-After).",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        }
       }
      }
     }
    }
   }
  },
  "/provas/{prova_uuid}/divisoes": {
   "get": {
    "tags": [
     "Divisões e modalidades"
    ],
    "summary": "Listar divisoes da prova",
    "parameters": [
     {
      "name": "prova_uuid",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      },
      "description": "UUID da prova"
     }
    ],
    "responses": {
     "200": {
      "description": "Lista",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "divisoes": {
           "type": "array",
           "items": {
            "$ref": "#/components/schemas/Divisao"
           }
          }
         }
        },
        "example": {
         "divisoes": [
          {
           "uuid": "b2c1d0e9-2222-4a2b-9c11-8e2f0a9b1c33",
           "nome": "Production",
           "modalidade": "Handgun",
           "modalidade_uuid": "c3d2e1f0-3333-4a2b-9c11-8e2f0a9b1c44",
           "descricao": null,
           "fator": "menor",
           "has_factor": false
          }
         ]
        }
       }
      }
     },
     "401": {
      "description": "Credenciais ausentes ou inválidas.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        }
       }
      }
     },
     "404": {
      "description": "Erro",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        },
        "example": {
         "error": {
          "code": "not_found",
          "message": "Recurso não encontrado."
         }
        }
       }
      }
     },
     "429": {
      "description": "Limite de requisições excedido (header Retry-After).",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        }
       }
      }
     }
    }
   },
   "post": {
    "tags": [
     "Divisões e modalidades"
    ],
    "summary": "Criar divisão",
    "parameters": [
     {
      "name": "prova_uuid",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      },
      "description": "UUID da prova"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "nome": {
          "type": "string"
         },
         "modalidade_uuid": {
          "type": "string"
         },
         "descricao": {
          "type": "string"
         },
         "fator": {
          "type": "string",
          "enum": [
           "menor",
           "maior"
          ]
         },
         "has_factor": {
          "type": "boolean"
         },
         "importar_padrao": {
          "oneOf": [
           {
            "type": "boolean"
           },
           {
            "type": "array",
            "items": {
             "type": "string"
            }
           }
          ],
          "description": "Se presente, importa as divisões IPSC padrão em vez de criar uma divisão avulsa."
         }
        }
       },
       "example": {
        "nome": "Production",
        "modalidade_uuid": "c3d2e1f0-3333-4a2b-9c11-8e2f0a9b1c44",
        "fator": "menor"
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "importar_padrao sem divisões novas (todas já existiam)",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "description": "Resposta de importar_padrao",
         "properties": {
          "criadas": {
           "type": "integer"
          },
          "ignoradas": {
           "type": "integer"
          },
          "divisoes": {
           "type": "array",
           "items": {
            "$ref": "#/components/schemas/Divisao"
           }
          }
         }
        },
        "example": {
         "criadas": 0,
         "ignoradas": 5,
         "divisoes": []
        }
       }
      }
     },
     "201": {
      "description": "Criado",
      "content": {
       "application/json": {
        "schema": {
         "oneOf": [
          {
           "type": "object",
           "properties": {
            "divisao": {
             "$ref": "#/components/schemas/Divisao"
            }
           }
          },
          {
           "type": "object",
           "description": "Resposta de importar_padrao",
           "properties": {
            "criadas": {
             "type": "integer"
            },
            "ignoradas": {
             "type": "integer"
            },
            "divisoes": {
             "type": "array",
             "items": {
              "$ref": "#/components/schemas/Divisao"
             }
            }
           }
          }
         ]
        },
        "example": {
         "divisao": {
          "uuid": "b2c1d0e9-2222-4a2b-9c11-8e2f0a9b1c33",
          "nome": "Production",
          "modalidade": "Handgun",
          "modalidade_uuid": "c3d2e1f0-3333-4a2b-9c11-8e2f0a9b1c44",
          "descricao": null,
          "fator": "menor",
          "has_factor": false
         }
        }
       }
      }
     },
     "401": {
      "description": "Credenciais ausentes ou inválidas.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        }
       }
      }
     },
     "409": {
      "description": "Erro",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        },
        "example": {
         "error": {
          "code": "conflict",
          "message": "Conflito com o estado atual do recurso."
         }
        }
       }
      }
     },
     "422": {
      "description": "Erro",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        },
        "example": {
         "error": {
          "code": "validation_error",
          "message": "Dados inválidos."
         }
        }
       }
      }
     },
     "429": {
      "description": "Limite de requisições excedido (header Retry-After).",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        }
       }
      }
     }
    },
    "description": "Cria uma divisão (nome + modalidade_uuid) — resposta `{\"divisao\": ...}` com 201. Alternativamente, envie `importar_padrao` (lista de códigos de modalidade — handgun, rifle, shotgun, mini_rifle, pcc — ou `true` para todas) para importar as divisões IPSC padrão: a resposta vira `{\"criadas\", \"ignoradas\", \"divisoes\"}`, com 201 se criou alguma e 200 se todas já existiam."
   }
  },
  "/provas/{prova_uuid}/divisoes/{divisao_uuid}": {
   "patch": {
    "tags": [
     "Divisões e modalidades"
    ],
    "summary": "Atualizar divisão",
    "parameters": [
     {
      "name": "prova_uuid",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      },
      "description": "UUID da prova"
     },
     {
      "name": "divisao_uuid",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      },
      "description": "UUID do recurso"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "nome": {
          "type": "string"
         },
         "modalidade_uuid": {
          "type": "string"
         },
         "descricao": {
          "type": "string"
         },
         "fator": {
          "type": "string",
          "enum": [
           "menor",
           "maior"
          ]
         },
         "has_factor": {
          "type": "boolean"
         },
         "importar_padrao": {
          "oneOf": [
           {
            "type": "boolean"
           },
           {
            "type": "array",
            "items": {
             "type": "string"
            }
           }
          ],
          "description": "Se presente, importa as divisões IPSC padrão em vez de criar uma divisão avulsa."
         }
        }
       },
       "example": {
        "nome": "Production Optics",
        "has_factor": true
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Atualizado",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "divisao": {
           "$ref": "#/components/schemas/Divisao"
          }
         }
        },
        "example": {
         "divisao": {
          "uuid": "b2c1d0e9-2222-4a2b-9c11-8e2f0a9b1c33",
          "nome": "Production",
          "modalidade": "Handgun",
          "modalidade_uuid": "c3d2e1f0-3333-4a2b-9c11-8e2f0a9b1c44",
          "descricao": null,
          "fator": "menor",
          "has_factor": false
         }
        }
       }
      }
     },
     "401": {
      "description": "Credenciais ausentes ou inválidas.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        }
       }
      }
     },
     "404": {
      "description": "Erro",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        },
        "example": {
         "error": {
          "code": "not_found",
          "message": "Recurso não encontrado."
         }
        }
       }
      }
     },
     "409": {
      "description": "Erro",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        },
        "example": {
         "error": {
          "code": "conflict",
          "message": "Conflito com o estado atual do recurso."
         }
        }
       }
      }
     },
     "422": {
      "description": "Erro",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        },
        "example": {
         "error": {
          "code": "validation_error",
          "message": "Dados inválidos."
         }
        }
       }
      }
     },
     "429": {
      "description": "Limite de requisições excedido (header Retry-After).",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        }
       }
      }
     }
    }
   },
   "delete": {
    "tags": [
     "Divisões e modalidades"
    ],
    "summary": "Excluir divisão. Bloqueada (409) se houver atletas inscritos na divisão.",
    "parameters": [
     {
      "name": "prova_uuid",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      },
      "description": "UUID da prova"
     },
     {
      "name": "divisao_uuid",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      },
      "description": "UUID do recurso"
     }
    ],
    "responses": {
     "200": {
      "description": "Excluído",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "ok": {
           "type": "boolean"
          }
         }
        },
        "example": {
         "ok": true
        }
       }
      }
     },
     "401": {
      "description": "Credenciais ausentes ou inválidas.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        }
       }
      }
     },
     "404": {
      "description": "Erro",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        },
        "example": {
         "error": {
          "code": "not_found",
          "message": "Recurso não encontrado."
         }
        }
       }
      }
     },
     "409": {
      "description": "Erro",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        },
        "example": {
         "error": {
          "code": "conflict",
          "message": "Conflito com o estado atual do recurso."
         }
        }
       }
      }
     },
     "429": {
      "description": "Limite de requisições excedido (header Retry-After).",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        }
       }
      }
     }
    }
   }
  },
  "/provas/{prova_uuid}/matches": {
   "get": {
    "tags": [
     "Main Matches"
    ],
    "summary": "Listar matches da prova",
    "parameters": [
     {
      "name": "prova_uuid",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      },
      "description": "UUID da prova"
     }
    ],
    "responses": {
     "200": {
      "description": "Lista",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "matches": {
           "type": "array",
           "items": {
            "$ref": "#/components/schemas/MainMatch"
           }
          }
         }
        },
        "example": {
         "matches": [
          {
           "uuid": "d4e3f2a1-4444-4a2b-9c11-8e2f0a9b1c55",
           "nome": "Main Match",
           "ordem": 1,
           "data_match": "2026-10-10",
           "ativo": true,
           "observacao": null
          }
         ]
        }
       }
      }
     },
     "401": {
      "description": "Credenciais ausentes ou inválidas.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        }
       }
      }
     },
     "404": {
      "description": "Erro",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        },
        "example": {
         "error": {
          "code": "not_found",
          "message": "Recurso não encontrado."
         }
        }
       }
      }
     },
     "429": {
      "description": "Limite de requisições excedido (header Retry-After).",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        }
       }
      }
     }
    }
   },
   "post": {
    "tags": [
     "Main Matches"
    ],
    "summary": "Criar main match",
    "parameters": [
     {
      "name": "prova_uuid",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      },
      "description": "UUID da prova"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "nome": {
          "type": "string"
         },
         "ordem": {
          "type": "integer"
         },
         "data_match": {
          "type": "string",
          "format": "date"
         },
         "observacao": {
          "type": "string"
         }
        }
       },
       "example": {
        "nome": "Main Match 2",
        "ordem": 2,
        "ativo": true
       }
      }
     }
    },
    "responses": {
     "201": {
      "description": "Criado",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "match": {
           "$ref": "#/components/schemas/MainMatch"
          }
         }
        },
        "example": {
         "match": {
          "uuid": "d4e3f2a1-4444-4a2b-9c11-8e2f0a9b1c55",
          "nome": "Main Match",
          "ordem": 1,
          "data_match": "2026-10-10",
          "ativo": true,
          "observacao": null
         }
        }
       }
      }
     },
     "401": {
      "description": "Credenciais ausentes ou inválidas.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        }
       }
      }
     },
     "409": {
      "description": "Erro",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        },
        "example": {
         "error": {
          "code": "conflict",
          "message": "Conflito com o estado atual do recurso."
         }
        }
       }
      }
     },
     "422": {
      "description": "Erro",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        },
        "example": {
         "error": {
          "code": "validation_error",
          "message": "Dados inválidos."
         }
        }
       }
      }
     },
     "429": {
      "description": "Limite de requisições excedido (header Retry-After).",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        }
       }
      }
     }
    }
   }
  },
  "/provas/{prova_uuid}/matches/{match_uuid}": {
   "patch": {
    "tags": [
     "Main Matches"
    ],
    "summary": "Atualizar main match",
    "parameters": [
     {
      "name": "prova_uuid",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      },
      "description": "UUID da prova"
     },
     {
      "name": "match_uuid",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      },
      "description": "UUID do recurso"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "nome": {
          "type": "string"
         },
         "ordem": {
          "type": "integer"
         },
         "data_match": {
          "type": "string",
          "format": "date"
         },
         "observacao": {
          "type": "string"
         },
         "ativo": {
          "type": "boolean"
         }
        }
       },
       "example": {
        "nome": "Main Match A",
        "ativo": true
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Atualizado",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "match": {
           "$ref": "#/components/schemas/MainMatch"
          }
         }
        },
        "example": {
         "match": {
          "uuid": "d4e3f2a1-4444-4a2b-9c11-8e2f0a9b1c55",
          "nome": "Main Match",
          "ordem": 1,
          "data_match": "2026-10-10",
          "ativo": true,
          "observacao": null
         }
        }
       }
      }
     },
     "401": {
      "description": "Credenciais ausentes ou inválidas.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        }
       }
      }
     },
     "404": {
      "description": "Erro",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        },
        "example": {
         "error": {
          "code": "not_found",
          "message": "Recurso não encontrado."
         }
        }
       }
      }
     },
     "409": {
      "description": "Erro",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        },
        "example": {
         "error": {
          "code": "conflict",
          "message": "Conflito com o estado atual do recurso."
         }
        }
       }
      }
     },
     "422": {
      "description": "Erro",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        },
        "example": {
         "error": {
          "code": "validation_error",
          "message": "Dados inválidos."
         }
        }
       }
      }
     },
     "429": {
      "description": "Limite de requisições excedido (header Retry-After).",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        }
       }
      }
     }
    }
   },
   "delete": {
    "tags": [
     "Main Matches"
    ],
    "summary": "Excluir main match. Bloqueado (409) se for o último da prova ou tiver squads/scores; com schedule sem scores exige ?confirmar=1.",
    "parameters": [
     {
      "name": "prova_uuid",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      },
      "description": "UUID da prova"
     },
     {
      "name": "match_uuid",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      },
      "description": "UUID do recurso"
     },
     {
      "name": "confirmar",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string",
       "enum": [
        "1"
       ]
      },
      "description": "Envie confirmar=1 quando a exclusão for destrutiva (409 confirmation_required sem ele)"
     }
    ],
    "responses": {
     "200": {
      "description": "Excluído",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "ok": {
           "type": "boolean"
          }
         }
        },
        "example": {
         "ok": true
        }
       }
      }
     },
     "401": {
      "description": "Credenciais ausentes ou inválidas.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        }
       }
      }
     },
     "404": {
      "description": "Erro",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        },
        "example": {
         "error": {
          "code": "not_found",
          "message": "Recurso não encontrado."
         }
        }
       }
      }
     },
     "409": {
      "description": "Erro",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        },
        "example": {
         "error": {
          "code": "conflict",
          "message": "Conflito com o estado atual do recurso."
         }
        }
       }
      }
     },
     "429": {
      "description": "Limite de requisições excedido (header Retry-After).",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        }
       }
      }
     }
    }
   }
  },
  "/provas/{prova_uuid}/areas": {
   "get": {
    "tags": [
     "Áreas"
    ],
    "summary": "Listar areas da prova",
    "parameters": [
     {
      "name": "prova_uuid",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      },
      "description": "UUID da prova"
     }
    ],
    "responses": {
     "200": {
      "description": "Lista",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "areas": {
           "type": "array",
           "items": {
            "$ref": "#/components/schemas/Area"
           }
          }
         }
        },
        "example": {
         "areas": [
          {
           "uuid": "e5f4a3b2-5555-4a2b-9c11-8e2f0a9b1c66",
           "nome": "Área 1",
           "ordem": 1
          }
         ]
        }
       }
      }
     },
     "401": {
      "description": "Credenciais ausentes ou inválidas.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        }
       }
      }
     },
     "404": {
      "description": "Erro",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        },
        "example": {
         "error": {
          "code": "not_found",
          "message": "Recurso não encontrado."
         }
        }
       }
      }
     },
     "429": {
      "description": "Limite de requisições excedido (header Retry-After).",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        }
       }
      }
     }
    }
   },
   "post": {
    "tags": [
     "Áreas"
    ],
    "summary": "Criar área",
    "parameters": [
     {
      "name": "prova_uuid",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      },
      "description": "UUID da prova"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "nome": {
          "type": "string"
         },
         "ordem": {
          "type": "integer"
         }
        }
       },
       "example": {
        "nome": "Área 2",
        "ordem": 2
       }
      }
     }
    },
    "responses": {
     "201": {
      "description": "Criado",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "area": {
           "$ref": "#/components/schemas/Area"
          }
         }
        },
        "example": {
         "area": {
          "uuid": "e5f4a3b2-5555-4a2b-9c11-8e2f0a9b1c66",
          "nome": "Área 1",
          "ordem": 1
         }
        }
       }
      }
     },
     "401": {
      "description": "Credenciais ausentes ou inválidas.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        }
       }
      }
     },
     "409": {
      "description": "Erro",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        },
        "example": {
         "error": {
          "code": "conflict",
          "message": "Conflito com o estado atual do recurso."
         }
        }
       }
      }
     },
     "422": {
      "description": "Erro",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        },
        "example": {
         "error": {
          "code": "validation_error",
          "message": "Dados inválidos."
         }
        }
       }
      }
     },
     "429": {
      "description": "Limite de requisições excedido (header Retry-After).",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        }
       }
      }
     }
    }
   }
  },
  "/provas/{prova_uuid}/areas/{area_uuid}": {
   "patch": {
    "tags": [
     "Áreas"
    ],
    "summary": "Atualizar área",
    "parameters": [
     {
      "name": "prova_uuid",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      },
      "description": "UUID da prova"
     },
     {
      "name": "area_uuid",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      },
      "description": "UUID do recurso"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "nome": {
          "type": "string"
         },
         "ordem": {
          "type": "integer"
         }
        }
       },
       "example": {
        "nome": "Área 1 — Bay A"
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Atualizado",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "area": {
           "$ref": "#/components/schemas/Area"
          }
         }
        },
        "example": {
         "area": {
          "uuid": "e5f4a3b2-5555-4a2b-9c11-8e2f0a9b1c66",
          "nome": "Área 1",
          "ordem": 1
         }
        }
       }
      }
     },
     "401": {
      "description": "Credenciais ausentes ou inválidas.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        }
       }
      }
     },
     "404": {
      "description": "Erro",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        },
        "example": {
         "error": {
          "code": "not_found",
          "message": "Recurso não encontrado."
         }
        }
       }
      }
     },
     "409": {
      "description": "Erro",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        },
        "example": {
         "error": {
          "code": "conflict",
          "message": "Conflito com o estado atual do recurso."
         }
        }
       }
      }
     },
     "422": {
      "description": "Erro",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        },
        "example": {
         "error": {
          "code": "validation_error",
          "message": "Dados inválidos."
         }
        }
       }
      }
     },
     "429": {
      "description": "Limite de requisições excedido (header Retry-After).",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        }
       }
      }
     }
    }
   },
   "delete": {
    "tags": [
     "Áreas"
    ],
    "summary": "Excluir área. Bloqueada (409) enquanto houver stages na área.",
    "parameters": [
     {
      "name": "prova_uuid",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      },
      "description": "UUID da prova"
     },
     {
      "name": "area_uuid",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      },
      "description": "UUID do recurso"
     }
    ],
    "responses": {
     "200": {
      "description": "Excluído",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "ok": {
           "type": "boolean"
          }
         }
        },
        "example": {
         "ok": true
        }
       }
      }
     },
     "401": {
      "description": "Credenciais ausentes ou inválidas.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        }
       }
      }
     },
     "404": {
      "description": "Erro",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        },
        "example": {
         "error": {
          "code": "not_found",
          "message": "Recurso não encontrado."
         }
        }
       }
      }
     },
     "409": {
      "description": "Erro",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        },
        "example": {
         "error": {
          "code": "conflict",
          "message": "Conflito com o estado atual do recurso."
         }
        }
       }
      }
     },
     "429": {
      "description": "Limite de requisições excedido (header Retry-After).",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        }
       }
      }
     }
    }
   }
  },
  "/provas/{prova_uuid}/stages": {
   "get": {
    "tags": [
     "Stages"
    ],
    "summary": "Listar stages da prova",
    "parameters": [
     {
      "name": "prova_uuid",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      },
      "description": "UUID da prova"
     }
    ],
    "responses": {
     "200": {
      "description": "Lista",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "stages": {
           "type": "array",
           "items": {
            "$ref": "#/components/schemas/Stage"
           }
          }
         }
        },
        "example": {
         "stages": [
          {
           "uuid": "f6a5b4c3-6666-4a2b-9c11-8e2f0a9b1c77",
           "nome": "Stage 1",
           "numero": 1,
           "area_uuid": "e5f4a3b2-5555-4a2b-9c11-8e2f0a9b1c66",
           "tipo_pontuacao": "Comstock",
           "rounds_minimos": null,
           "pontos_maximos": null,
           "qtd_alvos_papel": 4,
           "disparos_por_alvo_papel": 2,
           "qtd_alvos_metal": 0,
           "qtd_alvos_noshoot": 1,
           "tem_alvo_bonus": false,
           "qtd_alvos_bonus": null,
           "ativa": true
          }
         ]
        }
       }
      }
     },
     "401": {
      "description": "Credenciais ausentes ou inválidas.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        }
       }
      }
     },
     "404": {
      "description": "Erro",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        },
        "example": {
         "error": {
          "code": "not_found",
          "message": "Recurso não encontrado."
         }
        }
       }
      }
     },
     "429": {
      "description": "Limite de requisições excedido (header Retry-After).",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        }
       }
      }
     }
    }
   },
   "post": {
    "tags": [
     "Stages"
    ],
    "summary": "Criar stage",
    "parameters": [
     {
      "name": "prova_uuid",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      },
      "description": "UUID da prova"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "nome": {
          "type": "string"
         },
         "numero": {
          "type": "integer"
         },
         "area_uuid": {
          "type": "string"
         },
         "tipo_pontuacao": {
          "type": "string",
          "enum": [
           "Comstock",
           "Virginia",
           "Fixed Time"
          ]
         },
         "qtd_alvos_papel": {
          "type": "integer"
         },
         "disparos_por_alvo_papel": {
          "type": "integer"
         },
         "qtd_alvos_metal": {
          "type": "integer"
         },
         "qtd_alvos_noshoot": {
          "type": "integer"
         },
         "tem_alvo_bonus": {
          "type": "boolean"
         },
         "qtd_alvos_bonus": {
          "type": "integer"
         }
        },
        "required": [
         "area_uuid"
        ]
       },
       "example": {
        "nome": "Stage 1",
        "numero": 1,
        "area_uuid": "e5f4a3b2-5555-4a2b-9c11-8e2f0a9b1c66",
        "tipo_pontuacao": "Comstock",
        "qtd_alvos_papel": 4,
        "disparos_por_alvo_papel": 2,
        "qtd_alvos_metal": 0,
        "qtd_alvos_noshoot": 1
       }
      }
     }
    },
    "responses": {
     "201": {
      "description": "Criado",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "stage": {
           "$ref": "#/components/schemas/Stage"
          }
         }
        },
        "example": {
         "stage": {
          "uuid": "f6a5b4c3-6666-4a2b-9c11-8e2f0a9b1c77",
          "nome": "Stage 1",
          "numero": 1,
          "area_uuid": "e5f4a3b2-5555-4a2b-9c11-8e2f0a9b1c66",
          "tipo_pontuacao": "Comstock",
          "rounds_minimos": null,
          "pontos_maximos": null,
          "qtd_alvos_papel": 4,
          "disparos_por_alvo_papel": 2,
          "qtd_alvos_metal": 0,
          "qtd_alvos_noshoot": 1,
          "tem_alvo_bonus": false,
          "qtd_alvos_bonus": null,
          "ativa": true
         }
        }
       }
      }
     },
     "401": {
      "description": "Credenciais ausentes ou inválidas.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        }
       }
      }
     },
     "409": {
      "description": "Erro",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        },
        "example": {
         "error": {
          "code": "conflict",
          "message": "Conflito com o estado atual do recurso."
         }
        }
       }
      }
     },
     "422": {
      "description": "Erro",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        },
        "example": {
         "error": {
          "code": "validation_error",
          "message": "Dados inválidos."
         }
        }
       }
      }
     },
     "429": {
      "description": "Limite de requisições excedido (header Retry-After).",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        }
       }
      }
     }
    }
   }
  },
  "/provas/{prova_uuid}/stages/{stage_uuid}": {
   "patch": {
    "tags": [
     "Stages"
    ],
    "summary": "Atualizar stage",
    "parameters": [
     {
      "name": "prova_uuid",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      },
      "description": "UUID da prova"
     },
     {
      "name": "stage_uuid",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      },
      "description": "UUID do recurso"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "nome": {
          "type": "string"
         },
         "numero": {
          "type": "integer"
         },
         "area_uuid": {
          "type": "string"
         },
         "tipo_pontuacao": {
          "type": "string",
          "enum": [
           "Comstock",
           "Virginia",
           "Fixed Time"
          ]
         },
         "qtd_alvos_papel": {
          "type": "integer"
         },
         "disparos_por_alvo_papel": {
          "type": "integer"
         },
         "qtd_alvos_metal": {
          "type": "integer"
         },
         "qtd_alvos_noshoot": {
          "type": "integer"
         },
         "tem_alvo_bonus": {
          "type": "boolean"
         },
         "qtd_alvos_bonus": {
          "type": "integer"
         },
         "ativa": {
          "type": "boolean"
         }
        }
       },
       "example": {
        "nome": "Stage 1 — Revisado",
        "qtd_alvos_papel": 6
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Atualizado",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "stage": {
           "$ref": "#/components/schemas/Stage"
          }
         }
        },
        "example": {
         "stage": {
          "uuid": "f6a5b4c3-6666-4a2b-9c11-8e2f0a9b1c77",
          "nome": "Stage 1",
          "numero": 1,
          "area_uuid": "e5f4a3b2-5555-4a2b-9c11-8e2f0a9b1c66",
          "tipo_pontuacao": "Comstock",
          "rounds_minimos": null,
          "pontos_maximos": null,
          "qtd_alvos_papel": 4,
          "disparos_por_alvo_papel": 2,
          "qtd_alvos_metal": 0,
          "qtd_alvos_noshoot": 1,
          "tem_alvo_bonus": false,
          "qtd_alvos_bonus": null,
          "ativa": true
         }
        }
       }
      }
     },
     "401": {
      "description": "Credenciais ausentes ou inválidas.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        }
       }
      }
     },
     "404": {
      "description": "Erro",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        },
        "example": {
         "error": {
          "code": "not_found",
          "message": "Recurso não encontrado."
         }
        }
       }
      }
     },
     "409": {
      "description": "Erro",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        },
        "example": {
         "error": {
          "code": "conflict",
          "message": "Conflito com o estado atual do recurso."
         }
        }
       }
      }
     },
     "422": {
      "description": "Erro",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        },
        "example": {
         "error": {
          "code": "validation_error",
          "message": "Dados inválidos."
         }
        }
       }
      }
     },
     "429": {
      "description": "Limite de requisições excedido (header Retry-After).",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        }
       }
      }
     }
    }
   },
   "delete": {
    "tags": [
     "Stages"
    ],
    "summary": "Excluir stage. Com scores lançados exige ?confirmar=1 (os scores são removidos junto).",
    "parameters": [
     {
      "name": "prova_uuid",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      },
      "description": "UUID da prova"
     },
     {
      "name": "stage_uuid",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      },
      "description": "UUID do recurso"
     },
     {
      "name": "confirmar",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string",
       "enum": [
        "1"
       ]
      },
      "description": "Envie confirmar=1 quando a exclusão for destrutiva (409 confirmation_required sem ele)"
     }
    ],
    "responses": {
     "200": {
      "description": "Excluído",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "ok": {
           "type": "boolean"
          },
          "scores_removidos": {
           "type": "integer"
          }
         }
        },
        "example": {
         "ok": true,
         "scores_removidos": 0
        }
       }
      }
     },
     "401": {
      "description": "Credenciais ausentes ou inválidas.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        }
       }
      }
     },
     "404": {
      "description": "Erro",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        },
        "example": {
         "error": {
          "code": "not_found",
          "message": "Recurso não encontrado."
         }
        }
       }
      }
     },
     "409": {
      "description": "Erro",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        },
        "example": {
         "error": {
          "code": "conflict",
          "message": "Conflito com o estado atual do recurso."
         }
        }
       }
      }
     },
     "429": {
      "description": "Limite de requisições excedido (header Retry-After).",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        }
       }
      }
     }
    }
   }
  },
  "/provas/{prova_uuid}/squads": {
   "get": {
    "tags": [
     "Squads"
    ],
    "summary": "Listar squads da prova",
    "parameters": [
     {
      "name": "prova_uuid",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      },
      "description": "UUID da prova"
     }
    ],
    "responses": {
     "200": {
      "description": "Lista",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "squads": {
           "type": "array",
           "items": {
            "$ref": "#/components/schemas/Squad"
           }
          }
         }
        },
        "example": {
         "squads": [
          {
           "uuid": "a7b6c5d4-7777-4a2b-9c11-8e2f0a9b1c88",
           "nome": "Squad 1",
           "numero": 1,
           "limite": 16,
           "main_match_uuid": "d4e3f2a1-4444-4a2b-9c11-8e2f0a9b1c55",
           "area_uuid": "e5f4a3b2-5555-4a2b-9c11-8e2f0a9b1c66",
           "ativo": true,
           "observacao": null,
           "inscritos": 8
          }
         ]
        }
       }
      }
     },
     "401": {
      "description": "Credenciais ausentes ou inválidas.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        }
       }
      }
     },
     "404": {
      "description": "Erro",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        },
        "example": {
         "error": {
          "code": "not_found",
          "message": "Recurso não encontrado."
         }
        }
       }
      }
     },
     "429": {
      "description": "Limite de requisições excedido (header Retry-After).",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        }
       }
      }
     }
    }
   },
   "post": {
    "tags": [
     "Squads"
    ],
    "summary": "Criar squad",
    "parameters": [
     {
      "name": "prova_uuid",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      },
      "description": "UUID da prova"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "nome": {
          "type": "string"
         },
         "numero": {
          "type": "integer"
         },
         "limite": {
          "type": "integer"
         },
         "main_match_uuid": {
          "type": "string"
         },
         "area_uuid": {
          "type": "string"
         },
         "observacao": {
          "type": "string"
         }
        }
       },
       "example": {
        "nome": "Squad 1",
        "numero": 1,
        "limite": 16,
        "main_match_uuid": "d4e3f2a1-4444-4a2b-9c11-8e2f0a9b1c55",
        "area_uuid": "e5f4a3b2-5555-4a2b-9c11-8e2f0a9b1c66"
       }
      }
     }
    },
    "responses": {
     "201": {
      "description": "Criado",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "squad": {
           "$ref": "#/components/schemas/Squad"
          }
         }
        },
        "example": {
         "squad": {
          "uuid": "a7b6c5d4-7777-4a2b-9c11-8e2f0a9b1c88",
          "nome": "Squad 1",
          "numero": 1,
          "limite": 16,
          "main_match_uuid": "d4e3f2a1-4444-4a2b-9c11-8e2f0a9b1c55",
          "area_uuid": "e5f4a3b2-5555-4a2b-9c11-8e2f0a9b1c66",
          "ativo": true,
          "observacao": null,
          "inscritos": 8
         }
        }
       }
      }
     },
     "401": {
      "description": "Credenciais ausentes ou inválidas.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        }
       }
      }
     },
     "409": {
      "description": "Erro",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        },
        "example": {
         "error": {
          "code": "conflict",
          "message": "Conflito com o estado atual do recurso."
         }
        }
       }
      }
     },
     "422": {
      "description": "Erro",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        },
        "example": {
         "error": {
          "code": "validation_error",
          "message": "Dados inválidos."
         }
        }
       }
      }
     },
     "429": {
      "description": "Limite de requisições excedido (header Retry-After).",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        }
       }
      }
     }
    }
   }
  },
  "/provas/{prova_uuid}/squads/{squad_uuid}": {
   "patch": {
    "tags": [
     "Squads"
    ],
    "summary": "Atualizar squad",
    "parameters": [
     {
      "name": "prova_uuid",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      },
      "description": "UUID da prova"
     },
     {
      "name": "squad_uuid",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      },
      "description": "UUID do recurso"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "nome": {
          "type": "string"
         },
         "numero": {
          "type": "integer"
         },
         "limite": {
          "type": "integer"
         },
         "main_match_uuid": {
          "type": "string"
         },
         "area_uuid": {
          "type": "string"
         },
         "observacao": {
          "type": "string"
         },
         "ativo": {
          "type": "boolean"
         }
        }
       },
       "example": {
        "limite": 20,
        "observacao": "Squad ampliado"
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Atualizado",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "squad": {
           "$ref": "#/components/schemas/Squad"
          }
         }
        },
        "example": {
         "squad": {
          "uuid": "a7b6c5d4-7777-4a2b-9c11-8e2f0a9b1c88",
          "nome": "Squad 1",
          "numero": 1,
          "limite": 16,
          "main_match_uuid": "d4e3f2a1-4444-4a2b-9c11-8e2f0a9b1c55",
          "area_uuid": "e5f4a3b2-5555-4a2b-9c11-8e2f0a9b1c66",
          "ativo": true,
          "observacao": null,
          "inscritos": 8
         }
        }
       }
      }
     },
     "401": {
      "description": "Credenciais ausentes ou inválidas.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        }
       }
      }
     },
     "404": {
      "description": "Erro",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        },
        "example": {
         "error": {
          "code": "not_found",
          "message": "Recurso não encontrado."
         }
        }
       }
      }
     },
     "409": {
      "description": "Erro",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        },
        "example": {
         "error": {
          "code": "conflict",
          "message": "Conflito com o estado atual do recurso."
         }
        }
       }
      }
     },
     "422": {
      "description": "Erro",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        },
        "example": {
         "error": {
          "code": "validation_error",
          "message": "Dados inválidos."
         }
        }
       }
      }
     },
     "429": {
      "description": "Limite de requisições excedido (header Retry-After).",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        }
       }
      }
     }
    }
   },
   "delete": {
    "tags": [
     "Squads"
    ],
    "summary": "Excluir squad. Bloqueado (409) enquanto houver atletas no squad.",
    "parameters": [
     {
      "name": "prova_uuid",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      },
      "description": "UUID da prova"
     },
     {
      "name": "squad_uuid",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      },
      "description": "UUID do recurso"
     }
    ],
    "responses": {
     "200": {
      "description": "Excluído",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "ok": {
           "type": "boolean"
          }
         }
        },
        "example": {
         "ok": true
        }
       }
      }
     },
     "401": {
      "description": "Credenciais ausentes ou inválidas.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        }
       }
      }
     },
     "404": {
      "description": "Erro",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        },
        "example": {
         "error": {
          "code": "not_found",
          "message": "Recurso não encontrado."
         }
        }
       }
      }
     },
     "409": {
      "description": "Erro",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        },
        "example": {
         "error": {
          "code": "conflict",
          "message": "Conflito com o estado atual do recurso."
         }
        }
       }
      }
     },
     "429": {
      "description": "Limite de requisições excedido (header Retry-After).",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        }
       }
      }
     }
    }
   }
  },
  "/arbitros": {
   "get": {
    "tags": [
     "ROs"
    ],
    "summary": "Listar árbitros da entidade aptos a RO",
    "responses": {
     "200": {
      "description": "Lista",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "arbitros": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "uuid": {
              "type": "string"
             },
             "nome": {
              "type": "string"
             },
             "username": {
              "type": "string"
             },
             "email": {
              "type": "string",
              "nullable": true
             },
             "certificacao": {
              "type": "string",
              "nullable": true
             }
            }
           }
          }
         }
        },
        "example": {
         "arbitros": [
          {
           "uuid": "b8c7d6e5-8888-4a2b-9c11-8e2f0a9b1c99",
           "nome": "João RO",
           "username": "joao.ro",
           "email": "joao.ro@example.com",
           "certificacao": "RO"
          }
         ]
        }
       }
      }
     },
     "401": {
      "description": "Credenciais ausentes ou inválidas.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        }
       }
      }
     },
     "429": {
      "description": "Limite de requisições excedido (header Retry-After).",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        }
       }
      }
     }
    }
   }
  },
  "/provas/{prova_uuid}/ros": {
   "get": {
    "tags": [
     "ROs"
    ],
    "summary": "Listar vínculos de RO da prova (inclui os implícitos dos gestores)",
    "parameters": [
     {
      "name": "prova_uuid",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      },
      "description": "UUID da prova"
     }
    ],
    "responses": {
     "200": {
      "description": "Lista",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "ros": {
           "type": "array",
           "items": {
            "$ref": "#/components/schemas/ROVinculo"
           }
          }
         }
        },
        "example": {
         "ros": [
          {
           "uuid": "c9d8e7f6-9999-4a2b-9c11-8e2f0a9b1caa",
           "arbitro": {
            "uuid": "b8c7d6e5-8888-4a2b-9c11-8e2f0a9b1c99",
            "nome": "João RO",
            "username": "joao.ro"
           },
           "ativo": true,
           "pode_check_equipamento": true,
           "pode_crono": false,
           "stages": [
            {
             "stage_uuid": "f6a5b4c3-6666-4a2b-9c11-8e2f0a9b1c77",
             "stage_numero": 1,
             "stage_nome": "Stage 1"
            }
           ]
          }
         ]
        }
       }
      }
     },
     "401": {
      "description": "Credenciais ausentes ou inválidas.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        }
       }
      }
     },
     "404": {
      "description": "Erro",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        },
        "example": {
         "error": {
          "code": "not_found",
          "message": "Recurso não encontrado."
         }
        }
       }
      }
     },
     "429": {
      "description": "Limite de requisições excedido (header Retry-After).",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        }
       }
      }
     }
    }
   },
   "post": {
    "tags": [
     "ROs"
    ],
    "summary": "Vincular árbitro existente como RO da prova",
    "parameters": [
     {
      "name": "prova_uuid",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      },
      "description": "UUID da prova"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "arbitro_uuid",
         "stage_uuids"
        ],
        "properties": {
         "arbitro_uuid": {
          "type": "string"
         },
         "stage_uuids": {
          "type": "array",
          "items": {
           "type": "string"
          }
         },
         "pode_check_equipamento": {
          "type": "boolean"
         },
         "pode_crono": {
          "type": "boolean"
         }
        }
       },
       "example": {
        "arbitro_uuid": "b8c7d6e5-8888-4a2b-9c11-8e2f0a9b1c99",
        "stage_uuids": [
         "f6a5b4c3-6666-4a2b-9c11-8e2f0a9b1c77"
        ],
        "pode_check_equipamento": true,
        "pode_crono": false
       }
      }
     }
    },
    "responses": {
     "201": {
      "description": "Vinculado",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "ro": {
           "$ref": "#/components/schemas/ROVinculo"
          }
         }
        },
        "example": {
         "ro": {
          "uuid": "c9d8e7f6-9999-4a2b-9c11-8e2f0a9b1caa",
          "arbitro": {
           "uuid": "b8c7d6e5-8888-4a2b-9c11-8e2f0a9b1c99",
           "nome": "João RO",
           "username": "joao.ro"
          },
          "ativo": true,
          "pode_check_equipamento": true,
          "pode_crono": false,
          "stages": [
           {
            "stage_uuid": "f6a5b4c3-6666-4a2b-9c11-8e2f0a9b1c77",
            "stage_numero": 1,
            "stage_nome": "Stage 1"
           }
          ]
         }
        }
       }
      }
     },
     "401": {
      "description": "Credenciais ausentes ou inválidas.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        }
       }
      }
     },
     "409": {
      "description": "Erro",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        },
        "example": {
         "error": {
          "code": "conflict",
          "message": "Conflito com o estado atual do recurso."
         }
        }
       }
      }
     },
     "422": {
      "description": "Erro",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        },
        "example": {
         "error": {
          "code": "validation_error",
          "message": "Dados inválidos."
         }
        }
       }
      }
     },
     "429": {
      "description": "Limite de requisições excedido (header Retry-After).",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        }
       }
      }
     }
    }
   }
  },
  "/provas/{prova_uuid}/ros/{ro_uuid}": {
   "delete": {
    "tags": [
     "ROs"
    ],
    "summary": "Remover o RO da prova (e seus stages)",
    "parameters": [
     {
      "name": "prova_uuid",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      },
      "description": "UUID da prova"
     },
     {
      "name": "ro_uuid",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      },
      "description": "UUID do vínculo de RO"
     }
    ],
    "responses": {
     "200": {
      "description": "Removido",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "ok": {
           "type": "boolean"
          }
         }
        },
        "example": {
         "ok": true
        }
       }
      }
     },
     "401": {
      "description": "Credenciais ausentes ou inválidas.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        }
       }
      }
     },
     "404": {
      "description": "Erro",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        },
        "example": {
         "error": {
          "code": "not_found",
          "message": "Recurso não encontrado."
         }
        }
       }
      }
     },
     "429": {
      "description": "Limite de requisições excedido (header Retry-After).",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        }
       }
      }
     }
    }
   }
  },
  "/provas/{prova_uuid}/ros/{ro_uuid}/stages": {
   "post": {
    "tags": [
     "ROs"
    ],
    "summary": "Vincular stages adicionais ao RO",
    "parameters": [
     {
      "name": "prova_uuid",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      },
      "description": "UUID da prova"
     },
     {
      "name": "ro_uuid",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      },
      "description": "UUID do vínculo de RO"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "stage_uuids"
        ],
        "properties": {
         "stage_uuids": {
          "type": "array",
          "items": {
           "type": "string"
          }
         }
        }
       },
       "example": {
        "stage_uuids": [
         "f6a5b4c3-6666-4a2b-9c11-8e2f0a9b1c77"
        ]
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Vinculados",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "ro": {
           "$ref": "#/components/schemas/ROVinculo"
          },
          "vinculados": {
           "type": "integer",
           "description": "Quantos stages foram vinculados agora (já vinculados são ignorados)"
          }
         }
        },
        "example": {
         "ro": {
          "uuid": "c9d8e7f6-9999-4a2b-9c11-8e2f0a9b1caa",
          "arbitro": {
           "uuid": "b8c7d6e5-8888-4a2b-9c11-8e2f0a9b1c99",
           "nome": "João RO",
           "username": "joao.ro"
          },
          "ativo": true,
          "pode_check_equipamento": true,
          "pode_crono": false,
          "stages": [
           {
            "stage_uuid": "f6a5b4c3-6666-4a2b-9c11-8e2f0a9b1c77",
            "stage_numero": 1,
            "stage_nome": "Stage 1"
           }
          ]
         },
         "vinculados": 1
        }
       }
      }
     },
     "401": {
      "description": "Credenciais ausentes ou inválidas.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        }
       }
      }
     },
     "404": {
      "description": "Erro",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        },
        "example": {
         "error": {
          "code": "not_found",
          "message": "Recurso não encontrado."
         }
        }
       }
      }
     },
     "422": {
      "description": "Erro",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        },
        "example": {
         "error": {
          "code": "validation_error",
          "message": "Dados inválidos."
         }
        }
       }
      }
     },
     "429": {
      "description": "Limite de requisições excedido (header Retry-After).",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        }
       }
      }
     }
    }
   }
  },
  "/provas/{prova_uuid}/ros/{ro_uuid}/stages/{stage_uuid}": {
   "delete": {
    "tags": [
     "ROs"
    ],
    "summary": "Desvincular um stage do RO",
    "parameters": [
     {
      "name": "prova_uuid",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      },
      "description": "UUID da prova"
     },
     {
      "name": "ro_uuid",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      },
      "description": "UUID do vínculo de RO"
     },
     {
      "name": "stage_uuid",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      },
      "description": "UUID do stage"
     }
    ],
    "responses": {
     "200": {
      "description": "Desvinculado",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "ok": {
           "type": "boolean"
          }
         }
        },
        "example": {
         "ok": true
        }
       }
      }
     },
     "401": {
      "description": "Credenciais ausentes ou inválidas.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        }
       }
      }
     },
     "404": {
      "description": "Erro",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        },
        "example": {
         "error": {
          "code": "not_found",
          "message": "Recurso não encontrado."
         }
        }
       }
      }
     },
     "429": {
      "description": "Limite de requisições excedido (header Retry-After).",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        }
       }
      }
     }
    }
   }
  },
  "/provas/{prova_uuid}/inscricoes": {
   "get": {
    "tags": [
     "Inscrições"
    ],
    "summary": "Listar inscrições",
    "parameters": [
     {
      "name": "prova_uuid",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      },
      "description": "UUID da prova"
     },
     {
      "name": "divisao_uuid",
      "in": "query",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "squad_uuid",
      "in": "query",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "status_inscricao",
      "in": "query",
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "page",
      "in": "query",
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "per_page",
      "in": "query",
      "schema": {
       "type": "integer",
       "maximum": 200
      }
     },
     {
      "name": "external_id",
      "in": "query",
      "schema": {
       "type": "string",
       "maxLength": 64
      },
      "description": "Filtra pela sua própria referência (id no sistema do integrador)."
     }
    ],
    "responses": {
     "200": {
      "description": "Lista paginada",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "inscricoes": {
           "type": "array",
           "items": {
            "$ref": "#/components/schemas/InscricaoResumo"
           }
          },
          "page": {
           "type": "integer"
          },
          "per_page": {
           "type": "integer"
          },
          "total": {
           "type": "integer"
          }
         }
        },
        "example": {
         "inscricoes": [
          {
           "uuid": "d0e9f8a7-aaaa-4a2b-9c11-8e2f0a9b1cbb",
           "nome": "Maria Atiradora",
           "email": "maria@example.com",
           "cpf": "12345678900",
           "divisao": "Production",
           "divisao_uuid": "b2c1d0e9-2222-4a2b-9c11-8e2f0a9b1c33",
           "fator": "menor",
           "squad_uuid": "a7b6c5d4-7777-4a2b-9c11-8e2f0a9b1c88",
           "status_inscricao": "confirmada",
           "status_participacao": "confirmado",
           "perfil_uuid": "f2a1b0c9-cccc-4a2b-9c11-8e2f0a9b1cdd",
           "membro_entidade_uuid": "e1f0a9b8-bbbb-4a2b-9c11-8e2f0a9b1ccc"
          }
         ],
         "page": 1,
         "per_page": 50,
         "total": 1
        }
       }
      }
     },
     "401": {
      "description": "Credenciais ausentes ou inválidas.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        }
       }
      }
     },
     "404": {
      "description": "Erro",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        },
        "example": {
         "error": {
          "code": "not_found",
          "message": "Recurso não encontrado."
         }
        }
       }
      }
     },
     "429": {
      "description": "Limite de requisições excedido (header Retry-After).",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        }
       }
      }
     }
    }
   },
   "post": {
    "tags": [
     "Inscrições"
    ],
    "summary": "Criar inscrição",
    "description": "Cria uma inscrição por divisão (multi-divisão se a prova permitir). Squad: `squad_uuid` (modo mesmo_squad) ou `squads_por_match` `{match_uuid: squad_uuid}` (modo por_match). Respeita lotação de squad, unicidade atleta/divisão e fator da divisão. Os campos obrigatórios/únicos do atleta seguem a configuração da entidade (ver GET /entidade).",
    "parameters": [
     {
      "name": "prova_uuid",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      },
      "description": "UUID da prova"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "nome",
         "email"
        ],
        "properties": {
         "nome": {
          "type": "string"
         },
         "email": {
          "type": "string",
          "format": "email"
         },
         "cpf": {
          "type": "string"
         },
         "divisao_uuid": {
          "type": "string"
         },
         "divisao_uuids": {
          "type": "array",
          "items": {
           "type": "string"
          }
         },
         "fator": {
          "type": "string",
          "enum": [
           "menor",
           "maior"
          ]
         },
         "squad_uuid": {
          "type": "string"
         },
         "squads_por_match": {
          "type": "object",
          "additionalProperties": {
           "type": "string"
          }
         },
         "telefone": {
          "type": "string"
         },
         "data_nascimento": {
          "type": "string",
          "format": "date"
         },
         "cr": {
          "type": "string"
         },
         "validade_cr": {
          "type": "string",
          "format": "date"
         },
         "apelido": {
          "type": "string"
         },
         "estado": {
          "type": "string"
         },
         "pais": {
          "type": "string"
         },
         "sexo": {
          "type": "string"
         },
         "federacao_id": {
          "type": "string"
         },
         "endereco": {
          "type": "string",
          "description": "Endereço da inscrição — snapshot próprio, independente do cadastro do atleta."
         },
         "numero": {
          "type": "string"
         },
         "complemento": {
          "type": "string"
         },
         "bairro": {
          "type": "string"
         },
         "cidade": {
          "type": "string"
         },
         "uf": {
          "type": "string",
          "maxLength": 2
         },
         "cep": {
          "type": "string"
         },
         "external_id": {
          "type": "string",
          "maxLength": 64,
          "nullable": true,
          "description": "Id desta inscrição no **sistema do integrador** (opcional, exclusivo da API). Único por prova — chave de idempotência. Em POST com mais de uma divisão o campo é recusado (422): cada divisão vira uma inscrição e não há como dizer a qual delas o id pertence."
         }
        }
       },
       "example": {
        "nome": "Maria Atiradora",
        "email": "maria@example.com",
        "cpf": "12345678900",
        "divisao_uuid": "b2c1d0e9-2222-4a2b-9c11-8e2f0a9b1c33",
        "squad_uuid": "a7b6c5d4-7777-4a2b-9c11-8e2f0a9b1c88"
       }
      }
     }
    },
    "responses": {
     "201": {
      "description": "Criada(s)",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "inscricoes": {
           "type": "array",
           "items": {
            "$ref": "#/components/schemas/Inscricao"
           }
          }
         }
        },
        "example": {
         "inscricoes": [
          {
           "uuid": "d0e9f8a7-aaaa-4a2b-9c11-8e2f0a9b1cbb",
           "nome": "Maria Atiradora",
           "email": "maria@example.com",
           "cpf": "12345678900",
           "divisao": "Production",
           "divisao_uuid": "b2c1d0e9-2222-4a2b-9c11-8e2f0a9b1c33",
           "fator": "menor",
           "squad_uuid": "a7b6c5d4-7777-4a2b-9c11-8e2f0a9b1c88",
           "status_inscricao": "confirmada",
           "status_participacao": "confirmado",
           "status_pgto": "pago",
           "perfil_uuid": "f2a1b0c9-cccc-4a2b-9c11-8e2f0a9b1cdd",
           "membro_entidade_uuid": "e1f0a9b8-bbbb-4a2b-9c11-8e2f0a9b1ccc",
           "apelido": "Mari",
           "telefone": "+5511999999999",
           "data_nascimento": "1990-05-20",
           "clube_filiado": "Clube Exemplo",
           "classe": "A",
           "categoria": null,
           "estado": "SP",
           "pais": "Brasil",
           "sexo": "F",
           "presenca": "nao_informado",
           "ordem_tiro": null,
           "criada_em": "2026-08-01T12:00:00",
           "atualizada_em": "2026-08-01T12:00:00"
          }
         ]
        }
       }
      }
     },
     "401": {
      "description": "Credenciais ausentes ou inválidas.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        }
       }
      }
     },
     "409": {
      "description": "Erro",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        },
        "example": {
         "error": {
          "code": "conflict",
          "message": "Conflito com o estado atual do recurso."
         }
        }
       }
      }
     },
     "422": {
      "description": "Erro",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        },
        "example": {
         "error": {
          "code": "validation_error",
          "message": "Dados inválidos."
         }
        }
       }
      }
     },
     "429": {
      "description": "Limite de requisições excedido (header Retry-After).",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        }
       }
      }
     }
    }
   }
  },
  "/provas/{prova_uuid}/inscricoes/{inscricao_uuid}": {
   "get": {
    "tags": [
     "Inscrições"
    ],
    "summary": "Detalhe da inscrição",
    "parameters": [
     {
      "name": "prova_uuid",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      },
      "description": "UUID da prova"
     },
     {
      "name": "inscricao_uuid",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      },
      "description": "UUID da inscrição"
     }
    ],
    "responses": {
     "200": {
      "description": "Inscrição",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "inscricao": {
           "$ref": "#/components/schemas/Inscricao"
          }
         }
        },
        "example": {
         "inscricao": {
          "uuid": "d0e9f8a7-aaaa-4a2b-9c11-8e2f0a9b1cbb",
          "nome": "Maria Atiradora",
          "email": "maria@example.com",
          "cpf": "12345678900",
          "divisao": "Production",
          "divisao_uuid": "b2c1d0e9-2222-4a2b-9c11-8e2f0a9b1c33",
          "fator": "menor",
          "squad_uuid": "a7b6c5d4-7777-4a2b-9c11-8e2f0a9b1c88",
          "status_inscricao": "confirmada",
          "status_participacao": "confirmado",
          "status_pgto": "pago",
          "perfil_uuid": "f2a1b0c9-cccc-4a2b-9c11-8e2f0a9b1cdd",
          "membro_entidade_uuid": "e1f0a9b8-bbbb-4a2b-9c11-8e2f0a9b1ccc",
          "apelido": "Mari",
          "telefone": "+5511999999999",
          "data_nascimento": "1990-05-20",
          "clube_filiado": "Clube Exemplo",
          "classe": "A",
          "categoria": null,
          "estado": "SP",
          "pais": "Brasil",
          "sexo": "F",
          "presenca": "nao_informado",
          "ordem_tiro": null,
          "criada_em": "2026-08-01T12:00:00",
          "atualizada_em": "2026-08-01T12:00:00"
         }
        }
       }
      }
     },
     "401": {
      "description": "Credenciais ausentes ou inválidas.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        }
       }
      }
     },
     "404": {
      "description": "Erro",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        },
        "example": {
         "error": {
          "code": "not_found",
          "message": "Recurso não encontrado."
         }
        }
       }
      }
     },
     "429": {
      "description": "Limite de requisições excedido (header Retry-After).",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        }
       }
      }
     }
    }
   },
   "patch": {
    "tags": [
     "Inscrições"
    ],
    "summary": "Atualizar inscrição",
    "description": "Trocar `fator` com scores já lançados exige `\"confirmar_troca_fator\": true` — os resultados são recalculados e auditados. `squad_uuid` respeita a lotação. `status_inscricao`: pendente | confirmada | cancelada.",
    "parameters": [
     {
      "name": "prova_uuid",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      },
      "description": "UUID da prova"
     },
     {
      "name": "inscricao_uuid",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      },
      "description": "UUID da inscrição"
     }
    ],
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "nome": {
          "type": "string"
         },
         "divisao_uuid": {
          "type": "string"
         },
         "fator": {
          "type": "string",
          "enum": [
           "menor",
           "maior"
          ]
         },
         "confirmar_troca_fator": {
          "type": "boolean"
         },
         "motivo_troca_fator": {
          "type": "string"
         },
         "squad_uuid": {
          "type": "string",
          "nullable": true
         },
         "status_inscricao": {
          "type": "string"
         },
         "status_pgto": {
          "type": "string"
         },
         "telefone": {
          "type": "string"
         },
         "apelido": {
          "type": "string"
         },
         "estado": {
          "type": "string"
         },
         "pais": {
          "type": "string"
         },
         "sexo": {
          "type": "string"
         },
         "data_nascimento": {
          "type": "string",
          "format": "date"
         },
         "cr": {
          "type": "string"
         },
         "endereco": {
          "type": "string",
          "description": "Endereço da inscrição — snapshot próprio, independente do cadastro do atleta."
         },
         "numero": {
          "type": "string"
         },
         "complemento": {
          "type": "string"
         },
         "bairro": {
          "type": "string"
         },
         "cidade": {
          "type": "string"
         },
         "uf": {
          "type": "string",
          "maxLength": 2
         },
         "cep": {
          "type": "string"
         }
        }
       },
       "example": {
        "status_inscricao": "confirmada",
        "squad_uuid": "a7b6c5d4-7777-4a2b-9c11-8e2f0a9b1c88"
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "Atualizada",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "inscricao": {
           "$ref": "#/components/schemas/Inscricao"
          }
         }
        },
        "example": {
         "inscricao": {
          "uuid": "d0e9f8a7-aaaa-4a2b-9c11-8e2f0a9b1cbb",
          "nome": "Maria Atiradora",
          "email": "maria@example.com",
          "cpf": "12345678900",
          "divisao": "Production",
          "divisao_uuid": "b2c1d0e9-2222-4a2b-9c11-8e2f0a9b1c33",
          "fator": "menor",
          "squad_uuid": "a7b6c5d4-7777-4a2b-9c11-8e2f0a9b1c88",
          "status_inscricao": "confirmada",
          "status_participacao": "confirmado",
          "status_pgto": "pago",
          "perfil_uuid": "f2a1b0c9-cccc-4a2b-9c11-8e2f0a9b1cdd",
          "membro_entidade_uuid": "e1f0a9b8-bbbb-4a2b-9c11-8e2f0a9b1ccc",
          "apelido": "Mari",
          "telefone": "+5511999999999",
          "data_nascimento": "1990-05-20",
          "clube_filiado": "Clube Exemplo",
          "classe": "A",
          "categoria": null,
          "estado": "SP",
          "pais": "Brasil",
          "sexo": "F",
          "presenca": "nao_informado",
          "ordem_tiro": null,
          "criada_em": "2026-08-01T12:00:00",
          "atualizada_em": "2026-08-01T12:00:00"
         }
        }
       }
      }
     },
     "401": {
      "description": "Credenciais ausentes ou inválidas.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        }
       }
      }
     },
     "404": {
      "description": "Erro",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        },
        "example": {
         "error": {
          "code": "not_found",
          "message": "Recurso não encontrado."
         }
        }
       }
      }
     },
     "409": {
      "description": "Erro",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        },
        "example": {
         "error": {
          "code": "conflict",
          "message": "Conflito com o estado atual do recurso."
         }
        }
       }
      }
     },
     "422": {
      "description": "Erro",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        },
        "example": {
         "error": {
          "code": "validation_error",
          "message": "Dados inválidos."
         }
        }
       }
      }
     },
     "429": {
      "description": "Limite de requisições excedido (header Retry-After).",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        }
       }
      }
     }
    }
   },
   "delete": {
    "tags": [
     "Inscrições"
    ],
    "summary": "Excluir inscrição",
    "description": "Com scores já lançados exige `?confirmar=1` (409 `confirmation_required` sem a confirmação); inscrição e scores saem em soft-delete auditado.",
    "parameters": [
     {
      "name": "prova_uuid",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      },
      "description": "UUID da prova"
     },
     {
      "name": "inscricao_uuid",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      },
      "description": "UUID da inscrição"
     },
     {
      "name": "confirmar",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "1"
       ]
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Excluída",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "ok": {
           "type": "boolean"
          },
          "excluida": {
           "type": "string",
           "description": "Nome do atleta da inscrição excluída"
          },
          "scores_removidos": {
           "type": "integer"
          }
         }
        },
        "example": {
         "ok": true,
         "excluida": "Maria Atiradora",
         "scores_removidos": 0
        }
       }
      }
     },
     "401": {
      "description": "Credenciais ausentes ou inválidas.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        }
       }
      }
     },
     "404": {
      "description": "Erro",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        },
        "example": {
         "error": {
          "code": "not_found",
          "message": "Recurso não encontrado."
         }
        }
       }
      }
     },
     "409": {
      "description": "Erro",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        },
        "example": {
         "error": {
          "code": "conflict",
          "message": "Conflito com o estado atual do recurso."
         }
        }
       }
      }
     },
     "429": {
      "description": "Limite de requisições excedido (header Retry-After).",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        }
       }
      }
     }
    }
   }
  },
  "/provas/{prova_uuid}/resultados": {
   "get": {
    "tags": [
     "Resultados"
    ],
    "summary": "Resultados completos da prova",
    "description": "JSON no formato do visualizador m.scoring.services: `matches[]` com `match_pfs` (tabelas Major/Minor), `stages[]` (alvos, req. shots, max HF geral e por divisão) e `divisions{}` (atletas com hits por stage, hit factor, stage/match points, squad, classe, power factor e DQ). Por padrão só scores aprovados; `?incluir_nao_aprovados=1` inclui os pendentes.",
    "parameters": [
     {
      "name": "prova_uuid",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      },
      "description": "UUID da prova"
     },
     {
      "name": "incluir_nao_aprovados",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "1"
       ]
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Resultados",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "description": "Formato m.scoring.services"
        },
        "example": {
         "matches": [
          {
           "uuid": "d4e3f2a1-4444-4a2b-9c11-8e2f0a9b1c55",
           "nome": "Main Match",
           "match_pfs": {
            "major": 1000,
            "minor": 1000
           }
          }
         ],
         "stages": [
          {
           "uuid": "f6a5b4c3-6666-4a2b-9c11-8e2f0a9b1c77",
           "numero": 1,
           "nome": "Stage 1",
           "max_hf_geral": 10.5
          }
         ],
         "divisions": {
          "Production": [
           {
            "nome": "Maria Atiradora",
            "squad": 1,
            "classe": "A",
            "power_factor": "minor",
            "stage_points": [
             95.5
            ],
            "match_points": 95.5,
            "dq": false
           }
          ]
         }
        }
       }
      }
     },
     "401": {
      "description": "Credenciais ausentes ou inválidas.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        }
       }
      }
     },
     "404": {
      "description": "Erro",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        },
        "example": {
         "error": {
          "code": "not_found",
          "message": "Recurso não encontrado."
         }
        }
       }
      }
     },
     "429": {
      "description": "Limite de requisições excedido (header Retry-After).",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        }
       }
      }
     }
    }
   }
  },
  "/provas/{prova_uuid}/urls": {
   "get": {
    "tags": [
     "Resultados"
    ],
    "summary": "URLs públicas da prova",
    "description": "Links públicos da prova (inscrição, resultados, hub) e o endpoint JSON de resultados desta API. Cada um traz `ativa` e, quando fechado, o `motivo`. Respeita PUBLIC_HOST.",
    "parameters": [
     {
      "name": "prova_uuid",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string",
       "format": "uuid"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "URLs",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "codigo_publico": {
           "type": "string",
           "nullable": true
          },
          "urls": {
           "type": "object",
           "properties": {
            "inscricao": {
             "$ref": "#/components/schemas/UrlPublica"
            },
            "resultados": {
             "$ref": "#/components/schemas/UrlPublica"
            },
            "hub": {
             "$ref": "#/components/schemas/UrlPublica"
            },
            "resultados_json": {
             "$ref": "#/components/schemas/UrlPublica"
            }
           }
          }
         }
        },
        "example": {
         "codigo_publico": "COPA2026",
         "urls": {
          "inscricao": {
           "url": "https://orbit.scoring.services/i/COPA2026",
           "ativa": true,
           "motivo": null,
           "limite_em": "2026-10-05T23:59:00"
          },
          "resultados": {
           "url": "https://orbit.scoring.services/r/COPA2026",
           "ativa": true,
           "motivo": null
          },
          "hub": {
           "url": "https://orbit.scoring.services/p/COPA2026",
           "ativa": true,
           "motivo": null
          },
          "resultados_json": {
           "url": "https://orbit.scoring.services/api/v1/provas/3fa4c9d2-1234-4a2b-9c11-8e2f0a9b1c22/resultados",
           "ativa": true,
           "motivo": null
          }
         }
        }
       }
      }
     },
     "401": {
      "description": "Credenciais ausentes ou inválidas.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        }
       }
      }
     },
     "404": {
      "description": "Erro",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        },
        "example": {
         "error": {
          "code": "not_found",
          "message": "Recurso não encontrado."
         }
        }
       }
      }
     },
     "429": {
      "description": "Limite de requisições excedido (header Retry-After).",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Erro"
        }
       }
      }
     }
    }
   }
  }
 }
}