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

Esta política vale pra API REST da Certu (/api/v1) e pro servidor MCP, que rodam as mesmas ferramentas. Ela diz o que pode mudar na v1, como sai uma mudança que quebra compatibilidade e como você fica sabendo antes de qualquer coisa ser removida.

Versão atual

A versão atual é a v1, no caminho: https://certu.com.br/api/v1. A versão faz parte do endereço, não de um cabeçalho.
A forma legível por máquina desta política é o objeto x-deprecation-policy do /openapi.json.

O que pode mudar na v1

A v1 só ganha acréscimos: endereços novos, ferramentas novas, parâmetros opcionais novos e campos novos na resposta.
A integração deve ignorar campo de resposta que não conhece; assim um acréscimo nunca quebra nada.

Mudança que quebra compatibilidade

O que quebraria uma integração existente sai num caminho novo, /api/v2, e a v1 continua respondendo como está documentada.
Quebrar é, por exemplo: remover um endereço, uma ferramenta ou um campo da resposta; renomear qualquer um deles; tornar obrigatório um parâmetro opcional; ou mudar o tipo ou o significado de um campo.

Antes de remover ou mudar qualquer coisa na v1

A Certu avisa por e-mail quem tem chave.
Os endereços afetados mandam o cabeçalho Deprecation (RFC 9745), com a data em que passaram a ser descontinuados, e o Sunset (RFC 8594), com a data em que deixam de responder.
Mandam também Link: <https://certu.com.br/docs/versionamento>; rel="deprecation"; type="text/html", que aponta pra esta página.
A operação descontinuada aparece com deprecated: true no /openapi.json, e a resposta 200 dela documenta os três cabeçalhos.
No servidor MCP, um pedido tools/call único pra uma ferramenta descontinuada leva os mesmos cabeçalhos.

Como se antecipar

Registre ou alerte toda resposta que trouxer Deprecation ou Sunset.
Confira deprecated: true no /openapi.json sempre que gerar o cliente de novo.

Como é uma resposta descontinuada

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Deprecation: @<unix-timestamp>
Sunset: <HTTP-date>
Link: <https://certu.com.br/docs/versionamento>; rel="deprecation"; type="text/html"

Os valores entre sinais de menor e maior são exemplos; as datas de verdade vêm com o aviso.

Veja também

Atualizado em 2026-10-08