Skip to main content
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; 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 (e no seu feed Atom) 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) com a data em que a descontinuação entrou em vigor, um cabeçalho Sunset (RFC 8594) 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.
  • 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.