Status: Approved · v2 · SPEC-API-TEAM-TORCIDA-001

depends_on: SPEC-DOMAIN-TEAM-001, SPEC-DOMAIN-TORCIDA-001, SPEC-DOMAIN-PERMISSION-001

used_by: IS-MVP-04.1, IS-MVP-04.2, IS-MVP-04.3, IS-MVP-04.4, IS-MVP-04.5, IS-MVP-05.2, IS-MVP-08.1, IS-MVP-08.2

API de gestão de times e torcidas

Casos de uso administrativos completos, respeitando vínculos, categories, aprovação e permission keys.

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	/teams	Autenticado	CreateTeamRequest	CreateTeamResponse	Criador vira primary_owner; district obrigatório.
PATCH	/teams/:teamId	team.editProfile	UpdateTeamRequest	TeamManagementResponse	Slug/território/identity auditados.
GET	/teams/:teamId/management-summary	Membership	—	TeamManagementSummaryResponse	Dados por permission.
POST	/teams/:teamId/categories	team.manageCategories	CreateCategoryRequest	TeamCategoryResponse	Tag do mesmo time.
PATCH	/teams/:teamId/categories/:categoryId	team.manageCategories	UpdateCategoryRequest	TeamCategoryResponse	Não remove histórico.
GET	/teams/:teamId/player-links	team.viewSquad	PlayerLinkQuery	TeamPlayerLinksResponse	Active/invited/guest/former.
POST	/teams/:teamId/player-invites	team.manageSquad	InvitePlayerRequest	TeamPlayerLinkResponse	Cadastrado precisa aceitar.
POST	/teams/:teamId/guests	team.manageSquad	CreateGuestPlayerRequest	TeamPlayerLinkResponse	Dados privados mínimos.
POST	/team-player-links/:linkId/respond	Jogador alvo	RespondPlayerInviteRequest	TeamPlayerLinkResponse	Accept/reject.
POST	/team-player-links/:linkId/end	Jogador ou team.manageSquad	EndPlayerLinkRequest	TeamPlayerLinkResponse	Vira former.
GET	/teams/:teamId/torcida-requests	team.manageTorcidas	—	TorcidaRequestsResponse	Pending approvals.
POST	/teams/:teamId/torcida-requests/:torcidaId/approve	team.manageTorcidas	DecisionReasonRequest	TorcidaLinkResponse	Aprova existência.
POST	/torcidas	Autenticado	CreateTorcidaRequest	CreateTorcidaResponse	Owner + wallet + pending team approval.
PATCH	/torcidas/:torcidaId	torcida.editProfile	UpdateTorcidaRequest	TorcidaManagementResponse	Dados públicos.
GET	/torcidas/:torcidaId/members	torcida.manageMembers	MembershipQuery	TorcidaMembersResponse	Fila e ativos.
POST	/torcidas/:torcidaId/join	Autenticado	JoinTorcidaRequest	TorcidaMemberResponse	Conforme join mode.
POST	/torcidas/:torcidaId/members/:memberId/approve	torcida.manageMembers	DecisionReasonRequest	TorcidaMemberResponse	Ativa vínculo.

Autenticação e autorização

• Toda rota de gestão exige membership active e permission adequada.
• Primary owner actions usam auth recente/confirmation.
• Gestor do time não recebe automaticamente acesso da torcida aprovada.

Erros de domínio

Código	HTTP	Quando ocorre	Ação esperada no cliente
DISTRICT_MISMATCH	422	Neighborhood/time fora do distrito	Corrigir território.
PLAYER_ALREADY_LINKED	409	Active/invited existente	Abrir vínculo atual.
PLAYER_NOT_INVITABLE	409	Jogador retired ou perfil não ativo	Buscar outro jogador.
PLAYER_INVITE_EXPIRED	410	Convite expirado	Solicitar novo.
INVITE_ALREADY_RESOLVED	409	Convite já aceito/rejeitado	Atualizar.
PLAYER_RETIRED	409	Jogador aposentado tenta aceitar convite	Bloquear; ver SPEC-DOMAIN-PLAYER-001.
TORCIDA_NOT_APPROVED	409	Ação pública/financeira antes de aprovação	Mostrar checklist.
MANAGER_LIMIT_REACHED	409	Limite recomendado/duro configurado	Remover ou revisar acessos.

Idempotência e concorrência

• Create team/torcida/invite/guest/end/approve usam idempotência para evitar duplicação por retry.
• Vínculos usam versão para evitar duas decisões simultâneas.

Auditoria e efeitos colaterais

• Mudanças de identidade, categorias, vínculos, aprovação e ownership geram audit log.
• Convites e decisões geram notifications pessoais/gestão.

Exemplos

createTeam

{
  "name": "Unidos do 6",
  "districtId": "district_001",
  "neighborhoodId": "neighborhood_001",
  "categories": [
    {
      "name": "Principal"
    }
  ]
}

invitePlayer

{
  "playerId": "player_004",
  "categoryIds": [
    "cat_001"
  ],
  "message": "Chega junto para o próximo jogo."
}

Mocks

• Handlers stateful para categorias e player links.
• Cenários pending/rejected/approved torcida.
• Permissions variam por role.

Testes obrigatórios

• Creator becomes owner.
• District mismatch.
• Invite accept/reject/expire.
• Guest privacy.
• End link former.
• Torcida approval independent management.

Critérios de aceite

• Fluxo completo de elenco e torcida sem bypass.
• Nenhum endpoint cria subtime por categoria.
• Todos os efeitos são refletidos nos mocks.

Machine summary

spec: SPEC-API-TEAM-TORCIDA-001
api_group: API de gestão de times e torcidas
base_path: /api/v1
response_envelope: ApiResponse<T>
ids: string
dates: ISO-8601
money: integer_cents