Versionamento

A API é versionada via Asp.Versioning. A versão faz parte do caminho da rota.

Como funciona

/v1/atividades    →  versão 1
/v2/atividades    →  versão 2
/v3/ocorrencias   →  versão 3

Cobertura por versão

Versão	Escopo
v1	Superfície principal — cadastro, ativos, atividades, relatórios, usuários, almoxarifado. Não há v1 de ocorrências na documentação: use a v3.
v2	Complementa a v1 onde não há v3: baixa de atividades em lote, consulta de referências de filtro de ocorrências e alguns lookups (Áreas, Equipamentos, Unidades, Prioridades).
v3	Ocorrências e Correções — domínios mais evoluídos.

Estratégia de evolução

As versões mais novas concentram-se nos domínios mais quentes — Ocorrências e Correções. Recursos de cadastro permanecem majoritariamente em v1.

Como a lógica de negócio vive na camada de service (não nos controllers), o mesmo comportamento costuma ser compartilhado entre versões. Exemplo: a validação de ocorrência típica protege POST /v2/ocorrencias e POST /v3/ocorrencias simultaneamente.

Recomendação

• Para ocorrências e correções, use sempre v3. Só recorra à v2 quando não existir equivalente em v3 (hoje: GET /v2/ocorrencias/filtrorefs).
• Nunca use /v1/ocorrencias em integrações novas — essa rota não faz parte da documentação e não deve ser usada por clientes externos.
• Para os demais recursos, use v1 (ou a v2 indicada acima, quando existir).
• Sempre fixe a versão explicitamente na URL; não dependa de default.