---
title: "Versionamento e depreciação"
description: "O que é estável no contrato /v1, o que pode mudar sem aviso de versão, e como uma mudança incompatível seria anunciada e convivida."
canonical: "https://cnpj.ia.br/docs/versionamento"
date_modified: 2026-09-02
source: "cnpj.ia.br"
---

docs · base agosto/2026 Atualizado em 02/09/2026

# Versionamento e depreciação

O que é estável no contrato /v1, o que pode mudar sem aviso de versão, e como uma mudança incompatível seria anunciada e convivida.

A versão da API está no caminho: `/v1`. Dentro de `/v1`, o contrato só recebe mudanças aditivas; uma mudança incompatível criaria `/v2`, anunciada no [changelog](https://cnpj.ia.br/docs/changelog) e por e-mail aos titulares de chave, com período de convivência entre as duas versões. Não há header de versão. A versão do documento OpenAPI publicado é 1.0.0-draft.3.

## O que é estável em `/v1`

- Os caminhos e métodos das operações, os nomes dos parâmetros e o significado de cada um.
- Os nomes, tipos e a nulabilidade dos campos da resposta; `null` continua significando ausência de dado, nunca chave omitida.
- O enum de `error.code` e o status HTTP de cada código.
- Os headers `X-Request-Id`, `X-Credits-*`, `X-RateLimit-*` e `Retry-After`.
- A regra de cobrança: só respostas `200` são cobradas, e o peso de cada operação está em [`/precos`](https://cnpj.ia.br/precos).

## O que pode mudar sem nova versão

Mudanças aditivas, sempre registradas no changelog:

- Campo novo na resposta, em qualquer objeto.
- Valor novo em um enum de dados (uma nova situação cadastral, um novo código de motivo). Trate valores desconhecidos como texto e não falhe.
- Código de erro novo, sempre com um status HTTP já existente. Trate código desconhecido como erro genérico.
- Filtro novo na busca, ferramenta nova no MCP, endpoint novo.
- Descrições, exemplos e a documentação.

Clientes robustos ignoram campos que não conhecem e não dependem da ordem das chaves no JSON.

## Como uma mudança incompatível seria feita

Remover ou renomear campo, mudar tipo, mudar o significado de um parâmetro ou o status de um código de erro é incompatível. Se um dia for necessário: a mudança nasce em `/v2`, `/v1` continua respondendo durante um período de convivência mínimo de 90 dias, e o changelog e o e-mail aos titulares de chave anunciam a data de encerramento. Nenhuma mudança incompatível é feita dentro de `/v1`.

## Estado atual do contrato

O documento OpenAPI publicado em [`/openapi/openapi.json`](https://cnpj.ia.br/openapi/openapi.json) está na versão 1.0.0-draft.3. Enquanto o sufixo `draft` existir, o contrato pode receber ajustes antes da abertura pública, todos registrados no changelog; a partir da versão sem sufixo valem as regras acima.

## Relacionados

- [Changelog](https://cnpj.ia.br/docs/changelog).
- [Referência gerada do OpenAPI](https://cnpj.ia.br/docs/referencia): o contrato como está publicado.