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.2.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.1.0 -> 1.2.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.
• Marcar um campo existente como deprecado — dentro da serie 1.x o campo continua aceito e continua sendo devolvido; muda so a recomendacao de qual nome usar. A REMOCAO dele, essa sim, e breaking e so acontece na proxima versao MAIOR. Ver Campos deprecados.

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.

Campos deprecados: o que "deprecado" significa aqui

Um campo pode ser marcado como deprecado sem sair do contrato. No openapi.json ele carrega o prefixo [DEPRECATED — use <nome novo>] na propria descricao, junto do nome que o substitui.

Neste produto, deprecar tem um significado unico e explicito:

Um campo deprecado continua aceito nos requests e devolvido nas responses em TODA a serie 1.x, e e REMOVIDO na versao 2.0 — uma mudanca MAIOR, publicada em uma nova versao de URL (/v2) e anunciada no Changelog.

Ou seja: deprecado hoje = removido na proxima versao MAIOR. Nao ha meio termo, e nao ha remocao dentro da 1.x. A garantia e de versao, nao de calendario — nao existe data de corte publicada e nao vamos publicar uma. O que nao pode acontecer e o campo sumir antes da 2.0.

Enquanto os dois nomes convivem na 1.x, eles carregam o mesmo valor: a troca e de nome, nunca de numero nem de semantica.

Consequencia pratica para o seu roadmap: ver um [DEPRECATED] num campo que voce le hoje nao e um incidente e nao exige acao no mesmo dia — a 1.x inteira continua funcionando. Mas e um item de backlog com destino certo: na 2.0 o campo nao existe mais. Migre campo a campo, no seu ritmo, antes de adotar a 2.0. Enquanto voce estiver na 1.x, nada quebra.

Tabela de migracao para a 2.0

O que esta deprecado hoje, e para onde migrar antes de adotar a 2.0:

Pacote	Nomes que SAEM na 2.0	Para onde migrar
Vocabulario de valores (*_future_value / *_present_value)	gross_face_value, net_face_value, requested_advance_value, discounted_value, discount_brl, liquid_value e os equivalentes opr_*	de-para campo a campo em Valores do Recebivel

Nos webhooks vale a mesma regra para o payload entregue: na 1.x o nome canonico e o deprecado viajam lado a lado; na 2.0 os eventos passam a sair so com o canonico. Uma ressalva propria da entrega assincrona esta em Eventos — eventos GERADOS antes da mudanca e reentregues na janela de re-tentativa trazem so o nome antigo, porque o payload e o que foi registrado na emissao.

Spec congelado de cada versao

O openapi.json e sempre o spec vigente e acompanha a release atual (1.6.0). Alem dele, algumas versoes tem um spec congelado, imutavel, publicado no proprio dominio:

Versao	Spec congelado
1.1.0	openapi-v1.1.0.json — piso historico da serie 1.x
1.2.0	ainda nao congelado — use o openapi.json
1.3.0	ainda nao congelado — use o openapi.json
1.4.0	ainda nao congelado — use o openapi.json
1.5.0	ainda nao congelado — use o openapi.json
1.5.1	ainda nao congelado — use o openapi.json
1.6.0 (vigente)	openapi-v1.6.0.json — piso de compatibilidade atual

Fixe um spec congelado nas suas ferramentas (geradores de SDK, mocks, testes de contrato) quando quiser um alvo que nao muda sob seus pes. Congelar uma versao e um ato deliberado, nao automatico: nem toda release ganha snapshot no dia em que sai. O que garante a sua compatibilidade nesse intervalo e o gate: a cada mudanca ele compara o spec vigente com o snapshot congelado mais recente (hoje o da 1.6.0) e recusa remocoes e estreitamentos, deixando passar so o que e retrocompativel.

Congelar uma versao nova, portanto, move o piso para ela — e por isso o ato nao e automatico: ele so acontece com decisao explicita de release, registrada no Changelog, e exige uma reancoragem manual fora do repositorio. Os snapshots anteriores continuam publicados, imutaveis, como registro do que foi prometido em cada versao: comparar-se com um deles e sempre possivel do seu lado. Nenhuma republicacao silenciosa reescreve nenhum deles.

Acompanhe as mudancas

• Changelog — historico de mudancas que afetam a integracao de API.
• Especificacao OpenAPI — fonte canonica do contrato (/openapi.json).