# Política de versionamento e descontinuação da API EmpresAqui

## Versionamento

A API pública do EmpresAqui usa versionamento no caminho. A versão estável atual é a `v1`, publicada em `/api/v1/consulta`. Mudanças incompatíveis serão publicadas em uma nova versão, como `/api/v2/consulta`; uma versão existente não muda de forma incompatível sem uma nova versão.

A rota legada `/acesso/RetornoJson.php` permanece compatível durante a transição para `/api/v1/consulta`. Novas integrações devem usar a rota versionada e o contrato disponível em `/openapi.json`.

## Deprecation e Sunset

Quando uma rota ou versão entrar em descontinuação, o EmpresAqui publicará o aviso nesta página e na documentação da API. A rota legada `/acesso/RetornoJson.php` está em descontinuação, tem como sucessora `/api/v1/consulta` e possui encerramento planejado para 30 de junho de 2027. Respostas da rota legada informam `Deprecation: true`, `Sunset: Wed, 30 Jun 2027 00:00:00 GMT` e o link `rel="successor-version"`. O prazo mínimo de aviso para novas descontinuações será de 90 dias.

Durante o período de transição, o contrato continuará disponível e a documentação indicará a rota sucessora. Clientes devem migrar antes da data informada em `Sunset` e não devem depender de uma rota marcada como `Deprecation` para novas integrações.

## Resiliência para agentes

Agentes devem consultar o OpenAPI antes de montar chamadas, tratar respostas `application/problem+json`, respeitar `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset` e aguardar `Retry-After` quando receberem HTTP 429.