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

---

📦 Assets (Recursos Territoriais)

TerritoryAssets representam recursos valiosos do território que pertencem ao próprio território (naturais, culturais, comunitários, infraestruturais, simbólicos). TerritoryAssets não são vendáveis e não devem ser tratados como produtos ou serviços. Mídia (foto, vídeo, documento, link) deve ser tratada como registro/evidência associada a um TerritoryAsset, Event ou Post, não como TerritoryAsset em si.

Corpos d'água: rios, córregos, nascentes e fontes entram como assets/recursos naturais curáveis (ponte TerritoryAsset; alvo NaturalAsset na FASE24.0). Ver CORPOS_DAGUA_TERRITORIO. Não embutir no modelo Territory.

Criar Asset (POST /api/v1/assets)

Descrição: Cria um recurso territorial valioso (ex.: trilha, rio, nascente, ponto cultural, infraestrutura comunitária).

Como usar:

• Exige autenticação
• Body: territoryId, type, name, description?, geoAnchors (obrigatório), subtype? (WA-E1)

Exemplo hídrico (ponte):

{
  "territoryId": "...",
  "type": "natural",
  "subtype": "river",
  "name": "Rio do Vale",
  "description": "Trecho urbano",
  "geoAnchors": [{ "latitude": -23.37, "longitude": -45.02 }]
}

Regras de negócio:

• Permissão: Apenas moradores verificados (RESIDENT + ResidencyVerification != NONE) ou curadores podem criar
• Geolocalização: Obrigatória (pelo menos um GeoAnchor)
• Status: Asset é criado como Suggested (aguarda curadoria → Active)
• Subtype (WA-E1): opcional; se informado, type deve ser natural e subtype ∈ river|stream|spring|waterfall|well|potable_water
• Limites: Nome máximo 200 caracteres, descrição máxima 1000 caracteres, subtype máximo 40
• Não vendável: TerritoryAssets não podem ser vendidos ou transferidos via marketplace

Resposta: inclui subtype (nullable) além de type.

Listar Assets (GET /api/v1/assets)

Descrição: Lista assets do território.

Como usar:

• Exige autenticação
• Query params: territoryId (opcional), assetId (filtro), type (filtro), skip, take (paginação)
• Header X-Session-Id para identificar território ativo

Regras de negócio:

• Visibilidade / status canônico: resposta usa status runtime Suggested | Active | Archived | Rejected (curadoria promove Suggested → Active)
• Filtros: assetId e type são opcionais
• Paginação: Padrão 20 itens
• Nota histórica: docs antigos usavam PENDING/VALIDATED como aliases de Suggested/Active

Atualizar Asset (PATCH /api/v1/assets/{assetId})

Subtype (tri-estado, WA-E1):

• propriedade omitida → preserva subtype atual (se type continuar natural)
• "subtype": null → remove subtype
• "subtype": "river" → substitui

Validar Asset (POST /api/v1/assets/{assetId}/validate)

Descrição: Confirmação comunitária / curadoria auxiliar (não confundir com status Active).

Como usar:

• Exige autenticação
• Path param: assetId

Regras de negócio:

• Permissão: conforme política de curadoria do território
• Status canônico: aprovação de curadoria (Curate) muda para Active; confirmações incrementam contagem de validações
• Idempotente: Pode validar múltiplas vezes
• Contagem: Assets retornam contagem de validações e percentual

---

📚 Documentação Relacionada

• Mapa Territorial - Assets aparecem como pins no mapa
• Marketplace - Assets NÃO são vendáveis (diferenciação importante)
• Regras de Visibilidade - Visibilidade de assets

---

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