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

depends_on: SPEC-DOMAIN-SEARCH-001, SPEC-DOMAIN-RANKING-001, SPEC-DOMAIN-TERRITORY-001

used_by: IS-MVP-03.1, IS-MVP-03.2, IS-MVP-03.3, IS-MVP-12.1, IS-MVP-12.2

API de busca, rankings e território

Descoberta pública neutra, territorial e respeitosa à privacidade.

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	/search	Público	UniversalSearchQuery	UniversalSearchResponse	Tipos, território, pagination.
GET	/search/suggestions	Público	SuggestionQuery	SuggestionsResponse	Curto e rate limited.
GET	/search/teams	Público	TeamSearchQuery	TeamSearchResponse	Filtros completos.
GET	/search/players	Público	PlayerSearchQuery	PlayerSearchResponse	Privacy/status.
GET	/search/matches	Público	MatchSearchQuery	MatchSearchResponse	Data/campo/categoria/status.
GET	/territory/states	Público	—	StatesResponse	Hierarquia.
GET	/territory/cities	Público	stateId	CitiesResponse	Hierarquia.
GET	/territory/districts	Público	cityId/query	DistrictsResponse	Obrigatório no onboarding.
GET	/territory/neighborhoods	Público	districtId/query	NeighborhoodsResponse	Mesmo distrito.
GET	/territory/vocabulary/resolve	Público/auth opcional	TerritoryContextQuery	VocabularyResponse	Override user→district→city→state→default.
GET	/rankings	Público	RankingQuery	RankingResponse	Type, territory, period.
GET	/rankings/top-scorers	Público	TopScorersQuery	TopScorersResponse	Validated/confirmed.
GET	/stats/teams/:teamId	Público	StatsQuery	TeamStatsResponse	Period/categoria/championship.
GET	/stats/torcidas/:torcidaId	Público	StatsQuery	TorcidaStatsResponse	Sem valores financeiros.

Autenticação e autorização

• Público; optional auth para preferências, não para aumentar resultado pago.
• Search index respeita status e privacy.
• Sem sponsor boost.

Erros de domínio

Código	HTTP	Quando ocorre	Ação esperada no cliente
INVALID_SEARCH_FILTER	422	Combinação inválida	Revisar filtros.
TERRITORY_REQUIRED	422	Consulta exige district/context	Selecionar.
RANKING_NOT_AVAILABLE	404	Sem dados suficientes	Empty state.
PRIVATE_PROFILE	404	Player não buscável	Não revelar existência.

Idempotência e concorrência

• GETs cacheáveis por query e version; sem efeitos.
• Ranking snapshots identificados por generatedAt/version.

Auditoria e efeitos colaterais

• Search queries podem gerar métricas agregadas sem registrar termos sensíveis associados ao usuário.
• Ranking generation logs técnicos, não audit de usuário.

Exemplos

search

{
  "items": [
    {
      "id": "team_001",
      "type": "team",
      "title": "Unidos do 6",
      "subtitle": "São Mateus • Principal",
      "publicRoute": "/teams/unidos-do-6",
      "badges": [
        "Ranking #4"
      ]
    }
  ],
  "meta": {
    "pagination": {
      "page": 1,
      "pageSize": 20,
      "totalItems": 1,
      "totalPages": 1
    }
  }
}

ranking

{
  "type": "team_performance",
  "period": "last_90_days",
  "territory": {
    "type": "district",
    "id": "district_001"
  },
  "rows": [
    {
      "position": 1,
      "entityId": "team_001",
      "score": 82.4,
      "status": "confirmed"
    }
  ]
}

Mocks

• Search fixtures indexadas; filters realmente aplicados.
• Rankings provisional/confirmed e periods.

Testes obrigatórios

• Privacy exclusion.
• Suspended hidden.
• Abandoned downrank/badge.
• No paid boost.
• Minimum 3 matches provisional.
• Validated-only.

Critérios de aceite

• Filtros acordados disponíveis.
• Vocabulary resolve corretamente.
• Ranking explica período/território/status.

Machine summary

spec: SPEC-API-DISCOVERY-001
api_group: API de busca, rankings e território
base_path: /api/v1
response_envelope: ApiResponse<T>
ids: string
dates: ISO-8601
money: integer_cents