Status: Approved · v2 · SPEC-API-CHAMP-001

depends_on: SPEC-DOMAIN-CHAMPIONSHIP-001, SPEC-DOMAIN-PAYMENT-001, SPEC-DOMAIN-MATCH-001

used_by: IS-MVP-07.1, IS-MVP-07.2, IS-MVP-07.3, IS-MVP-07.4, IS-MVP-07.5

API de campeonatos

Criação, publicação paga, edições, regulamento, inscrição, atletas, formato, fixtures, classificação e disciplina.

Princípios e padrões

• Base path /api/v1; JSON UTF-8; chaves em camelCase.
• Toda resposta usa ApiResponse<T> com ok, data|error e meta contendo requestId e timestamp.
• IDs são strings opacas; datas são ISO-8601 UTC; dinheiro é inteiro em centavos com moeda BRL.
• Listas usam page e pageSize no MVP; default 20, máximo 100; metadados ficam em meta.pagination.
• Endpoints públicos usam DTOs públicos específicos; entidades internas, memberships, saldos e dados privados nunca vazam.
• Erros de domínio são estáveis e acionáveis; stack traces e detalhes internos não são retornados.
• Alterações sensíveis usam Idempotency-Key, confirmação recente quando necessário e audit log.
• Uploads usam fluxo presigned; o backend valida propósito, MIME, tamanho e ownership antes de confirmar o asset.

Endpoints

Método	Rota	Acesso	Request	Response	Regras principais
POST	/championships	Autenticado	CreateChampionshipRequest	ChampionshipManagementResponse	Draft + owner.
PATCH	/championships/:id	championship.editProfile	UpdateChampionshipRequest	ChampionshipManagementResponse	Enquanto regras permitem.
POST	/championships/:id/publish	championship.publish	PublishChampionshipRequest	PaymentResponse	Pix separado, 30 min.
POST	/championships/:id/editions	championship.manageEditions	CreateEditionRequest	EditionResponse	Dados/janelas.
PUT	/championships/:id/editions/:editionId/regulation	championship.manageRegulation	UpsertRegulationRequest	RegulationResponse	Texto+structured+PDF.
POST	/championships/:id/editions/:editionId/registrations/invite	championship.manageRegistrations	InviteTeamRequest	RegistrationResponse	Invite.
POST	/championships/:id/editions/:editionId/registrations/request	Team manager	RequestRegistrationRequest	RegistrationResponse	Request.
POST	/championships/:id/editions/:editionId/registrations/:rid/decide	championship.manageRegistrations	DecideRegistrationRequest	RegistrationResponse	Approve/reject.
PUT	/championships/:id/editions/:editionId/format	championship.manageFormat	ConfigureFormatRequest	FormatResponse	Formato MVP.
POST	/championships/:id/editions/:editionId/phases	championship.manageFormat	CreatePhaseRequest	PhaseResponse	Group/knockout/final.
POST	/championships/:id/editions/:editionId/fixtures/generate	championship.manageFixtures	GenerateFixturesRequest	FixturePreviewResponse	Preview idempotente.
POST	/championships/:id/editions/:editionId/fixtures/confirm	championship.manageFixtures	ConfirmFixturesRequest	FixturesResponse	Cria matches; datas podem pending.
GET	/championships/:id/editions/:editionId/standings	Público	StandingsQuery	StandingsResponse	Validated only.
GET	/championships/:id/editions/:editionId/top-scorers	Público	StatsQuery	TopScorersResponse	Privacy/confirmed stats.
PUT	/championships/:id/editions/:editionId/discipline	championship.manageDiscipline	DisciplineRulesRequest	DisciplineRulesResponse	Cartões/suspensão/override policy.

Autenticação e autorização

• Draft privado para gestão; publicado público.
• Permission por campeonato, não por time.
• Times só manipulam sua inscrição/contestação dentro da regra.

Erros de domínio

Código	HTTP	Quando ocorre	Ação esperada no cliente
CHAMPIONSHIP_NOT_PUBLISHED	409	Operação pública antes do pagamento	Publicar.
REGISTRATION_WINDOW_CLOSED	410	Fora da janela	Bloquear.
FORMAT_INCOMPATIBLE	422	Times/fases incompatíveis	Reconfigurar.
FIXTURE_GENERATION_CONFLICT	409	Já confirmado/estrutura mudou	Reabrir preview.
ATHLETE_INELIGIBLE	422	Regra estruturada falhou	Exibir motivo.
REGULATION_LOCKED	409	Alteração após lock	Criar versão/retificação conforme policy.

Idempotência e concorrência

• Publish e fixture confirm obrigatórios.
• Payment effect publica uma única vez.
• Fixture generator usa inputHash para detectar mudança.

Auditoria e efeitos colaterais

• Publication, regulation versions, registration decisions, fixture generation, discipline override e result authority auditados.
• Notificações para gestores/times.

Exemplos

format

{
  "type": "groups_then_knockout",
  "groupCount": 2,
  "teamsPerGroup": 4,
  "advancePerGroup": 2,
  "homeAway": false
}

fixturePreview

{
  "previewId": "fixture_preview_001",
  "inputHash": "sha256:...",
  "matches": [
    {
      "homeTeamId": "team_001",
      "awayTeamId": "team_002",
      "datePending": true
    }
  ]
}

Mocks

• Payment fake publica; formatos geram fixtures determinísticos.
• Empty inscrições e conflicts configuráveis.

Testes obrigatórios

• Draft/publish expiration.
• Registration modes/windows.
• Format validation.
• Fixture idempotency.
• Validated standings.
• Discipline override audit.

Critérios de aceite

• Todos os formatos MVP representados.
• Datas podem ser definidas depois.
• Regulamento público e versionado.

Machine summary

spec: SPEC-API-CHAMP-001
api_group: API de campeonatos
base_path: /api/v1
response_envelope: ApiResponse<T>
ids: string
dates: ISO-8601
money: integer_cents