> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usecroma.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Versionamento e descontinuação

> Como a API do Croma é versionada, o que pode mudar sem aviso e como a aposentadoria de um endpoint é anunciada.

Agentes se integram uma vez e depois rodam sem supervisão, então o contrato
precisa dizer de antemão o que pode mudar e com quanto aviso.

## Versionamento

Cada caminho carrega a sua versão maior: `/co/rues/entity-by-nit/v1`,
`/pe/sunat/ruc/v1`, `/global/web-search/v1`. A versão faz parte do caminho,
não de um cabeçalho, de modo que uma solicitação é inequívoca por si só e a
descrição OpenAPI em `https://api.croma.run/openapi` (também em
`https://usecroma.com/openapi.json`) lista todas as versões em serviço.

Dentro de uma versão maior o contrato só cresce. Estas mudanças saem sem nova
versão e sem aviso:

* Novos endpoints, novos campos opcionais na solicitação, novos campos na
  resposta.
* Novos valores em campos documentados como conjuntos abertos (status, nomes e
  termos jurídicos no idioma da fonte).
* Novas fontes atrás de um endpoint existente, quando a forma da resposta não
  muda.

Estas mudanças quebram o contrato e exigem um novo caminho maior (`/v2`):

* Remover ou renomear um campo de solicitação ou de resposta.
* Mudar o tipo ou o significado de um campo.
* Tornar obrigatório um campo de solicitação opcional.
* Mudar um `code` de erro ou o envelope de erro.

Os nomes de campo são `snake_case` em inglês em todos os endpoints, e todo
endpoint aceita um cabeçalho opcional
[`Idempotency-Key`](/pt/rate-limits#tentativas-e-idempotência); essas
convenções também fazem parte do contrato.

## Descontinuação

Quando uma versão de um endpoint é programada para remoção:

1. Ela é anunciada no [changelog](https://usecroma.com/en/changelog) (e no seu
   [feed Atom](https://usecroma.com/changelog/atom.xml)) com pelo menos **90
   dias** de antecedência da data de remoção, nomeando o sucessor.
2. A partir do anúncio, cada resposta do endpoint em remoção carrega um
   cabeçalho `Deprecation` ([RFC 9745](https://www.rfc-editor.org/rfc/rfc9745))
   com a data em que a descontinuação entrou em vigor, um cabeçalho `Sunset`
   ([RFC 8594](https://www.rfc-editor.org/rfc/rfc8594)) com a data de remoção e
   um cabeçalho `Link` com `rel="successor-version"` apontando para o
   substituto.
3. A descrição OpenAPI marca a operação com `deprecated: true` e a sua
   descrição nomeia o sucessor.
4. Após a data de remoção, o caminho responde `410 Gone` com o envelope de erro
   padrão (`code: "endpoint_retired"`) e o mesmo cabeçalho `Link`, por pelo
   menos mais 90 dias.

Hoje nenhum endpoint está descontinuado, então nenhuma resposta carrega esses
cabeçalhos ainda; um cliente que observe `Deprecation` e `Sunset` em cada
resposta saberá de uma remoção no dia em que for anunciada.

## O que isto não cobre

* O conteúdo dos dados. O Croma devolve os registros oficiais como são
  publicados; uma fonte mudar o que publica não é uma mudança da API. Cada guia
  anota os limites da própria fonte.
* Os limites de taxa e cotas, que são por organização e podem mudar com o seu
  plano. São reportados em cada resposta; veja [Limites de taxa](/pt/rate-limits).
* O servidor MCP negocia a sua versão de protocolo conforme o Model Context
  Protocol; os nomes das ferramentas seguem os ids dos endpoints
  (`rues_entity_by_nit`) e compartilham o calendário de descontinuação dos
  endpoints por trás delas.