Versionamento e depreciação

A API é versionada no caminho da URL. A versão estável em produção é a v1:

https://app.syncro.chat/api/v1

Toda integração deve fixar a versão explicitamente na URL. Não existe negociação de versão por header, e não há uma URL "sem versão" que aponte para a mais recente — isso é proposital: uma integração nunca muda de comportamento sozinha.

Estas mudanças só acontecem numa versão nova (v2, v3…):

• Remover ou renomear um endpoint, um campo de resposta ou um parâmetro
• Tornar obrigatório um parâmetro que era opcional
• Alterar o tipo de um campo, ou o código HTTP devolvido num caso já documentado
• Mudar o significado de um valor existente

Estas mudanças são compatíveis e podem ocorrer na v1 sem aviso prévio — a sua integração precisa tolerá-las:

• Acrescentar um endpoint novo
• Acrescentar um campo novo numa resposta
• Acrescentar um parâmetro opcional
• Acrescentar um novo valor a um enum já existente
• Corrigir um comportamento que divergia da documentação

Quando um endpoint ou uma versão entra em depreciação, o aviso chega na própria resposta HTTP, para que um cliente automatizado perceba sem depender de e-mail ou changelog:

Header	Conteúdo
Deprecation	Data em que a depreciação passou a valer (formato HTTP-date), conforme o RFC 9745
Sunset	Data em que o recurso deixa de responder (formato HTTP-date), conforme o RFC 8594
Link	rel="deprecation" apontando para a documentação da alternativa

Exemplo:

HTTP/1.1 200 OK
Deprecation: Wed, 01 Oct 2026 00:00:00 GMT
Sunset: Sun, 01 Mar 2027 00:00:00 GMT
Link: <https://docs.syncro.chat/pt-BR/versioning>; rel="deprecation"

Compromissos:

• Entre o Deprecation e o Sunset há no mínimo 6 meses.
• Uma versão inteira da API só é desligada com no mínimo 12 meses de aviso.
• A operação depreciada também é marcada com deprecated: true na especificação OpenAPI, o que permite detectar a mudança automaticamente no seu CI.
• Nada é removido sem que exista uma alternativa documentada.

• Monitore os headers Deprecation e Sunset nas respostas — é o canal mais confiável.
• Compare periodicamente a especificação OpenAPI com a versão que você integrou; ela é gerada a partir desta documentação e reflete o estado atual.
• O objeto x-deprecation-policy na raiz da especificação aponta para esta página.