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

depends_on: SPEC-DOMAIN-MATCH-001, SPEC-DOMAIN-PLAYER-001

used_by: IS-MVP-06.1, IS-MVP-06.2, IS-MVP-06.3, IS-MVP-06.4, IS-MVP-06.5

API de partidas, resultados e súmulas

Ciclo completo de criação, agenda, eventos, resultado, validação, contestação e retificação.

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	/matches	Contextual team/champ permission	CreateMatchRequest	MatchManagementResponse	Dois times; campo ou local livre; data pending opcional.
PATCH	/matches/:matchId	match.edit	UpdateMatchRequest	MatchManagementResponse	Respeita status/authority.
GET	/matches	Público	MatchSearchQuery	MatchesResponse	Filtros e paginação.
POST	/matches/:matchId/start	match.manage	StartMatchRequest	MatchManagementResponse	Scheduled → in_progress.
POST	/matches/:matchId/result	match.reportResult	ReportMatchResultRequest	MatchResultResponse	Placar e origem.
POST	/matches/:matchId/validate	Oponente/champ authority	ValidateResultRequest	MatchResultResponse	Consolida stats/ranking.
POST	/matches/:matchId/contest	Elegível	ContestResultRequest	MatchDisputeResponse	Motivo/evidências/prazo.
POST	/matches/:matchId/retifications	Authority	CreateRetificationRequest	RetificationResponse	Audit e recompute.
GET	/matches/:matchId/report	Público/gestão	—	MatchReportResponse	View filtrada.
PUT	/matches/:matchId/report	match.manageReport	UpsertMatchReportRequest	MatchReportResponse	Relacionados/titulares/banco/eventos.
POST	/matches/:matchId/events	match.manageReport	CreateMatchEventRequest	MatchEventResponse	Goal/card/substitution.
POST	/matches/:matchId/guest-players	match.manageReport	CreateMatchGuestRequest	MatchParticipantResponse	Guest no contexto.
DELETE	/matches/:matchId/events/:eventId	match.manageReport	DeleteEventRequest	OperationResponse	Somente antes do lock ou via retificação.

Autenticação e autorização

• Autoridade varia entre amistoso e campeonato.
• Participantes e gestores só veem dados privados necessários.
• Public report omite documentos e dados de guests.

Erros de domínio

Código	HTTP	Quando ocorre	Ação esperada no cliente
MATCH_STATE_INVALID	409	Ação incompatível com status	Recarregar.
RESULT_ALREADY_VALIDATED	409	Validação já concluída	Abrir resultado.
VALIDATION_NOT_ALLOWED	403	Usuário/time sem autoridade	Explicar.
CONTEST_WINDOW_CLOSED	410	Prazo encerrado	Suporte/retificação autorizada.
EVENT_INCONSISTENT	422	Jogador/time/minuto inválido	Corrigir súmula.
FIXTURE_LOCKED	409	Jogo controlado por campeonato	Usar gestão campeonato.

Idempotência e concorrência

• Create/report/validate/contest/retification usam idempotência.
• Validação concorrente consolida uma única vez.
• Recompute de stats é transacional com alteração validada.

Auditoria e efeitos colaterais

• Toda transição e mudança de resultado/súmula é auditada.
• Notifications para times, campeonato e jogadores quando relevante.
• Auto-validation job registra actor system e regra usada.

Exemplos

result

{
  "homeScore": 2,
  "awayScore": 1,
  "reportedByTeamId": "team_001",
  "notes": "Placar conferido com a súmula."
}

event

{
  "type": "goal",
  "teamId": "team_001",
  "playerReference": {
    "kind": "registered",
    "playerId": "player_004"
  },
  "minute": 57
}

Mocks

• Clock e auto-validation determinísticos.
• Cenários friendly/championship/contested/validated.
• Eventos alteram report state.

Testes obrigatórios

• State machine completa.
• Double validation.
• Contest windows.
• Guest stats privacy.
• Retification recompute.
• Invalid event.

Critérios de aceite

• Stats/ranking apenas após validação.
• Contestados não consolidam.
• Súmula e resultado permanecem auditáveis.

Machine summary

spec: SPEC-API-MATCH-001
api_group: API de partidas, resultados e súmulas
base_path: /api/v1
response_envelope: ApiResponse<T>
ids: string
dates: ISO-8601
money: integer_cents