Politica de Versionamento
Versao na URL (/v1)
Todos os endpoints publicos vivem sob o prefixo /v1. Esse numero so muda
em uma quebra de compatibilidade (breaking change): nesse caso, uma nova
versao (/v2) e publicada e a anterior entra em periodo de descontinuacao
anunciado com antecedencia. Sua integracao nao quebra por mudancas dentro
da mesma versao.
Versao da release (X-Zemo-API-Version)
Toda resposta inclui o header X-Zemo-API-Version (ex.: 1.0.0), seguindo
SemVer para a release da API:
| Parte | Significa | Exemplo |
|---|---|---|
| MAJOR | Quebra de compatibilidade (nova versao na URL) | 1.x.x -> 2.0.0 |
| MINOR | Recurso novo, retrocompativel | 1.0.0 -> 1.1.0 |
| PATCH | Correcao retrocompativel | 1.0.0 -> 1.0.1 |
O que e retrocompativel (NAO quebra)
Mudancas que podem ocorrer sem aviso de breaking change — sua integracao deve toleras-las:
- Novos endpoints ou novos campos opcionais em requests.
- Novos campos em responses (ignore os que nao conhece).
- Novos valores em enums nao criticos e novos codigos de erro.
- Novos eventos de webhook.
Programe defensivamente: nao falhe ao receber campos desconhecidos e trate enums abertos com um caso
default.
O que e breaking change (quebra)
- Remover/renomear campos ou endpoints.
- Tornar um campo opcional em obrigatorio.
- Alterar tipo, formato ou semantica de um campo existente.
- Remover valores de enum ou alterar codigos HTTP de respostas existentes.
Breaking changes sao publicados em uma nova versao de URL e comunicados no Changelog (marcados como BREAKING CHANGE) com um periodo de transicao.
Acompanhe as mudancas
- Changelog — historico de mudancas que afetam a integracao M2M.
- Especificacao OpenAPI — fonte canonica do contrato (
/openapi.json).