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

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

used_by: IS-MVP-01.1, IS-MVP-01.2, IS-MVP-01.3, IS-MVP-01.4, IS-MVP-01.5, IS-MVP-01.6, IS-MVP-01.7

API de entidades e páginas públicas

Leitura pública canônica e ações sociais protegidas para times, jogadores, torcidas, campeonatos, partidas, campos, serviços e territórios.

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
GET	/teams/:slug	Público + auth opcional	PublicEntityQuery	PublicTeamResponse	Inclui viewer relation quando autenticado.
GET	/players/:slug	Público	—	PublicPlayerResponse	Respeita privacy matrix.
GET	/torcidas/:slug	Público	—	PublicTorcidaResponse	Só approved/visível.
GET	/championships/:slug	Público	—	PublicChampionshipResponse	Draft não público.
GET	/matches/:matchId	Público	—	PublicMatchResponse	Resultado/report conforme status.
GET	/fields/:slug	Público	—	PublicFieldResponse	Endereço conforme visibility.
GET	/services/:slug	Público	—	PublicServiceResponse	Contato/portfolio públicos.
GET	/districts/:slug	Público	—	PublicDistrictResponse	Agregados e rankings.
GET	/neighborhoods/:slug	Público	—	PublicNeighborhoodResponse	Sem gestão/carteira.
POST	/follows	Autenticado	FollowEntityRequest	FollowEntityResponse	Idempotente.
DELETE	/follows/:targetType/:targetId	Autenticado	—	OperationResponse	Remove follow; cheer independente exige confirmação específica.
POST	/teams/:teamId/cheer	Autenticado	CheerTeamRequest	CheerTeamResponse	Cria follow automaticamente.
DELETE	/teams/:teamId/cheer	Autenticado	RemoveCheerRequest	OperationResponse	Pode manter follow.
GET	/:entityType/:entityId/supporters	Público	PaginationQuery	PublicSupportersResponse	Máx. 10 destaque e lista paginada, sem valores.
GET	/:entityType/:entityId/sponsors	Público	—	PublicSponsorsResponse	Até 3 ativos, ordem randômica controlada.

Autenticação e autorização

• GETs são públicos; optional auth apenas personaliza viewer state.
• Ações follow/cheer/join/report usam AuthIntent quando visitante.
• Statuses suspended/merged/abandoned alteram shape com warning/redirect.

Erros de domínio

Código	HTTP	Quando ocorre	Ação esperada no cliente
ENTITY_NOT_PUBLIC	404	Draft/privado/inexistente	404 neutro.
ENTITY_SUSPENDED	403	Suspensa	Tela de indisponibilidade.
ENTITY_MERGED	308	Unificada	Seguir canonicalUrl.
PRIVACY_RESTRICTED	403	Campo privado	Ocultar seção.
ALREADY_CHEERING	409	Cheer existente	Atualizar viewer state.

Idempotência e concorrência

• Follow/cheer são idempotentes por usuário+target.
• Counters são derivados no backend; o cliente não incrementa como fonte de verdade.

Auditoria e efeitos colaterais

• Follow/cheer geram atividade e notificações conforme preferências, sem expor dados privados.
• Public reads não criam audit log, apenas métricas anônimas/agregadas.

Exemplos

publicTeam

{
  "team": {
    "id": "team_001",
    "slug": "unidos-do-6",
    "name": "Unidos do 6",
    "district": {
      "id": "district_001",
      "name": "São Mateus"
    },
    "categories": [
      {
        "id": "cat_001",
        "name": "Principal"
      }
    ]
  },
  "viewer": {
    "isFollowing": true,
    "isCheering": true,
    "canManage": false
  },
  "warnings": []
}

Mocks

• Fixtures públicas nunca contêm e-mail, telefone privado, documento, saldo ou permission keys.
• Viewer state varia por cenário auth.
• Merged/suspended/abandoned disponíveis.

Testes obrigatórios

• Anonymous read.
• Privacy player/address.
• Cheer creates follow.
• Counters idempotentes.
• Draft hidden.
• Merged redirect.

Critérios de aceite

• Todas as páginas públicas possuem endpoint canônico.
• Ações sociais não exigem reescrever tela entre mock/API.
• DTO público é explicitamente menor que management DTO.

Machine summary

spec: SPEC-API-PUBLIC-001
api_group: API de entidades e páginas públicas
base_path: /api/v1
response_envelope: ApiResponse<T>
ids: string
dates: ISO-8601
money: integer_cents