Parte de: API Arah - Lógica de Negócio e Usabilidade
Versão: 2.0
Data: 2025-01-20

---

🗺️ Mapa Territorial

Listar Entidades do Mapa (GET /api/v1/map/entities)

Descrição: Obtém entidades (estabelecimentos, espaços públicos, etc.) do território.

Como usar:

• Exige autenticação
• Query params: territoryId (opcional, usa território ativo se não informado)
• Header X-Session-Id para identificar território ativo

Regras de negócio:

• Visibilidade:
  • Visitantes: Veem apenas entidades PUBLIC
  • Moradores validados: Veem entidades PUBLIC e RESIDENTS_ONLY
• Bloqueios: Entidades de usuários bloqueados não aparecem
• Status: Apenas entidades com status VALIDATED ou SUGGESTED são retornadas

Sugerir Entidade (POST /api/v1/map/entities)

Descrição: Sugere uma nova entidade territorial (estabelecimento, espaço público, etc.).

Como usar:

• Exige autenticação
• Body: nome, categoria, latitude, longitude, visibilidade (PUBLIC, RESIDENTS_ONLY)

Regras de negócio:

• Permissão: Visitantes e moradores podem sugerir
• Geolocalização: Obrigatória
• Status: Entidade é criada como SUGGESTED (aguarda validação)
• Categoria: Tipos válidos: "estabelecimento", "espaço público", "espaço natural", etc.

Validar Entidade (PATCH /api/v1/map/entities/{entityId}/validation)

Descrição: Valida ou rejeita uma entidade sugerida (curadoria).

Como usar:

• Exige autenticação
• Path param: entityId
• Body: validated=true ou validated=false

Regras de negócio:

• Permissão: Apenas curadores (usuários com role CURATOR) podem validar
• Status: Se validada, status muda para VALIDATED
• Idempotente: Pode validar múltiplas vezes sem efeito adicional

Confirmar Entidade (POST /api/v1/map/entities/{entityId}/confirmations)

Descrição: Confirma uma entidade no mapa (marcar como relevante).

Como usar:

• Exige autenticação
• Path param: entityId
• Query param: territoryId (obrigatório)

Regras de negócio:

• Permissão: Todos usuários autenticados podem confirmar
• Idempotente: Múltiplas confirmações são contabilizadas uma vez por usuário
• Contagem: Entidades retornam contagem de confirmações

Relacionar-se com Entidade (POST /api/v1/map/entities/{entityId}/relations)

Descrição: Relaciona um morador com uma entidade (ex: "sou morador deste estabelecimento").

Como usar:

• Exige autenticação
• Path param: entityId

Regras de negócio:

• Permissão: Apenas moradores verificados (RESIDENT + ResidencyVerification != NONE) podem se relacionar
• Idempotente: Relação é única por usuário/entidade
• Uso: Usado para identificar moradores vinculados a entidades específicas

Obter Pins do Mapa (GET /api/v1/map/pins)

Descrição: Obtém todos os pontos georreferenciados do território (entidades, posts, eventos, assets, alertas).

Como usar:

• Exige autenticação
• Query params:
  • territoryId (opcional, usa território ativo se não informado)
  • types (CSV opcional: entity, post, event, asset, alert, media)
  • assetId (opcional — restringe a um asset)
  • assetTypes (CSV opcional — no mapa casa com Type ou Subtype; legado + WA-E2)
  • assetSubtypes (CSV opcional — casa apenas com Subtype; ex.: river,stream,spring)
• Header X-Session-Id para identificar território ativo

Regras de negócio:

• Visibilidade: Respeita regras de visibilidade de cada tipo de conteúdo
• Assets no mapa: apenas status Active (após curadoria)
• Retorno: coordenadas, IDs, tipo de pin, título; para assets também assetType e assetSubtype
• Sensibilidade: omitir HIGH/RESTRICTED ainda não aplica na ponte TerritoryAsset (acompanhamento FASE24.0 / AC-WA-4)
• Nota: GET /api/v1/assets?types= continua filtrando só por Type (não por Subtype)

Obter Pins do Mapa Paginados (GET /api/v1/map/pins/paged)

Descrição: Obtém pins do mapa com paginação.

Como usar:

• Exige autenticação
• Query params: mesmos de /pins + pageNumber (padrão: 1), pageSize (padrão: 20)
• Header X-Session-Id para identificar território ativo

Regras de negócio:

• Paginação: Padrão 20 itens por página
• Visibilidade: Respeita regras de visibilidade de cada tipo de conteúdo
• Filtros: types / assetTypes / assetSubtypes como em /pins
• Retorno: PagedResponse<MapPinResponse> com metadados de paginação

---

📚 Documentação Relacionada

• Feed Comunitário - Posts podem referenciar entidades do mapa
• Eventos - Eventos aparecem como pins no mapa
• Assets - Assets aparecem como pins no mapa
• Alertas - Alertas aparecem como pins no mapa
• Regras de Visibilidade - Visibilidade de entidades
• Corpos d'água - WA-E2 filtros hídricos

---

Voltar para: Índice da Documentação da API