Versionamento

A API pública usa versionamento na URL, só pelo major. A versão atual — e a única — é a v1, presente em toda rota:

https://api.maestron.com.br/api/v1

A regra

• A URL não muda enquanto a API só cresce. Endpoint novo, campo novo, valor de enum novo: tudo isso entra na v1 sem aviso e sem trocar a URL.
• A URL só mudaria (/v2) se algo fosse quebrado — um campo removido, um tipo alterado, o envelope reestruturado. Nunca aconteceu, e não há /v2 planejado.
• Não existe negociação de versão por header nem por query string. O único identificador de versão é o segmento /v1.

Cada mudança retrocompatível é registrada no Changelog, em ordem cronológica.

O que muda dentro da v1 sem aviso

Sua integração precisa tolerar, sem quebrar:

• Novos endpoints.
• Novos campos opcionais no corpo de uma requisição.
• Novos campos nos objetos de resposta.
• Novos valores em enums existentes (ex.: um novo status de negócio no catálogo de um funil).
• Novos parâmetros de query opcionais.

Cuidado

Trate campos desconhecidos na resposta como aceitáveis e ignore-os. Uma integração que rejeita um campo extra quebra na primeira adição retrocompatível.

O que exigiria um novo major

• Remoção ou renomeação de um endpoint, campo ou parâmetro existente.
• Mudança do tipo de um campo existente.
• Tornar obrigatório um campo hoje opcional.
• Mudança da estrutura do envelope de sucesso ou de erro.

Se um /v2 for lançado algum dia, ele terá a própria URL, a v1 continuará respondendo durante uma janela de transição anunciada com antecedência, e tudo isso estará no Changelog. Enquanto isso não existe, trate /api/v1 como estável.

Headers de depreciação

Quando uma versão entrar em depreciação, a janela de transição é anunciada por máquina, em toda resposta dessa versão, com os headers padrão da RFC 8594:

Header	Conteúdo	Significa
Deprecation	true ou uma data HTTP	A versão está depreciada (desde a data, se informada).
Sunset	uma data HTTP	A partir dela a versão para de responder.
Link	<url>; rel="sunset"	Aponta para o Changelog com o guia de migração.

Deprecation: Sat, 01 Nov 2025 00:00:00 GMT
Sunset: Wed, 31 Dec 2025 23:59:59 GMT
Link: <https://developers.maestron.com.br/pt-br/changelog/>; rel="sunset"

Dica

Logue ou alerte quando uma resposta trouxer Sunset — é o sinal de que você tem até aquela data para migrar. Hoje a v1 não emite nenhum desses headers; eles só passam a aparecer se e quando uma versão for depreciada.

Para os códigos de status, consulte Erros. Para os limites de requisição, consulte Rate limiting.