Versionamento e descontinuação

Esta página diz o que você pode esperar quando as APIs públicas da Zabit mudam, e o que o seu código precisa tolerar para não quebrar quando isso acontece.

Como as versões são numeradas

Cada API segue versionamento semântico (MAJOR.MINOR.PATCH):

Parte	Onde aparece	Quando muda
Maior (v1)	No caminho da API: /kyc/v1, /party/v1	Só em mudança incompatível
Menor e correção (1.5.1)	No contrato OpenAPI, em info.version (mostrada na referência)	Menor: recurso novo compatível. Correção: ajuste de texto ou de comportamento sem efeito no contrato

Enquanto a versão maior for v1, o caminho não muda. As versões menores e as correções chegam sem que você precise alterar nada.

O que muda sem aviso prévio (compatível)

Estas mudanças podem acontecer a qualquer momento dentro de uma versão maior. Elas não exigem aviso, mas o seu código precisa tolerá-las:

• novos endpoints;
• novos campos opcionais nas requisições;
• novos campos nas respostas;
• novos valores em campos que listam opções (enums);
• novos tipos de evento de webhook;
• novos cabeçalhos opcionais, de requisição ou de resposta.

Na prática, isto significa:

• ignore campos desconhecidos ao ler uma resposta ou um evento, em vez de recusá-los;
• trate listas de valores (como match_basis ou status) como abertas: um valor que você não conhece não pode derrubar o seu processamento;
• ignore, em vez de falhar, um type de webhook que o seu código não trata.

O que é mudança incompatível

É incompatível tudo o que pode fazer um cliente que seguiu o contrato deixar de funcionar:

• remover ou renomear um campo ou um endpoint;
• mudar o tipo de um campo;
• tornar obrigatório um campo que era opcional;
• mudar a forma de autenticação;
• mudar o significado de um erro (o status ou o error.code).

Mudança incompatível só entra em uma nova versão maior (por exemplo, /kyc/v2), nunca dentro de v1. Ela é anunciada nesta documentação com um aviso "Ação necessária" que diz o que fazer.

Descontinuação

Antes de uma versão maior deixar de funcionar, você recebe aviso e tempo para migrar:

1. A nova versão (v2) é publicada e a antiga (v1) é marcada como descontinuada, com aviso nesta documentação e na página da API.
2. As duas versões funcionam lado a lado durante o período de descontinuação, que é de, no mínimo, 6 meses a partir do aviso.
3. Só depois desse prazo a versão antiga é removida, o que também é anunciado nesta documentação.

Exceção: correções de segurança

Uma correção de vulnerabilidade pode entrar em vigor antes de qualquer prazo, quando esperar expuser você ou os dados dos seus clientes. Nesse caso, o aviso sai nesta documentação, com o que mudou e o que fazer.

Como acompanhar

• Confira a versão do contrato (info.version) na página de cada API.